miaoda-game-guandan-react

React bindings and a framework-neutral controller for a complete four-player Guandan match.

pnpm add miaoda-game-guandan-react

import { createGuandanGame, GuandanController, useGuandanView } from 'miaoda-game-guandan-react';

const controller = new GuandanController(
  createGuandanGame({ playerIds: ['a', 'b', 'c', 'd'], seed: 2026 }),
  'a',
);

function PlayControls() {
  const view = useGuandanView(controller);
  const candidate = view.legalActions.plays.plays[0];
  return candidate ? (
    <button
      onClick={() => controller.dispatch({
        type: 'play-cards',
        playerId: view.viewerId,
        candidate,
      })}
    >
      Play
    </button>
  ) : null;
}

Render play, tribute, return, assignment, and next-hand controls only from legalActions. Submit the complete candidate or choice object unchanged. The selected player view omits other hands, deck data, random state, and anti-tribute proofs.

Ownership and AI scheduling

This adapter owns the rules controller and React snapshot subscription. It does not schedule AI turns, create delays, or provide a game clock. A plain turn-based integration may dispatch an AI action immediately. If the application adds a delay, countdown, frame loop, or other gameplay timing, that timing belongs in the application controller and must use its injected clock/scheduler: use the production clock in the browser and a deterministic manual clock in tests. Do not call global setTimeout, setInterval, or requestAnimationFrame for gameplay timing.

Controllers that own timers or subscriptions must expose an idempotent destroy() and must be created and owned by the mounted application lifetime. Do not start external work from a controller constructor; start it from an explicit command or mounted effect so Strict Mode probing and test cleanup are safe.

Commits and reconnects

const unsubscribe = controller.onCommit(({ revision, view, events }) => {
  queueAnimations(events);
  persistRevision(revision);
  renderHud(view);
});

controller.replaceSnapshot(JSON.parse(savedJson), serverRevision);
controller.setViewerId('b');

Only accepted actions advance revision or publish commits. Commit views and normalized public events are detached. Invalid viewers, inconsistent snapshots, and lower revisions throw atomically. Reconnect snapshots must come from a trusted host because structural validation cannot prove their replay origin.

Phaser

pnpm add miaoda-game-command-phaser

import { PhaserGameBridge } from 'miaoda-game-command-phaser';

const bridge = new PhaserGameBridge().setup(controller);
bridge.consumeWith((event) => animateGuandanEvent(event));
bridge.dispatch({ type: 'pass-play', playerId: controller.view.viewerId });

bridge.destroy();
unsubscribe();

The bridge consumes accepted events in commit order. Only already-public tribute/return card ids and played cards enter the queue; hidden choices and authoritative state remain outside Phaser.