用途
rmmz-scene 是一个面向 RPG Maker MZ 的场景包管理命令行工具,用于发现、检查、打包、发布、安装和回滚可复用的 RPG Maker 场景。当用户提到 RPG Maker MZ 或 MV 相关场景复用需求时可以使用。
主要能力
- 发现(Discover):检索集中式 Registry,并查看精确坐标(owner/scene@version)。报告内容包括:创作者仓库 URL、engines.mz 与 engines.mv 的兼容声明、许可证与来源说明、包 SHA-256 以及外部依赖数量(若有)。
- 安装(Install):将公开场景安装到已有的 MZ 项目。安装过程中自动分配地图 ID 与图块集 ID、重写引用、解决同名内容冲突,并创建原子备份。
- 注册与发布(Register and Publish):将已有地图转为可复用仓库。需先盘点地图直接素材,将其分类为随包(bundled,创作者拥有或可再分发)或外部(external,如 RTP、付费第三方素材)。发布时生成创作者仓库协议,可分别声明 MZ/MV 兼容性,并支持多语言名称与描述。
- 回滚(Roll Back):使用 apply 返回的 backup_id 预览并撤销已应用的安装。
使用方式
- 准备 CLI:检查 rmmz-scene 是否可用;若缺失,可执行
uv tool install git+https://github.com/lemonhall/rmmz-scene-registry.git安装。若无 uv,应报告该前置条件缺失。 - 发现场景:
rmmz-scene search shop --json、rmmz-scene info lemonhall/convenience-store --json。 - 安装场景:先 dry-run(不加 --apply),确认目标含 Game.rmmzproject、data/MapInfos.json、data/Tilesets.json,并拒绝仅兼容 MV 的坐标;经用户明确授权后再加 --apply。安装后核对返回的 applied、map_id、tileset_id、backup_id,并确认 data/RmmzSceneRegistry.json 记录相同包哈希。
- 注册地图:
rmmz-scene register --source ... --map 2 --library ... --scene-id my-scene --external-asset 'img/tilesets/Inside_A1.png' --json。 - 发布场景:使用
rmmz-scene publish生成仓库协议,检查 scene.json、提交仓库并打 v<version> 标签,再通过集中式 Registry 的场景提交表单提交公开仓库 URL。 - 回滚:
rmmz-scene rollback <backup-id> --target ... --json先预览,明确授权后再加 --apply。
适用场景
适用于需要在多个 RPG Maker MZ 项目之间复用场景、从公开 Registry 挑选并安装场景、把自有地图打包发布为可复用仓库,以及在安装后需要安全回滚的开发者工作流。
限制
- 当前写入器仅校验和更新 MZ 项目;MV 兼容性在 Registry 中记录,但不支持仅兼容 MV 的场景安装。
- 外部素材缺失或哈希不符属于阻断错误,不得从无关项目复制或下载非官方 RTP 文件。
- 网络、压缩包、SHA-256、清单、素材、引擎或项目校验错误会在 apply 前终止操作。
- 不得在 dry-run 成功时声称已安装,也不得在未确认 applied 结果时声称回滚成功。
- 发布的标签不可移动或覆盖;公开 Registry 数据与问题提交中不得包含用户项目的绝对路径。