Build a Map HUD

Build a Map HUD (Map screen)

Goal

Render a simple Heads‑Up Display (HUD) on the Map screen using platform data (player stats, map name, gold). This tutorial only touches UI code inside the menus workspace; the plugin wiring is already handled for you.

What you’ll build

A MapHUD React component that observes platform data via RPGBridge.GetPlatformData() and displays:
- Current map name
- Party gold
- Current actor’s HP/MP (actor 0)

Prerequisites

React UI is set up (menus/ built at least once)
Plugin enabled and overlay visible in your project

Create the component Create (or reuse) menus/src/views/tutorial/MapHUD.tsx:

import React from 'react';
import { observer } from 'mobx-react-lite';

//adjust these paths for your directory structure
import RPGBridge from '../../bridge/RPGBridge';
import GetGoldInfo from '../../types/Gold';

const clamp01 = (v: number) => Math.max(0, Math.min(1, v));

const MapHUD: React.FC = observer(() => {
  const platform = RPGBridge.GetPlatformData();

  // Map name via decorated platform api
  const mapName = platform.runtime.gameMap.displayName();

  // Gold via provided helper (value, unit, unitColor)
  const { value: goldValue, unit: goldUnit, unitColor } = GetGoldInfo(platform);

  // Actor 0 (leader) stats
  const actor = platform.runtime.gameParty.members()[0];
  const hp = actor.hp;
  const mhp = actor.mhp;
  const mp = actor.mp;
  const mmp = actor.mmp;
  const hpRatio = mhp > 0 ? hp / mhp : 0;
  const mpRatio = mmp > 0 ? mp / mmp : 0;

  return (
          <div
                  className="absolute bottom-3 right-3 px-3 py-2 bg-black/60 text-white rounded-md font-sans text-sm leading-tight pointer-events-none"
                  role="status"
                  aria-label="map-hud"
          >
            <div className="font-semibold mb-1">{mapName}</div>
            <div className="flex items-center gap-1">
              <span>Gold:</span>
              <span className="font-semibold">{goldValue}</span>
              <span className="opacity-80" style={{ color: unitColor }}>{goldUnit}</span>
            </div>

            <div className="mt-2">HP</div>
            <div className="w-40 h-2.5 bg-white/15 rounded-full overflow-hidden mt-1">
              <div
                      className="h-full"
                      style={{ width: `${clamp01(hpRatio) * 100}%`, backgroundColor: "red" }}                />
            </div>

            <div className="mt-2">MP</div>
            <div className="w-40 h-2.5 bg-white/15 rounded-full overflow-hidden mt-1">
              <div
                      className="h-full bg-sky-500"
                      style={{ width: `${clamp01(mpRatio) * 100}%`, backgroundColor: "blue"  }}
              />
            </div>
          </div>
  );
});

export default MapHUD;

Notes

Uses Tailwind utility classes for layout/visuals. The only inline style is the dynamic bar width, which is computed at runtime.
The component uses observer so it re-renders when MobX-decorated platform data changes.
The engine remains the source of truth (gold, hp/mp, map name). When MZ updates these values, your HUD updates automatically.

Add the HUD to the Map screen Open menus/src/views/MapScreen.tsx and render the HUD inside the Map screen layout. Example (pseudo-structure):

// menus/src/views/MapScreen.tsx
import React from 'react';
import MapHUD from './tutorial/MapHUD';

export default function MapScreen(props: { pageData: any; isTestMenu: boolean; hasFocus: boolean }) {
  return (
    <div className="map-screen-root">
      {/* your existing Map UI */}

      {/* HUD overlay (positioned absolutely inside the overlay root) */}
      <MapHUD />
    </div>
  );
}

If your screen uses a main container with relative positioning, the absolute positioning in MapHUD will anchor relative to it; otherwise, it will anchor to the overlay root (which is pinned to the viewport by the plugin). Adjust styles as desired.

Build and run

cd menus
yarn build

Package and run your game as usual. Enter a map: you should see the HUD with the current map name, gold, and actor 0’s HP/MP bars. As values change (combat, items, map transfers), the HUD updates automatically.

Extensions

Show more party members by iterating gameParty.members()
Add EXP bars or level/TP
Swap to icons/sprites from platform.gameInfo.getIconPath()/getPortraitPath()