miaoda-game-gou-ji-rules

Immutable, engine-neutral rules for fixed six-player Qingdao Gou Ji profile pagat-qingdao-main-complete-match-v1: opening claims, revolution, tribute/return, opposite-seat duels, Shao Pai, Rang Pai, endgame order, placements, and cumulative team scoring.

pnpm add miaoda-game-gou-ji-rules

Run a match

import {
  applyGouJiAction,
  createGouJiGame,
  createGouJiPlayerView,
} from 'miaoda-game-gou-ji-rules';

let state = createGouJiGame({
  playerOrder: ['a', 'b', 'c', 'd', 'e', 'f'],
  seed: 2026,
});
const playerId = state.playerOrder[0];
const view = createGouJiPlayerView(state, playerId);
if (view.legalActions.canClaimOpeningLead) {
  const result = applyGouJiAction(state, { type: 'claim-opening-lead', playerId });
  if (result.ok) state = result.state;
}

Render commands only from legalActions. Use suggestedPlays for ready-made selections and playConstraint for manual physical-card selection; every submitted action is revalidated. Do not derive tribute strength, response eligibility, Shao Pai order, Rang Pai seats, or endgame order in UI code.

Public events

import { projectGouJiEvents } from 'miaoda-game-gou-ji-rules';

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

The projector returns detached, explicitly rebuilt events. Tribute and return events contain only the obligation, players, and card count; exchanged card ids stay private. A Shao Pai declaration contains only its group count. Card ids become public only in cards-played or shao-pai-advanced after those groups are actually played. Settlement records accept only the six committed player ids, and unknown runtime event types throw instead of being forwarded.

Restore a snapshot

import { restoreGouJiState } from 'miaoda-game-gou-ji-rules';

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

Restore verifies seed, deal evidence, and accepted-action replay provenance before returning a detached snapshot. Use validateGouJiState for a non-throwing result. Keep authoritative hands, deck order, tribute card ids, pending Shao Pai groups, seed, and action history on a trusted host; clients receive only their player view and projected events. GOU_JI_ZH_CN_LABELS provides optional default UI copy.