Battle System Architecture

The RPGReact battle system is a collection of React components that work together to render battles using data from RPG Maker MZ's battle engine. This guide explains the architecture, component relationships, and how to customize the battle UI.

Architecture Overview

The battle system uses a single-direction data flow from RMMZ to React:

RMMZ Battle Engine (Game_Battler, BattleManager, etc.)
    ↓
Override Files (override_scene_battle.js, override_battle_manager.js)
    ↓
RPGBridge Events (RPGEventType.BATTLE_*)
    ↓
React Battle Components (observe and render)

React components never modify game state directly. They only:

1. Observe MobX-wrapped game objects

2. Render UI based on that state

3. Call RMMZ commands through pageData.commands

Core Components

BattleMain.tsx

Location: menus/src/views/battle/BattleMain.tsx

The root battle component that orchestrates all battle UI elements.

Key responsibilities:

• Mounts all battle sub-components

• Manages battle phase transitions

• Handles battle end/victory/defeat

• Coordinates between input, display, and results screens

Structure:

<div className="battle-main">
  <BattleParty />        {/* Party member status */}
  <BattleLog />          {/* Combat log */}
  <BattleAtb />          {/* ATB gauges (if ATB mode) */}
  <BattleInput />        {/* Command selection */}
  <TargetCursor />       {/* Target selection overlay */}
  <BattleResults />      {/* Victory screen with rewards */}
</div>

Props: Standard BaseMenuScreenProps

BattleParty.tsx

Location: menus/src/views/battle/BattleParty.tsx

Displays all party members' HP/MP/TP gauges and status.

Features:

• Real-time HP/MP updates using MobX observers

• Status ailment icons

• ATB gauge integration

• Click-to-target (if target selection active)

Key code pattern:

const BattleParty = observer((props) => {
  const members = props.pageData.runtime.gameParty.battleMembers();

  return members.map(actor => (
    <Observer key={actor._actorId}>
      {() => (
        <div className="party-member">
          <div>HP: {actor.hp} / {actor.mhp}</div>
          <div>MP: {actor.mp} / {actor.mmp}</div>
          {/* Automatically re-renders when hp/mp change */}
        </div>
      )}
    </Observer>
  ));
});

BattleInput.tsx

Location: menus/src/views/battle/BattleInput.tsx

Handles command input for the active battler (Attack, Skill, Guard, Item, etc.).

Flow:

1. Shows when BattleManager.isInputting() is true

2. Displays commands for current actor

3. Calls pageData.commands.battleCommand(commandName) on selection

4. May trigger SubSelectionWindow for skills/items

5. May trigger target selection

Command types:

• Attack → Target selection

• Skill → Skill list → Target selection

• Guard → Immediate action

• Item → Item list → Target selection

Layout note:

• Ensure the command window stacks above the party panel (z-index on the battle input container) so the full width remains clickable even with 3D transforms.

SubSelectionWindow.tsx

Location: menus/src/views/battle/SubSelectionWindow.tsx

Generic selection window for skills/items during battle input.

Props:

• items - Array of skills or items

• onSelect(item) - Callback when item chosen

• onCancel() - Back to command menu

Uses:

• Chooser component for list navigation

• Shows item/skill costs and descriptions

TargetCursor.tsx & TargetCancel.tsx

Location: menus/src/views/battle/TargetCursor.tsx, TargetCancel.tsx

Visual indicators for target selection.

TargetCursor:

• Renders cursor over selected enemy/ally

• Positioned using battler sprite coordinates

• Shows flashing/animated cursor

TargetCancel:

• "Cancel" button to return to command menu

• Always visible during target selection

BattleLog.tsx

Location: menus/src/views/battle/BattleLog.tsx

Scrolling combat log showing actions, damage, and effects.

Features:

• Auto-scrolls to latest entry

• Color-coded messages (damage red, healing green)

• Special code support for rich text

Message format:

Harold used Attack!
Slime took 35 damage!
Harold gained 5 MP!

BattleAtb.tsx

Location: menus/src/views/battle/BattleAtb.tsx

ATB (Active Time Battle) gauge display for Time Progress or Active battle modes.

Only renders if:

const battleSystem = $dataSystem.battleSystem;
const isAtb = battleSystem === 1 || battleSystem === 2;
// 0 = Turn-based, 1 = ATB Active, 2 = ATB Wait

Shows:

• Individual ATB gauges for each battler

• Turn order preview

• Cast time indicators

BattleResults.tsx

Location: menus/src/views/battle/BattleResults.tsx

Victory screen showing EXP, gold, items, and level-ups.

Components used:

• PartyMemberReward - Shows XP gain animation and level-ups for each member

• Displays total gold and item drops

• "Next" button to continue

Flow:

1. Fades in after victory

2. Animates XP bars for each party member

3. Shows level-up notifications

4. Waits for player confirmation

5. Calls onContinue() to close and return to map

Component Communication

Event-Driven Updates

Battle state changes trigger events from overrides:

// In override_scene_battle.js
event(RPGEventType.BATTLE_ACTION,
      RPGBattleEventSpecifier.START,
      { battler, action });

event(RPGEventType.BATTLE_COMMAND,
      RPGBattleCommandSpecifier.INPUT,
      { commands });

React components listen via RPGBridge.AddEventHandler():

useEffect(() => {
  const handler = {
    id: 'battle-state-handler',
    handler: (event) => {
      if (event.eventType === RPGEventType.BATTLE_ACTION) {
        // Update UI based on battle action
      }
    }
  };
  RPGBridge.AddEventHandler(handler);

  return () => RPGBridge.RemoveEventHandlerById('battle-state-handler');
}, []);

Command Execution

React calls RMMZ commands through the pageData commands object:

// User selects "Attack"
props.pageData.commands.battleCommand('attack');

// User selects target
props.pageData.commands.selectTarget(enemyIndex);

// User confirms action
props.pageData.commands.confirmAction();

Commands are defined in the overrides and execute RMMZ battle logic.

Battle Flow

Turn-Based Battle

1. Battle Start
   ↓
2. Turn Start → Input Phase
   - BattleInput shows for active actor
   - Player selects command
   - Player selects target (if needed)
   ↓
3. Action Execution Phase
   - Actions execute in speed order
   - BattleLog updates with results
   - HP/MP/TP bars animate
   ↓
4. Turn End
   - Check for victory/defeat/escape
   - If battle continues, go to step 2
   ↓
5. Battle End
   - BattleResults shows (if victory)
   - OR GameOver screen (if defeat)

ATB Battle

1. Battle Start
   - All ATB gauges begin filling
   ↓
2. Continuous Loop
   - ATB gauges fill based on agility
   - When gauge full → Input Phase for that actor
     - Time continues (Active) or pauses (Wait)
     - Player selects command/target
   - Action executes immediately after input
   - BattleLog updates
   ↓
3. Battle End (same as turn-based)

Customization Examples

Custom Battle UI Layout

// Create custom BattleMain layout
const CustomBattleMain: React.FC<BaseMenuScreenProps> = (props) => {
  return (
    <div className="custom-battle">
      {/* Top: Enemy info */}
      <div className="enemy-area">
        {/* Custom enemy display */}
      </div>

      {/* Middle: Log */}
      <BattleLog {...props} />

      {/* Bottom: Party and commands */}
      <div className="battle-bottom">
        <BattleParty {...props} />
        <BattleInput {...props} />
      </div>

      {/* Overlays */}
      <TargetCursor {...props} />
      <BattleResults {...props} />
    </div>
  );
};

Custom Party Member Display

// Simplified party member card
const MinimalPartyMember = observer(({ actor }) => {
  return (
    <div className="mini-party-card">
      <div>{actor.name()}</div>
      <div className="hp-bar" style={{
        width: `${(actor.hp / actor.mhp) * 100}%`
      }} />
    </div>
  );
});

// Use in BattleParty alternative
const CustomBattleParty = observer((props) => {
  const members = props.pageData.runtime.gameParty.battleMembers();

  return (
    <div className="custom-party">
      {members.map(actor => (
        <MinimalPartyMember key={actor._actorId} actor={actor} />
      ))}
    </div>
  );
});

Custom Battle Log Formatting

const CustomBattleLog = ({ messages }) => {
  const formatMessage = (msg: string) => {
    // Custom formatting
    if (msg.includes('damage')) {
      return <span className="damage-text">{msg}</span>;
    }
    if (msg.includes('healing')) {
      return <span className="heal-text">{msg}</span>;
    }
    return msg;
  };

  return (
    <div className="custom-log">
      {messages.map((msg, i) => (
        <div key={i}>{formatMessage(msg)}</div>
      ))}
    </div>
  );
};

Adding Custom Battle HUD Elements

const BattleHUD = observer((props) => {
  const party = props.pageData.runtime.gameParty;
  const averageHpPercent = party.battleMembers()
    .reduce((sum, m) => sum + (m.hp / m.mhp), 0) / party.size();

  return (
    <div className="battle-hud">
      <div>Turn: {$gameTroop.turnCount()}</div>
      <div>Party HP: {Math.floor(averageHpPercent * 100)}%</div>
      <div>Enemies: {$gameTroop.aliveMembers().length}</div>
    </div>
  );
});

Performance Considerations

Use Observer Granularly

// ❌ BAD: Entire list re-renders when any member changes
const BattleParty = observer((props) => {
  const members = props.pageData.runtime.gameParty.battleMembers();
  return members.map(actor => (
    <div>HP: {actor.hp}</div>
  ));
});

// ✅ GOOD: Only affected member re-renders
const BattleParty = (props) => {
  const members = props.pageData.runtime.gameParty.battleMembers();
  return members.map(actor => (
    <Observer key={actor._actorId}>
      {() => <div>HP: {actor.hp}</div>}
    </Observer>
  ));
};

Avoid Expensive Calculations in Render

// ❌ BAD: Recalculates every render
const BattleStats = observer(() => {
  const damageDealt = calculateTotalDamage(); // Expensive!
  return <div>Damage: {damageDealt}</div>;
});

// ✅ GOOD: Cache calculation
const BattleStats = observer(() => {
  const damageDealt = useMemo(
    () => calculateTotalDamage(),
    [battleLog.length] // Recalc only when log changes
  );
  return <div>Damage: {damageDealt}</div>;
});

Debugging Battle Issues

Check Battle State

// Add debug overlay
const BattleDebug = observer(() => {
  return (
    <div className="debug-overlay">
      <div>Phase: {BattleManager.phase()}</div>
      <div>Inputting: {BattleManager.isInputting() ? 'Yes' : 'No'}</div>
      <div>Active: {BattleManager.actor()?.name() || 'None'}</div>
      <div>Turn: {$gameTroop.turnCount()}</div>
    </div>
  );
});

Log Battle Events

useEffect(() => {
  const handler = {
    id: 'battle-event-logger',
    handler: (event) => {
      if (event.eventType === RPGEventType.BATTLE_ACTION ||
          event.eventType === RPGEventType.BATTLE_COMMAND) {
        console.log('[Battle Event]', event);
      }
    }
  };
  RPGBridge.AddEventHandler(handler);
  return () => RPGBridge.RemoveEventHandlerById('battle-event-logger');
}, []);

See Also

• Level-Up Animation Tutorial

• State Management Best Practices

• InputContext

• PartyMemberFull vs PartyMemberCompact