cajonzero 0.1.2 → 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）。
 
 ## 安装
 
@@ -26,47 +26,69 @@ npm run demo      # http://127.0.0.1:8787
 npx cj0 create my-server
 cd my-server
 npm install
-npx cj0 setup     # 交互配置 ENV：vars 写 wrangler.jsonc，密钥写 .dev.vars
+npx cj0 setup     # 交互配置 ENV + KV namespace
 npm run dev
 ```
 
 ## 部署
 
 ```bash
-npx wrangler kv namespace create CAJONZERO_KV     # 把返回的 id 填进 wrangler.jsonc
+npx cj0 setup                                     # vars/密钥/KV（可自动创建 KV namespace）
 npx wrangler secret put CAJONZERO_SESSION_SECRET  # 会话签名密钥
 npx wrangler secret put BOX_PLAY_ADMIN_TOKEN      # 管理后台令牌
 npm run deploy
 ```
 
-## 配置地图
-
-地图文件单独上传，不随 worker 打包。把解包后的 `.boxplay` 目录上传到
-OSS/S3/CDN（需允许 CORS），然后在 `cajonzero/maps.json` 中登记：
-
-```json
-{
-  "version": 1,
-  "maps": [
-    {
-      "slug": "race",
-      "root": "https://<你的 CDN>/box3/race/",
-      "worldId": "<世界 id>",
-      "name": "显示名"
-    }
-  ]
-}
+`cj0 setup` 会把 KV namespace id 写进 `wrangler.jsonc`；如果当时没有登录
+wrangler，也可以手动运行 `npx wrangler kv namespace create <name> --update-config --binding CAJONZERO_KV`。
+
+## 导入地图
+
+地图在本地从 `.boxplay` 导入，写进项目的 `public/`，随 worker 一次部署：
+
+```bash
+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
 ```
 
-`root` 必须以 `/` 结尾；更新地图后刷新 CDN 缓存或改用带版本的路径。
-房间参数、地图拉取策略等配置位于 `cajonzero/config.json`。
+`add/update` 会一次性完成：
+
+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` 可上传）。
+
+`seed` 在 `add/update` 时构建，不再有独立的 build/seed 步骤。`cj0 update` 默认保留
+你手工改成 CDN 绝对地址的 `root`；`--reset-root` 可恢复为 `/maps/<slug>/`。
+
+### 使用独立 CDN
+
+如果不想把地图放进 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
-cj0 serve [--port <port>] [--host <host>]   # 本地启动
-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                             # 完整检查（类型/测试/构建）
 ```