Use rmmz-scene as the only writer for scene packages and target RPG Maker projects. Keep the
source project read-only, parse --json output for decisions, and preserve dry-run as a distinct
step from apply.
Prepare the CLI
-
Check whether
rmmz-sceneis available.Get-Command rmmz-scene -ErrorAction SilentlyContinue -
If missing, install it from the public tool repository.
uv tool install git+https://github.com/lemonhall/rmmz-scene-registry.git
- If
uvis unavailable, report that prerequisite. Do not invent a shell-pipe installer.
Choose a Workflow
- Find or compare public scenes: use Discover.
- Add a public scene to an existing MZ project: use Install.
- Turn an existing map into a reusable repository: use Register and Publish.
- Undo an applied installation: use Roll Back.
- Do not install an MV-only scene. The Registry records MV compatibility, but the current writer validates and updates MZ projects only.
Discover
Search the central Registry, then inspect the exact coordinate. Use JSON when making decisions.
rmmz-scene search shop --json
rmmz-scene info lemonhall/convenience-store --json
Before recommending a scene, report:
- exact
owner/scene@version; - creator
repository_url; engines.mzandengines.mvwithout inferring compatibility from screenshots;- license and source note;
- package SHA-256 and external dependency count when available.
Use --registry <url> only when the user supplies a mirror or test Registry. The environment
variable RMMZ_SCENE_REGISTRY_URL is the non-interactive equivalent.
Install
Treat the source package and target project as separate trust boundaries.
-
Confirm the target contains
Game.rmmzproject,data/MapInfos.json, anddata/Tilesets.json. -
Inspect the scene and reject an MV-only coordinate.
-
Run a dry-run first. Do not add
--applyin this command.rmmz-scene install lemonhall/convenience-store ` --target 'E:\games\MyProject' --json -
Read the plan. Report allocated Map ID, Tileset ID, bundled writes, reused external assets, renamed collisions, and package hash. A missing or different external asset is a blocking error; do not copy it from an unrelated project or download unofficial RTP files.
-
Apply only when the user's request clearly authorizes changing the target project.
rmmz-scene install lemonhall/convenience-store ` --target 'E:\games\MyProject' --apply --json -
Verify the returned
applied,map_id,tileset_id, andbackup_id. Check that the installed map points at the returned Tileset ID and thatdata/RmmzSceneRegistry.jsonrecords the same package hash.
Never edit MapInfos.json, Tilesets.json, or copied asset names by hand after the CLI plan. The
installer allocates IDs, rewrites references, resolves same-name content conflicts, and creates an
atomic backup as one transaction.
Register and Publish
Use this workflow only when the user owns or may redistribute the source map.
-
Inventory the map's direct assets. Classify each as:
bundled: creator-owned or explicitly redistributable;external: RPG Maker RTP, paid third-party material, or anything that may not be republished.
-
Register the map into a library outside the source project. Repeat
--external-assetfor every runtime dependency that must not enter the public package.rmmz-scene register --source 'E:\games\CreatorProject' --map 2 ` --library 'E:\rmmz-library' --scene-id my-scene ` --external-asset 'img/tilesets/Inside_A1.png' --json -
Inspect the manifest. Confirm every bundled file and the bundled/external counts before publish.
-
Generate the creator repository contract. Declare MZ/MV independently; use no
--mvoption when MV compatibility has not been tested.rmmz-scene publish my-scene --library 'E:\rmmz-library' ` --owner github-name ` --repository 'https://github.com/github-name/rmmz-scene-my-scene' ` --output 'E:\development\rmmz-scene-my-scene' ` --name-en 'My Scene' --description-en 'A complete reusable scene.' ` --name-zh '我的场景' --description-zh '可复用的完整场景。' ` --name-ja 'マイシーン' --description-ja '再利用できる完成シーン。' ` --mz '>=1.0.0' --tag interior --license CC-BY-4.0 ` --source-note 'Original bundled art by github-name; RPG Maker assets are external.' --json -
Review
scene.json, commit the repository, and tagv<version>. The generated package URL is pinned to that tag. Do not move or overwrite a published tag. -
Submit the public repository URL through the central Registry's scene submission form. Registry review owns the preview and searchable central record; the creator repository owns the package.
Roll Back
Use the exact backup_id returned by apply. Preview rollback first, then apply only with explicit
authorization.
rmmz-scene rollback <backup-id> --target 'E:\games\MyProject' --json
rmmz-scene rollback <backup-id> --target 'E:\games\MyProject' --apply --json
Stop if the target has drifted since installation. Do not force-delete maps, Tilesets, assets, or backup records around the rollback checks.
Failure Rules
- A network, archive, SHA-256, manifest, asset, engine, or project validation error ends the operation before apply.
- Do not weaken external asset checks merely to make a scene install.
- Do not claim a scene is installed when only dry-run succeeded.
- Do not claim rollback succeeded unless the applied result confirms it.
- Keep absolute user project paths out of public Registry data and issue submissions.