Messaging Bridge

Messaging Bridge

RPGReact includes a lightweight communication layer between RPG Maker MZ and the React app.

Concepts

• Outbound (MZ → React): In override files, use the provided event(eventType, eventSpecifier, data?, trace?) helper. Stock overrides live under js/plugins/rpgreact/ and your custom overrides should be placed under js/plugins/rpgreact/custom/. Overrides are loaded and executed strictly according to js/plugins/rpgreact/overrides.manifest.json (single source of truth). The helper is injected into overrides (not global) and automatically decorates data with the platform/app context so React always receives the current game state along with your payload.

• Alternative (Script calls): Outside overrides, you can emit messages using RPGBridge.CreateEvent(type, spec, data?, trace?) once the UI has initialized (see below).

• Inbound (React → MZ): The React app registers handlers with RPGBridge to receive and react to events.

Runtime loading

• The plugin loads menus/shared/types.js at boot (generated by the menus build) to share common enums and types across the bridge (e.g., RPGEventType, RPGScreen, RPGMessageType, RPGBattleEvent, RPGWindowEvent).

Sending messages from overrides (recommended) These examples mirror the real events emitted by the stock overrides:

// Open a screen (override_common.js)
event(RPGEventType.SCREEN_OPEN, RPGScreen[RPGScreen.Splash], null, "PluginSceneSplash");

// Title screen open with menu actions (override_common.js)
event(
  RPGEventType.SCREEN_OPEN,
  RPGScreen[RPGScreen.Title],
  { actions: [ { name: "New Game" }, { name: "Continue" }, { name: "Options" } ] },
  "PluginSceneTitle"
);

// Map screen open (override_scene_map.js)
event(RPGEventType.SCREEN_OPEN, RPGScreen[RPGScreen.Map], {}, "PluginSceneMap");

// Show a toast (override_window_map.js / override_common.js)
event(RPGEventType.SHOW_TOAST, RPGMessageType.MAP_NAME, { message: $gameMap.displayName() });
event(RPGEventType.SHOW_TOAST, RPGMessageType.NORMAL,   { message: "Test" }, "PluginSceneTitle");

// Hide a toast (override_window_map.js)
event(RPGEventType.HIDE_TOAST, RPGMessageType.MAP_NAME);

// Overlay a specific UI window (e.g., Message, Items, Save/Load, Options, Equip, Status, Skills)
// (override_interpreter.js and multiple override_scene_*.js)
event(RPGEventType.OVERLAY_WINDOW, RPGScreen[RPGScreen.Message], { gameMessage: $gameMessage }, "PluginInterpreter");
event(RPGEventType.OVERLAY_WINDOW, RPGScreen[RPGScreen.Items],   { /* menu data */ }, "PluginSceneItem");

// Window/UI events (override_scene_map.js, override_input.js)
event(RPGEventType.WINDOW_EVENT, RPGWindowEvent[RPGWindowEvent.MENU_BUTTON_SHOW], {}, "PluginSceneMap");
event(RPGEventType.WINDOW_EVENT, RPGWindowEvent[RPGWindowEvent.MENU_BUTTON_HIDE], {}, "PluginSceneMap");
event(
  RPGEventType.WINDOW_EVENT,
  RPGWindowEvent[RPGWindowEvent.INPUT_TYPE_CHANGED],
  { inputType: "keyboard" }
);

// Battle events (override_scene_battle.js, override_window_battlelog.js, override_battle_manager.js)
event(RPGEventType.BATTLE_EVENT, RPGBattleEvent[RPGBattleEvent.ACTOR_START_INPUT], { actor: this._currentActor }, "PluginSceneBattle");
event(RPGEventType.BATTLE_EVENT, RPGBattleEvent[RPGBattleEvent.ENEMY_SELECT_START], {}, "PluginSceneBattle");
event(RPGEventType.BATTLE_EVENT, RPGBattleEvent[RPGBattleEvent.BATTLE_LOG_APPEND], { message: msg });
event(RPGEventType.SHOW_TOAST,   RPGMessageType.BATTLE_MESSAGE,  { message: TextManager.victory.format($gameParty.name()) });

Sending messages from Script calls (outside overrides)

// Ensure the React UI has initialized first (e.g., call Show React App)
if (window.RPGBridge && RPGBridge.IsInitialized()) {
  RPGBridge.CreateEvent(RPGEventType.SCREEN_OPEN, RPGScreen[RPGScreen.MainMenu], { openedVia: "CommonEvent42" }, "CommonEvent42");
}

Handling messages in React

// See menus/src/bridge/RPGBridge.ts for the concrete implementation
import RPGBridge from "../bridge/RPGBridge";
import { RPGEventType, RPGScreen } from "../bridge/Types";

useEffect(() => {
  const id = RPGBridge.AddEventHandler({
    id: "example",
    handler: (evt) => {
      // evt has: eventType, eventSpecifier, data (already includes platform context), trace
      if (evt.eventType === RPGEventType.SCREEN_OPEN && evt.eventSpecifier === RPGScreen[RPGScreen.Map]) {
        // route to Map screen
      }
    }
  });
  return () => RPGBridge.RemoveEventHandlerById(id);
}, []);

Best practices

• In overrides, prefer the provided event(...) helper so the platform/app context is included automatically.

• Keep payloads small and serializable; add a trace string when helpful for debugging.

• Use the enums from menus/shared/types.js (RPGEventType, RPGScreen, etc.) to keep type/signature consistent.

Troubleshooting

• If messages don’t arrive, ensure the React app has initialized (use the Show React App command first).

• Check DevTools/debug.log (desktop: enable NW.js logging via chromium-args).

• Verify that your custom override file is listed correctly in js/plugins/rpgreact/overrides.manifest.json (with the right export name) and is present under js/plugins/rpgreact/. Fix any syntax errors.