miaoda-game-hearts-rules

Immutable, engine-neutral rules for four-player American Hearts profile pagat-american-4p: secret passing, legal trick play, hearts breaking, moon scoring, repeated hands, and target 100.

pnpm add miaoda-game-hearts-rules

Run a game

import {
  applyHeartsAction,
  createHeartsGame,
  createHeartsPlayerView,
} from 'miaoda-game-hearts-rules';

let state = createHeartsGame({
  playerIds: ['north', 'east', 'south', 'west'],
  seed: 2026,
});
const playerId = 'north';
const view = createHeartsPlayerView(state, playerId);
const pass = view.legalActions.pass;
if (pass) {
  const result = applyHeartsAction(state, {
    type: 'pass-cards',
    playerId,
    cardIds: pass.cardIds.slice(0, pass.requiredCount),
  });
  if (result.ok) state = result.state;
}

Drive passing, play, moon choice, and next-hand actions only from the safe view's legalActions. Passes move simultaneously after all four players submit. Only the moon shooter chooses moon scoring.

Public events

import { projectHeartsEvents } from 'miaoda-game-hearts-rules';

if (result.ok) {
  broadcast(projectHeartsEvents(result.events, playerId, result.state));
}

The committed state supplies the four allowed score-record keys. The viewer argument matches the shared controller contract; Hearts events are currently public and identical for every seated viewer. Pass events contain only submitter and completion facts, never the three selected card ids. Unknown runtime event types throw instead of being forwarded.

Restore a snapshot

import { restoreHeartsState } from 'miaoda-game-hearts-rules';

state = restoreHeartsState(JSON.parse(savedJson));

restoreHeartsState validates and detaches the parsed snapshot. Use validateHeartsState when a non-throwing validation result is preferable.

Keep authoritative state on a trusted host. Send each player only createHeartsPlayerView(state, playerId) and projected events; these omit opponent hands and pending secret pass selections. This profile permits point cards on trick one when a player cannot follow suit.