ArenaPro CLI（APC）

APC 是 BOX Creator 的本地开发命令行工具。它负责连接 Creator、生成并绑定 TypeScript/Vite 工程、同步资源声明、上传客户端和服务端脚本、控制地图的预览运行并订阅实时控制台，也能截取当前打开的编辑场景。

它不保存服务器地址或 Token 到工程目录：工程只绑定 Profile 名称和永久地图 ID；连接地址与 Token 只保存在当前用户电脑的私密 APC 配置中。

安装与术语

npm install -g @box3lab/arenapro-cli
apc --help

• Profile：一个 Creator 服务器连接，包含名称、Creator 地址和本机私密 Token。
• 永久地图 ID：地图的稳定 ID，不是地图名称、版本号或资源 hash。
• 预览运行：Creator 编辑器中“运行 / 停止”操作对应的同一个地图运行状态；APC 不会新建独立运行时。
• Bundle：dao3.config.ts 中的一个脚本入口，可同时拥有客户端和服务端入口。

首次配置

管理员需要先在玩家管理中为开发者打开 Creator 访问权限、签发 CLI Token，并授予所需权限。然后配置并测试 Profile：

apc profile add local --endpoint 127.0.0.1:3127 --token "$BOX_CREATOR_TOKEN"
apc profile test local
apc profile list

地址填写 Creator 服务地址，不是玩家管理或 Play 服务地址。省略协议的本地/LAN 地址会按 HTTP 处理；公网部署请填写完整 HTTPS 地址，例如 https://create.example.com。不要添加 /api/creator/v1 路径、账号密码或 Token。

创建并绑定工程

apc project create my-map
cd my-map
npm install

apc project bind <permanentMapId> --profile local
apc map resource --type all
apc project info

project bind 会写入工程的 .env：

VITE_BOX_CREATOR_PROFILE=local
VITE_BOX_CREATOR_PROJECT_ID=<permanentMapId>

不要将 endpoint、CLI Token 或其他秘密写入 .env，也不要提交该文件。多个 Profile 同时存在时，命令优先采用 --profile，其次采用 .env 的 VITE_BOX_CREATOR_PROFILE；两者都没有时，仅允许自动选择唯一的 Profile。

工程结构与构建

client/src/     客户端 ESM 脚本
server/src/     服务端 CJS 脚本
shares/         两端共享的 TypeScript 模块
dao3.config.ts  脚本入口、名称和启用状态
vite.config.ts  Vite、路径别名、ESLint、类型检查和上传配置

常用脚本：

npm run build       # 构建 client + server，并默认上传
npm run dev         # 同时监听 client + server；每次构建后上传
npm run lint        # ESLint 严格检查
npm run lint:fix    # 仅自动修复格式类 ESLint 问题
npm run format      # Prettier 格式化

npm run dev 是监听构建并上传，不是浏览器 HMR。开发与 debug 构建会生成 sourcemap，因此运行时异常能由 APC 映射回 .ts 文件；production 构建不会生成 sourcemap。

默认允许上传。只有需要纯本地构建时才显式设置：

VITE_UPDATE_FILE=false

VITE_CURRENT_FILE=<bundleKey> 可只构建 dao3.config.ts 中的一个 bundle；留空则构建所有 enable: true 的入口。Creator 脚本部署必须是单个自包含 JavaScript 文件；Vite 产生额外 chunk 时插件会失败，避免上传不完整代码。

地图与资源

apc map list --profile local
apc map list --keyword "教学"

apc map resource --type dts
apc map resource --type assets
apc map resource --type all --project <permanentMapId>

dts 同步 API 类型声明，不需要连接服务器；assets 同步地图资源索引，需要已经绑定地图并具有资源读取权限；all 同时执行两项。资源更新后重新执行同步，避免模型、UI、音频等声明滞后。

脚本读取与上传

apc script get
apc script get <entry> --side server --out ./shared-server.js
apc script upload <permanentMapId> client <entry> --file ./dist/client/<entry>.client.js

script get 只读取 Creator 的共享脚本，不能读取地图私有入口。上传会覆盖相同地图、端和入口的已有脚本；上传前用 apc project info 核对 Profile、永久地图 ID 和连通性。

通常应优先用 Vite 的 build/dev 脚本上传，因为插件会确保 bundle 名称、目标端和单文件约束正确；script upload 主要用于显式脚本管理或自动化。

数据空间

apc storage list player
apc storage get player user_123
apc storage set player user_123 --value '{"coins":100}'
apc storage set player user_123 --file ./user_123.json
apc storage delete player user_123 --yes
apc storage list leaderboard --scope group

storage 直接读取或修改地图脚本使用的持久化 JSON 数据。默认是当前地图的 project 数据空间；--scope group 是同一地图组共享的 group 数据空间，影响范围更大。set 必须且只能使用 --value 或 --file 之一；只有 delete 需要 --yes 确认。权限分别为 storage.read（list/get）和 storage.write（set/delete）。

预览运行与实时控制台

apc runtime status
apc runtime start
apc runtime restart
apc runtime stop

apc runtime logs --follow

start、stop、restart 使用的是 Creator 编辑器按钮背后的同一预览运行。 restart 会等待停止请求完成后再启动，适合重新加载脚本。停止本地的日志命令（Ctrl-C）只会断开 SSE 订阅，不会停止地图。

日志默认按连续的 Client / Server 输出和秒级时间显示，并带颜色：

• info / log：白色
• debug：紫色
• warn：黄色
• error / exception：红色，附带 sourcemap 后的 TypeScript 堆栈
• Runtime 状态：青色

筛选示例：

apc runtime logs --follow --side client
apc runtime logs --follow --side server --level error
apc runtime logs --follow --grep "player-demo"
apc runtime logs --follow --raw

--side 仅接受 client 或 server；--level 接受 error、warn、info、debug。 --raw 保留逐事件输出，适合复制或解析；--verbose 显示完整堆栈。新订阅只接收连接之后的实时事件，不回放旧控制台记录；--follow 在临时断线后每秒重连。

编辑场景截图

apc scene capture --out ./artifacts/player-view.png
apc scene capture --view 3d --out ./artifacts/world.png
apc scene capture --view 2d --out ./artifacts/ui.png

目标地图只要正在 Creator 编辑器中打开，场景桥接就会自动连接并在会话到期前自动续期。关闭编辑器或离开地图会让等待中的截图请求失败。随后执行 scene capture，Creator 会让当前浏览器编辑器生成 PNG，再保存到 --out 指定路径。

不带 --view 会合成玩家实际看到的 3D 与 UI 覆盖层，包括玩家名、对话框和游戏 UI；--view 3d 只包含 3D 世界，适合检查地形、方块和模型；--view 2d 只包含透明背景的 UI 覆盖层。截图只读取当前画面，不会启动预览运行、修改方块或写入地图。CLI Token 需要额外的 scene.capture 权限；目标地图没有打开编辑器时，命令会返回错误而不会截图。

扩展包

apc package list

查询 @dao3fun 组织公开发布的 npm 包、版本、发布者和说明。它只查询 npm，不安装或修改当前工程；需要安装时，在工程目录自行执行输出建议中的 npm install <包名>。

权限

CLI Token 仅由玩家管理签发和撤销，APC 没有独立的 token 子命令。常用权限如下：

| 场景 | 所需权限 | | ---------------------- | ----------------- | | 地图列表 | projects.list | | 同步资源 | resources.list | | 读取共享脚本 | scripts.read | | 上传脚本 | scripts.update | | 查看预览状态、订阅日志 | runtime.view | | 启动、停止、重启预览 | runtime.control | | 截取当前编辑场景 | scene.capture |

为 CI 创建仅含 scripts.update 的最小权限 Token；不要把 Token 输出到日志、提交到 Git 或写入工程文件。

自动化与故障处理

自动化总是使用 --json，并根据退出码和 JSON 错误码处理结果：

apc project info --json
apc runtime logs --follow --json

| 退出码 | 含义 | | ------ | ------------------------------ | | 2 | 参数、命令或工程配置无效 | | 3 | 缺少 Token 或权限不足 | | 4 | 目标 Profile、地图或资源不存在 | | 5 | 网络或 Creator 服务连接失败 | | 6 | 脚本上传失败 |

遇到构建上传失败时，先执行 apc project info --json 确认目标和认证；遇到运行时错误时，以 npm run dev 生成的 sourcemap 配合 apc runtime logs --follow --verbose 定位到源码。

完整命令文档

apc docs
apc docs --json
apc docs --file

apc docs 输出随 CLI 发布的 BOX Creator CLI Skill，供 AI、CI 和开发者使用。apc docs --file 只输出该 Skill 的入口文件绝对路径，便于 Agent 建立软链接或注册目录。该 Skill 与命令实现同步维护。