roh5

vscode-roh5 项目插件的脚手架、构建与诊断 CLI。它在游戏项目中创建 .roh5/plugins/* 插件包，由 VS Code 扩展自动发现和加载。

安装

npx @rontian/roh5-cli init --id game-i18n --type language

或全局安装：

npm install -g @rontian/roh5-cli
roh5

确认当前全局 CLI 版本：

roh5 --version
# 或 roh5 -v / roh5 version

命令

version、--version、-v

输出当前正在执行的 roh5 CLI 版本，用于确认全局安装是否已更新：

roh5 --version

init

创建 manifest、入口模板和 TypeScript 配置：

roh5 init
# 或适合脚本化的参数模式
roh5 init --id game-i18n --type language

在支持 TTY 的终端中，不带参数的 roh5 init 会引导填写 ID、显示名称、首个能力、TS/JS 与目录；--interactive 可强制引导。非交互环境请传入 --id 等参数，避免 CI 等待输入。

| 参数 | 默认值 | 说明 | | --- | --- | --- | | --id | my-project-plugin | 仅小写字母、数字和连字符。 | | --type | language | language、translation、skin、commands。 | | --language | ts | ts（默认）或 js。 | | --dir | .roh5/plugins/<id> | 新插件目录，必须不存在。 | | --display-name | 与 ID 相同 | 插件显示名称。 | | --interactive | 无 | 强制进入交互引导。 |

add

为已有插件增加能力。无能力参数时会在 TTY 中引导选择插件和能力；--interactive 可强制引导。TS 插件会生成 src/adapters/<type>.ts，构建后由 runtime 从 dist/adapters/<type>.js 加载；JS 插件生成 adapters/<type>.cjs。

roh5 add translation --plugin .roh5/plugins/game-i18n
roh5 add

add translation 会自动在 manifest 增加 network 权限；随后 TS 插件需再次运行 npm run build。

build、validate、list、doctor

roh5 build --plugin .roh5/plugins/game-i18n
roh5 validate --plugin .roh5/plugins/game-i18n
roh5 list
roh5 doctor

• build 执行插件自己的 npm run build。TS 插件先运行 npm install。
• validate 检查 manifest、ID、schema 和编译入口。
• list 列出 .roh5/plugins 下插件及启用状态。
• doctor 对发现的每个插件执行校验。

完整流程

cd /path/to/Game
npx @rontian/roh5-cli init --id game-i18n --type language
cd .roh5/plugins/game-i18n
npm install
npm run build
roh5 validate --plugin .

在 VS Code 打开游戏项目后，插件自动发现。多个同类插件时，写入 .vscode/settings.json：

{
  "vscodeROH5.plugins.bindings": { "language": "game-i18n" }
}

常见错误

| 错误 | 处理 | | --- | --- | | 目录已存在 | 使用新的 --id/--dir，不要覆盖已有插件。 | | entry 不存在 | TS 插件先 npm install && npm run build。 | | schemaVersion 或 id 无效 | schemaVersion 固定为 1；ID 仅小写字母、数字、连字符。 | | VS Code 未加载 | 检查 trusted workspace、enabled: true，运行 roh5 doctor。 | | 多个同类插件 | 使用 vscodeROH5.plugins.bindings 选择 ID。 |

能力接口、manifest 字段和权限见 Plugin API。