cajonzero 0.1.1 → 0.1.3

package/README.md

@@ -10,39 +10,42 @@ npm install cajonzero
 npx cj0 --help
 ```
 
-## 本地运行
+## 本地运行（本仓库）
 
 ```bash
 npm install
 npm run build     # 构建大厅与管理后台
-npm run demo      # 启动在 http://127.0.0.1:8787
+npm run demo      # http://127.0.0.1:8787
 ```
 
-打开页面，注册账号后选择地图即可进入房间。
-管理后台地址是 `/admin/login`，演示环境的令牌为 `cajonzero-demo-admin-token`。
+管理后台地址 `/admin/login`，演示令牌 `cajonzero-demo-admin-token`。
 
-## 创建自己的服务
+## 创建项目
 
 ```bash
-cj0 create my-server
+npx cj0 create my-server
 cd my-server
 npm install
-npm run dev       # 本地预览
+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
 ```
 
+`cj0 setup` 会把 KV namespace id 写进 `wrangler.jsonc`；如果当时没有登录
+wrangler，也可以手动运行 `npx wrangler kv namespace create <name> --update-config --binding CAJONZERO_KV`。
+
 ## 配置地图
 
-地图文件需要单独上传，不随 worker 打包。把解包后的 `.boxplay` 目录上传到
-OSS/S3/CDN，然后在 `cajonzero/maps.json` 中登记：
+地图文件单独上传，不随 worker 打包。把解包后的 `.boxplay` 目录上传到
+OSS/S3/CDN（需允许 CORS），然后在 `cajonzero/maps.json` 中登记：
 
 ```json
 {
@@ -58,17 +61,51 @@ OSS/S3/CDN，然后在 `cajonzero/maps.json` 中登记：
 }
 ```
 
-地图文件由客户端和房间直接向 CDN 拉取，服务端不做缓存。
-更新地图后请刷新 CDN 缓存，或改用带版本的路径。
+`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：
+
+```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])
+```
+
+之后房间启动变成 **1 次 assets 读取**，不再遍历项目图。生成的部署项目脚本已经包含这一步：
+
+```json
+"dev":    "cj0 worker prepare && wrangler dev",
+"deploy": "cj0 worker prepare && cj0 worker build-seed --force && wrangler deploy"
+```
+
+`cj0 worker prepare` 会保留 `seed/` 目录；`deploy` 强制重建，避免地图内容更新但 `version`
+没变时继续用旧 pack（`maps.json` 的 `version` / `etag` / `root` 变化也会触发重建）。
+
+如果你更想把 pack 放在地图 CDN 上（不改 worker），也可以用：
+
+```bash
+cj0 maps pack race    # 生成 race.seed.json.gz，手动上传到 <root>/seed.json.gz
+```
+
+两种来源都会自动识别，缺省时回退到逐文件解析。
+
 ## 常用命令
 
 ```bash
-cj0 serve [--port <port>] [--host <host>]   # 本地启动
 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                            # 完整检查（类型/测试/构建）
 ```
-
-详细说明见 [`docs/`](./docs/)。