React UI (menus)

React UI (menus): Overview

The menus/ workspace contains a React + TypeScript UI that renders over the RPG Maker MZ canvas. You fully control UI/UX using modern web tooling (Vite, React 19, Tailwind optional).

Structure (typical)

• src/ — React source (screens, components, bridge, state)

• public/ — Static assets (optional)

• vite.config.mts — Build configuration

• tsconfig.json — TypeScript config

• package.json — Scripts and dependencies

• build/ — Production build output (created by yarn build)

• shared/types.js — Bridge typings emitted for MZ (generated by the build)

Build

cd menus
yarn install
yarn build

This creates menus/build/.vite/manifest.json and menus/shared/types.js which the plugin loads at runtime.

Integration

• The plugin parameter manifestPath points to the Vite manifest (menus/build/.vite/manifest.json by default).

• The plugin injects an overlay container and loads built JS/CSS files listed in the manifest.

State model and reactivity (default implementation)

• The default UI uses MobX to provide fine‑grained reactivity for both platform data (objects coming from MZ) and any custom UI data.

• At boot, the plugin calls reactBridge.InitPlatformData(...) with a comprehensive snapshot of engine objects (see RPGReact.js). In the UI, this is implemented in menus/src/bridge/RPGBridge.ts as:

  • InitPlatformData(data) → decorates deeply with observables via a helper (makeDeepObservable) so nested properties can emit change notifications to React observers.

  • DecorateCustomData(data) → wraps ad‑hoc payloads with makeAutoObservable so ephemeral event data can also be reactive when consumed by components.

• After initialization, the plugin replaces many core $game* globals with their enhanced counterparts (see RPGReact.js), which means when the engine mutates them (e.g., variables/switches, party, map), those changes propagate through MobX to any observing React components.

How to consume platform data in React

• Access the decorated platform data via RPGBridge.GetPlatformData().; or,

• Most components and/or events will have a 'pageData' property which has platform data and custom data

• Wrap components that read observable fields with observer from mobx-react-lite, or use useObserver.

Example

// Component that reacts to game variable changes
import { observer } from 'mobx-react-lite';
import RPGBridge from '../bridge/RPGBridge';

const GoldDisplay = observer(() => {
  const platform = RPGBridge.GetPlatformData();
  const gold = platform?.runtime?.gameParty?.gold?.(); // calling MZ method via decorated object
  return <span>Gold: {gold}</span>;
});

export default GoldDisplay;

Guidelines

• Prefer reading from provided context inside observed components instead of copying snapshots into local React state.

• Do not mutate platform objects directly from React; emit intent via bridge events (see Messaging Bridge) or let MZ drive updates, which will then flow back through the decorated observables.

• For custom per‑screen data that should be reactive, pass plain objects; the bridge will decorate them (via DecorateCustomData) so observers update when you modify fields within React state stores.

• Battle sub-selection windows (skills/items) render the highlighted entry’s description in the UI; see menus/src/views/battle/SubSelectionWindow.tsx.