SuperAPI AI Directory

rmmz-scene

Coding & development

View repository

Updated 10-24 16:19

About this skill

RMMZ Scene CLI

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

  1. Check whether rmmz-scene is available.

    Get-Command rmmz-scene -ErrorAction SilentlyContinue
    
  2. If missing, install it from the public tool repository.

    uv tool install git+https://github.com/lemonhall/rmmz-scene-registry.git
    
  1. If uv is 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.mz and engines.mv without 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.

  1. Confirm the target contains Game.rmmzproject, data/MapInfos.json, and data/Tilesets.json.

  2. Inspect the scene and reject an MV-only coordinate.

  3. Run a dry-run first. Do not add --apply in this command.

    rmmz-scene install lemonhall/convenience-store `
      --target 'E:\games\MyProject' --json
    
  4. 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.

  5. 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
    
  6. Verify the returned applied, map_id, tileset_id, and backup_id. Check that the installed map points at the returned Tileset ID and that data/RmmzSceneRegistry.json records 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.

  1. 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.
  2. Register the map into a library outside the source project. Repeat --external-asset for 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
    
  3. Inspect the manifest. Confirm every bundled file and the bundled/external counts before publish.

  4. Generate the creator repository contract. Declare MZ/MV independently; use no --mv option 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
    
  5. Review scene.json, commit the repository, and tag v<version>. The generated package URL is pinned to that tag. Do not move or overwrite a published tag.

  6. 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.