Troubleshooting

Plugin Troubleshooting

Symptoms and quick fixes when enabling RPGReact in MZ.

No window opens on desktop (NW.js) after packaging

• Cause: NW.js runtime not included or invalid package.json entry.

• Fix: Use the packager with desktop runtime bundling, and ensure package.json → main is index.html.

  • ./build-package.ps1 -Target windows

  • Provide the runtime via one of: -RuntimePath, deploy.config.json.runtimePath, or RMMZ_RUNTIME_PATH env var.

Game boots but never leaves black screen

• Cause: React assets not loaded; the plugin waits for ReactSystemReady.

• Checks:

  • menus/build/.vite/manifest.json exists in your packaged folder

  • menus/shared/types.js exists

  • Plugin parameter manifestPath matches where the manifest actually is

Overrides didn’t run in development

• Cause: Missing or invalid overrides manifest, or export names don’t match.

• Checks:

  • js/plugins/rpgreact/overrides.manifest.json exists and contains { "entries": [ { "file", "export" } ] }.

  • Each listed file exists relative to js/plugins/rpgreact/ (custom files under custom/).

  • Each file defines a function whose name matches the export value.

  • Open DevTools and look for: Error evaluating override ... or Exported function ... not found.

Packaging failed when building overrides

• Cause: esbuild missing or a syntax error produced an invalid concatenation before minification.

• Fix:

  • Install esbuild (any one of): yarn add -D esbuild (in project root or under menus/) or add esbuild to PATH.

  • Re-run: ./build-package.ps1 -Target windows.

  • The script fails fast with errors like:

    • Missing manifest: js/plugins/rpgreact/overrides.manifest.json

    • Manifest references missing override file: <file>

    • Failed to create minified overrides bundle. Aborting.

  • Address the specific error and try again.

Production runs but overrides don’t execute

• Cause: The minified bundle loaded, but exported functions were not promoted due to a mismatch in names.

• Fix:

  • Ensure each manifest export exactly matches the function name defined in that file.

  • Confirm the bundle exists: js/plugins/rpgreact/RPGReact.overrides.min.js in the packaged output.

  • Confirm only the minified bundle is present (individual override sources are intentionally removed).

Overlay shows scrollbars

• Cause: Overlay sizing/children overflow.

• Fix: Use position: fixed + inset: 0 and avoid mixing width/height: 100% with inset.

  • Ensure html, body { margin:0 } and consider overflow: hidden on the overlay container.

Plugin commands appear to do nothing

• Cause: React app not initialized or hidden.

• Fix: Ensure you called Show React App after boot; check console for asset load errors.

How to gather logs (desktop)

• Add to package.json:

  • "chromium-args": "--enable-logging --v=1 --remote-debugging-port=9222"

• Re-run Game.exe and review debug.log next to the executable.