miaoda-game-gin-rummy-rules

Immutable, engine-neutral rules for fixed two-player profile pagat-standard-2p-10card-knock10: opening upcard choice, draw-before-discard turns, optimal meld partitioning, Ace-low deadwood, knock/gin/layoff/undercut scoring, and hidden live cards.

pnpm add miaoda-game-gin-rummy-rules

Run a hand

import {
  applyGinRummyAction,
  createGinRummyGame,
  createGinRummyPlayerView,
} from 'miaoda-game-gin-rummy-rules';

let state = createGinRummyGame({ playerIds: ['human', 'bot'], seed: 2026 });
const playerId = state.activePlayerId;
const view = createGinRummyPlayerView(state, playerId);
const action = view.legalActions.canDrawStock
  ? { type: 'draw-stock' as const, playerId }
  : { type: 'discard' as const, playerId, cardId: view.legalActions.discardCardIds[0] };
const result = applyGinRummyAction(state, action);
if (result.ok) state = result.state;

Use canTakeDiscard, canDrawStock, discardCardIds, and knockCardIds from the safe view. A taken discard cannot be returned immediately. UI and bots should not recalculate melds, deadwood, knock eligibility, layoffs, or scoring.

Public events

import { projectGinRummyEvents } from 'miaoda-game-gin-rummy-rules';

if (result.ok) broadcast(projectGinRummyEvents(result.events));

A stock draw reports only the player and source, never the physical card id. Discards are public. After the round ends, both final meld/deadwood analyses are public settlement facts and are deeply detached by the projector. Unknown runtime event types throw.

Restore a snapshot

import { restoreGinRummyState } from 'miaoda-game-gin-rummy-rules';

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

Restore validation replays the initial seed, action history, draw provenance, and scores. Use validateGinRummyState for a non-throwing validation result.

Keep authoritative state on a trusted host. During play, send each participant only their createGinRummyPlayerView result and projected events. Dealer rotation and broader match policy remain game-owned.