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