# ArenaPro CLI **Repository Path**: box3lab/arenapro-cli ## Basic Information - **Project Name**: ArenaPro CLI - **Description**: ArenaPro CLI 旨在攻克神岛Arena编辑器使用上的难题，通过与其生态中强大的外部编辑器实现无缝对接，极大地扩展了创作者的创作效率。让创作者能够更专注于代码创作本身，无需为繁琐的编辑操作分心，从而激发无限创意与灵感。 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 0 - **Created**: 2025-11-27 - **Last Updated**: 2026-09-22 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ArenaPro CLI（APC） APC 是 BOX Creator 的本地开发命令行工具。它负责连接 Creator、生成并绑定 TypeScript/Vite 工程、同步资源声明、上传客户端和服务端脚本、控制地图的**预览运行**并订阅实时控制台，也能截取当前打开的编辑场景。它不保存服务器地址或 Token 到工程目录：工程只绑定 Profile 名称和永久地图 ID；连接地址与 Token 只保存在当前用户电脑的私密 APC 配置中。 ## 安装与术语 ```bash 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： ```bash 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。 ## 创建并绑定工程 ```bash apc project create my-map cd my-map npm install apc project bind --profile local apc map resource --type all apc project info ``` `project bind` 会写入工程的 `.env`： ```ini VITE_BOX_CREATOR_PROFILE=local VITE_BOX_CREATOR_PROJECT_ID= ``` 不要将 endpoint、CLI Token 或其他秘密写入 `.env`，也不要提交该文件。多个 Profile 同时存在时，命令优先采用 `--profile`，其次采用 `.env` 的 `VITE_BOX_CREATOR_PROFILE`；两者都没有时，仅允许自动选择唯一的 Profile。 ## 工程结构与构建 ```text client/src/ 客户端 ESM 脚本 server/src/ 服务端 CJS 脚本 shares/ 两端共享的 TypeScript 模块 dao3.config.ts 脚本入口、名称和启用状态 vite.config.ts Vite、路径别名、ESLint、类型检查和上传配置 ``` 常用脚本： ```bash 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。默认允许上传。只有需要纯本地构建时才显式设置： ```ini VITE_UPDATE_FILE=false ``` `VITE_CURRENT_FILE=` 可只构建 `dao3.config.ts` 中的一个 bundle；留空则构建所有 `enable: true` 的入口。Creator 脚本部署必须是单个自包含 JavaScript 文件；Vite 产生额外 chunk 时插件会失败，避免上传不完整代码。 ## 地图与资源 ```bash 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 ``` `dts` 同步 API 类型声明，不需要连接服务器；`assets` 同步地图资源索引，需要已经绑定地图并具有资源读取权限；`all` 同时执行两项。资源更新后重新执行同步，避免模型、UI、音频等声明滞后。 ## 脚本读取与上传 ```bash apc script get apc script get --side server --out ./shared-server.js apc script upload client --file ./dist/client/.client.js ``` `script get` 只读取 Creator 的共享脚本，不能读取地图私有入口。上传会覆盖相同地图、端和入口的已有脚本；上传前用 `apc project info` 核对 Profile、永久地图 ID 和连通性。通常应优先用 Vite 的 build/dev 脚本上传，因为插件会确保 bundle 名称、目标端和单文件约束正确；`script upload` 主要用于显式脚本管理或自动化。 ## 数据空间 ```bash 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）。 ## 预览运行与实时控制台 ```bash 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 状态：青色筛选示例： ```bash 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` 在临时断线后每秒重连。 ## 编辑场景截图 ```bash 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` 权限；目标地图没有打开编辑器时，命令会返回错误而不会截图。 ## 扩展包 ```bash 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 错误码处理结果： ```bash 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` 定位到源码。 ## 完整命令文档 ```bash apc docs apc docs --json apc docs --file ``` `apc docs` 输出随 CLI 发布的 [BOX Creator CLI Skill](cli/skills/box-creator-cli/SKILL.md)，供 AI、CI 和开发者使用。`apc docs --file` 只输出该 Skill 的入口文件绝对路径，便于 Agent 建立软链接或注册目录。该 Skill 与命令实现同步维护。