Custom Overrides

Custom Overrides

RPGReact supports project‑specific override files so you can hook into RPG Maker MZ scenes and emit events to the React app without modifying core plugin code.

What are overrides?

• JavaScript files that patch/extend MZ classes (e.g., scenes, windows) and use the same internal facilities as the built‑in overrides.

• They have access to the event(eventType, eventSpecifier, data?, trace?) helper used throughout the stock overrides to send messages to the React app. This helper is injected into overrides and automatically decorates data with platform/app context so your React handlers receive game state along with your payload.

Single source of truth: overrides manifest

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

• Purpose: Defines the ordered list of override files and the exported function name each file provides. Both development and production use this manifest; there is no auto‑discovery.

• Schema:

{
  "entries": [
    { "file": "override_scene_map.js", "export": "overrideSceneMap" },
    { "file": "custom/override_myfeature.js", "export": "overrideMyFeature" }
  ]
}

• Rules:

  • file is relative to js/plugins/rpgreact/ (custom files go under custom/).

  • export is the exact function name defined by that file. Order in the array is execution order.

Where to place files

• STOCK overrides live under js/plugins/rpgreact/ and are provided by the plugin.

• CUSTOM overrides live under js/plugins/rpgreact/custom/.

• To include any file in dev/prod, add an entry to overrides.manifest.json.

Execution order

• Exactly the order listed in overrides.manifest.json.

• If one override depends on another, list the dependency first.

Authoring an override

• Each file should define a function whose name matches the export in the manifest. The build/dev loader prepares the code so symbols align and then invokes your function.

// File: js/plugins/rpgreact/custom/override_scene_map_custom.js
function overrideSceneMapCustom(event, createEventData, createExtraData, reactBridge, decorateData) {
  const _Scene_Map_start = Scene_Map.prototype.start;
  Scene_Map.prototype.start = function() {
    _Scene_Map_start.call(this);
    // Open Map screen (same pattern as stock override_scene_map.js)
    event(RPGEventType.SCREEN_OPEN, RPGScreen[RPGScreen.Map], {}, 'MyMapHook');
  };
}

Examples that mirror real events emitted by stock overrides

// File: js/plugins/rpgreact/custom/override_scene_map_custom.js
function overrideSceneMapCustom(event, createEventData, createExtraData, reactBridge, decorateData) {
  const _Scene_Map_start = Scene_Map.prototype.start;
  Scene_Map.prototype.start = function() {
    _Scene_Map_start.call(this);
    // Open Map screen (same pattern as stock override_scene_map.js)
    event(RPGEventType.SCREEN_OPEN, RPGScreen[RPGScreen.Map], {}, 'MyMapHook');
  };
}

// File: js/plugins/rpgreact/custom/override_input_custom.js
function overrideInputCustom(event, createEventData, createExtraData, reactBridge, decorateData) {
  const _Input_onKeyDown = Input._onKeyDown;
  Input._onKeyDown = function(eventArgs) {
    _Input_onKeyDown.call(this, eventArgs);
    if (eventArgs.key === 'M') {
      // Toggle the menu button visibility (same event used in override_scene_map.js)
      event(RPGEventType.WINDOW_EVENT, RPGWindowEvent[RPGWindowEvent.MENU_BUTTON_SHOW], {}, 'KeyM');
    }
  };
}

Example: overlay the Message window when a message/choice appears (like stock overrides)

// File: js/plugins/rpgreact/custom/override_interpreter_custom.js
function overrideInterpreterCustom(event, createEventData, createExtraData, reactBridge, decorateData) {
  const command101 = Game_Interpreter.prototype.command101;
  Game_Interpreter.prototype.command101 = function (params) {
    const ret = command101.call(this, params);
    if ($gameMessage && ($gameMessage.hasText() || $gameMessage.isChoice())) {
      event(RPGEventType.OVERLAY_WINDOW, RPGScreen[RPGScreen.Message], { gameMessage: $gameMessage }, 'MyInterpreter');
    }
    return ret === undefined ? true : ret;
  };
}

Guidelines

• Keep overrides small and focused; avoid deep engine rewrites when a simple event will do.

• Prefer emitting the same semantic events the stock overrides use (SCREEN_OPEN, OVERLAY_WINDOW, SHOW_TOAST, WINDOW_EVENT, BATTLE_EVENT).

• Use the optional trace parameter to make debugging easier (debug.log/DevTools).

• Namespacing: prefix your file names/functions to avoid collisions with stock overrides.

• Place custom files under js/plugins/rpgreact/custom/ and add them to overrides.manifest.json.

• See the Event Reference for a list of existing event types/specifiers and example payloads.

Dev vs. Prod behavior (how overrides run)

• Development (test mode): the plugin reads overrides.manifest.json, prepares each file by wrapping and promoting your export function, then immediately invokes each override with standard args: (event, createEventData, createExtraData, reactBridge, decorateData).

• Production (packaging): the build script reads the same manifest, concatenates/wraps each file, minifies with esbuild to js/plugins/rpgreact/RPGReact.overrides.min.js, and removes unminified sources from the package. At runtime the overrides are invoked in manifest order with the same args. The manifest remains in the output and is required for invocation order.

• Fail‑fast: missing manifest entries/files or minification errors stop the build with clear messages.

Troubleshooting

• If your override doesn’t seem to run, open DevTools (desktop: enable chromium-args logging) and look for syntax errors.

• Verify the file is listed correctly in js/plugins/rpgreact/overrides.manifest.json with the right export name.

• In production, confirm RPGReact.overrides.min.js and overrides.manifest.json exist under js/plugins/rpgreact/, and that your file wasn’t removed due to a build error.

• Build failures will mention the exact missing file or esbuild error; fix and re‑run the packager.