cajonzero 0.1.3 → 0.2.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Toby Lai
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Toby Lai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,7 +1,7 @@
 # cajonzero
 
 运行在 Cloudflare 上的 BOX3 游玩端引擎：内置账号系统，每个房间是一个
-Durable Object，地图存放在 OSS/CDN。
+Durable Object，地图默认随 worker 作为静态资源部署（也可改 CDN）。
 
 ## 安装
 
@@ -42,70 +42,53 @@ npm run deploy
 `cj0 setup` 会把 KV namespace id 写进 `wrangler.jsonc`；如果当时没有登录
 wrangler，也可以手动运行 `npx wrangler kv namespace create <name> --update-config --binding CAJONZERO_KV`。
 
-## 配置地图
-
-地图文件单独上传，不随 worker 打包。把解包后的 `.boxplay` 目录上传到
-OSS/S3/CDN（需允许 CORS），然后在 `cajonzero/maps.json` 中登记：
-
-```json
-{
-  "version": 1,
-  "maps": [
-    {
-      "slug": "race",
-      "root": "https://<你的 CDN>/box3/race/",
-      "worldId": "<世界 id>",
-      "name": "显示名"
-    }
-  ]
-}
-```
-
-`root` 必须以 `/` 结尾；更新地图后刷新 CDN 缓存或改用带版本的路径。
-房间参数、地图拉取策略等配置位于 `cajonzero/config.json`。
-
-### 预计算 seed（强烈建议）
-
-默认情况下房间启动会沿着 `bundle.json` → manifest → 每个 blob 逐个拉取，一张真实地图
-会产生 100+ 次子请求。Cloudflare Workers 免费版单次调用只有 50 个子请求 / 10ms CPU，
-线上会直接起不来（本地 `wrangler dev` 不限制，所以看起来正常）。
+## 导入地图
 
-`cj0 worker build-seed` 在本地把每张图解析一次，把单文件 seed pack 写进 **worker 的静态资源目录**
-（`dist/ui/seed/<slug>.json.gz`），随 `wrangler deploy` 一起上传，不需要改 CDN、不写 KV/R2：
+地图在本地从 `.boxplay` 导入，写进项目的 `public/`，随 worker 一次部署：
 
 ```bash
-cj0 worker build-seed            # 所有地图；也可只传 slug
-# seeded race: 155 bodies, 64 voxel chunks, 52 meshes -> dist/ui/seed/race.json.gz (38.2 KB)
-# seed assets: dist/ui/seed (served at /seed/<slug>.json[.gz])
+npx cj0 add ./race.boxplay                 # 解包到 public/maps/race/
+npx cj0 update race ./race-v2.boxplay      # 覆盖已有 slug
+npx cj0 list                               # catalog + 本地导入状态
+npx cj0 remove race                        # 删除地图、私有脚本、catalog
 ```
 
-之后房间启动变成 **1 次 assets 读取**，不再遍历项目图。生成的部署项目脚本已经包含这一步：
+`add/update` 会一次性完成：
 
-```json
-"dev":    "cj0 worker prepare && wrangler dev",
-"deploy": "cj0 worker prepare && cj0 worker build-seed --force && wrangler deploy"
-```
+1. 公开地图资源写到 `public/maps/<slug>/`（`bundle.json`、`worlds/...`）；
+2. 在本地解析世界图，写出 `public/maps/<slug>/seed.json.gz`，房间启动只读这一个文件；
+3. **服务端脚本**写到 `cajonzero/private/<slug>.json.gz`，不会进入公开的
+   `public/`；客户端脚本仍会保留在地图目录里；
+4. 在 `cajonzero/maps.json` 写入 `"root": "/maps/<slug>/"`，并把服端脚本文件记录为
+   `"scriptsFile": "cajonzero/private/<slug>.json.gz"`（该目录会提交，CF 构建时 `cj0 deploy` 可上传）。
 
-`cj0 worker prepare` 会保留 `seed/` 目录；`deploy` 强制重建，避免地图内容更新但 `version`
-没变时继续用旧 pack（`maps.json` 的 `version` / `etag` / `root` 变化也会触发重建）。
+`seed` 在 `add/update` 时构建，不再有独立的 build/seed 步骤。`cj0 update` 默认保留
+你手工改成 CDN 绝对地址的 `root`；`--reset-root` 可恢复为 `/maps/<slug>/`。
 
-如果你更想把 pack 放在地图 CDN 上（不改 worker），也可以用：
+### 使用独立 CDN
 
-```bash
-cj0 maps pack race    # 生成 race.seed.json.gz，手动上传到 <root>/seed.json.gz
-```
+如果不想把地图放进 worker 的静态资源，把对应条目的 `root` 改成
+`https://<你的 CDN>/box3/race/` 即可（需允许 CORS）。运行时会自动走 HTTP 读取；
+`seed.json.gz` 也放在同一个 root 下即可。
+
+> Worker 静态资源限制：免费版 20,000 文件 / 单文件 25 MiB，付费版 100,000 文件。
+> 超出时改用 CDN。
 
-两种来源都会自动识别，缺省时回退到逐文件解析。
+房间参数、地图拉取策略等配置位于 `cajonzero/config.json`。服务端脚本由
+`cj0 deploy` 上传到 KV（`CAJONZERO_SCRIPTS`，缺省回退 `CAJONZERO_KV`）。
 
 ## 常用命令
 
 ```bash
-cj0 create <folder>                         # 生成部署项目
-cj0 setup [--config <file>]                 # 配置 ENV + KV namespace（id）
-cj0 maps pack <slug>                        # 预计算 seed 文件（上传到 CDN）
-cj0 worker build-seed [slug...]             # 预计算 seed 并写进 worker assets
-cj0 serve [--port <port>] [--host <host>]   # 本地启动
-cj0 worker prepare [--config <file>]        # 把包内 UI 同步到 assets.directory
-npm test                                    # 运行测试
-npm run ci:gates                            # 完整检查（类型/测试/构建）
+cj0 create <folder>                          # 生成部署项目（并同步 UI 到 public/）
+cj0 setup [--config <file>]                  # 配置 ENV + KV namespace（id）
+cj0 add <file.boxplay> [--slug <slug>]       # 导入地图
+cj0 update <slug> <file.boxplay>             # 替换地图
+cj0 list [--json]                            # 查看地图 catalog
+cj0 remove <slug>                            # 删除地图
+cj0 sync [--config <file>]                   # 把包内 UI 同步到 public/
+cj0 deploy [--config <file>]                 # 同步 UI + 上传脚本 + wrangler deploy
+cj0 serve [--port <port>] [--host <host>]    # 本地启动
+npm test                                     # 运行测试
+npm run ci:gates                             # 完整检查（类型/测试/构建）
 ```