search

Quickstart

Quickstart

This guide gets you from an RPG Maker MZ project to a running React UI overlay and a runnable desktop package.

Prerequisites

  • RPG Maker MZ installed

  • Node.js 18+ and Yarn

  • Windows PowerShell 5.1+ or PowerShell 7+

  1. Build the React menus

  • Open a terminal at the project root

  • Change directory to menus

cd menus
yarn install
yarn build  # Development build (use `yarn release` for production)

This produces menus/build/ and menus/shared/types.js.

Note: For production releases, use yarn release instead of yarn build. The release command enables production optimizations.

RPGReact build

Optional: run the built-in battle test

Note: Event test (etest) exists in the engine but is editor-oriented; we don't use it in the CLI workflow.

  1. Enable the plugin in MZ

  • Open your project in RPG Maker MZ

  • Plugin Manager: add RPGReact

  • Set Asset Manifest Path to menus/build/.vite/manifest.json

  • Set Z-Index as needed (default 100)

RPGReact plugin

  1. Package for distribution

  • Prerequisites:

    • Ensure js/plugins/rpgreact/overrides.manifest.json lists all overrides you want to ship (order matters).

    • Install esbuild (globally, in project root, or under menus/). The packager fails fast if it cannot minify.

  • From the project root, run the packager

  • Windows desktop (runnable): ./build-package.ps1 -Target windows

  • Mac desktop (runnable): ./build-package.ps1 -Target mac

  • Web or mobile HTML5: ./build-package.ps1 -Target web If runtime auto-discovery fails on desktop, provide a runtime path via one of:

  • CLI: ./build-package.ps1 -Target windows -RuntimePath "C:\\Path\\To\\RMMZ\\Runtime"

  • Config: deploy.config.json → runtimePath

  • Env var: RMMZ_RUNTIME_PATH

  1. Run the packaged build

  • Change directory to dist\package (or your chosen OutDir)

  • Run the game executable

If the window does not appear, see Plugin → Troubleshooting.

Common Issues & Tips

  • Black screen on launch: React assets not loaded (check Asset Manifest Path in plugin settings)

  • Continue button errors: If no save files exist, the Continue button should be disabled. See Title/Save System Tutorial

  • Missing graphics: Asset pruning may have removed needed files. See Asset Pruning Guide

  • Shop selection broken: Ensure sellItems/buyItems are memoized. See Shop System Tutorial

  • Level-ups not showing: XP bar animation must track level thresholds. See Level-Up Animation Tutorial

Next Steps

PreviousOverviewNextPlugin

Last updated