miaoda-game-rpg-battle-react

Use this React DOM adapter for turn-based RPG command menus, action playback, battle logs, and outcome panels. The core remains authoritative for planning, validation, ranking, resolution, and phase transitions.

Install

pnpm add miaoda-game-rpg-battle-react miaoda-game-rpg-battle-core

Minimal battle screen

import { useRpgBattleController, useRpgBattleView } from 'miaoda-game-rpg-battle-react';

export function BattlePanel({ world, rules, random }) {
  const game = useRpgBattleController(world, rules, random);
  const view = useRpgBattleView(game);

  const chooseAttack = () => game.plan({
    id: 'hero-1', actorId: 'hero', actionId: 'slash', targetIds: ['goblin'], payload: {},
  });

  return (
    <section>
      <p>Phase: {view.state.phase}</p>
      <button onClick={chooseAttack}>Slash</button>
      <button onClick={() => game.beginResolution()}>Resolve turn</button>
      {view.state.phase === 'resolving' && <button onClick={() => game.resolveNext()}>Next action</button>}
      {view.lastEvents.map((event, index) => <pre key={index}>{JSON.stringify(event)}</pre>)}
    </section>
  );
}

Each operation returns { ok: false, error } when the core rejects a command or phase transition. Use view.lastEvents for animation and logs; map stable rule validation codes to player-facing text in your BattleRules layer.

Do not call plan, cancel, beginResolution, or resolveNext synchronously from onChange; defer the operation until the callback returns.

Save and determinism

Persist view.state together with the current position of the injected random source. The controller does not own storage, network authority, or RNG serialization. Do not send hidden target information or full authoritative world state to an untrusted client.

Public API

RpgBattleController, useRpgBattleController, useRpgBattleView, RpgBattleView, operation result types, and all battle-core exports are available. React 18.2+ is required.