forked from WikiDeck/wikideck
Pure deterministic off-chain engine in shared/game: createMatch, legalActions, applyAction, isOver, result, viewFor, serialize/deserialize, replay. Placeholder Snap-style lanes rules until DESIGN.md v1; keyword hook registry for engine-b. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
159 lines
5.3 KiB
TypeScript
159 lines
5.3 KiB
TypeScript
/**
|
|
* WikiDeck game engine types (off-chain). Everything here is plain JSON data:
|
|
* MatchState round-trips through JSON.stringify/parse with no loss.
|
|
* Contract: docs/game/ENGINE_API.md. Announce changes on claude/wikideck#3.
|
|
*/
|
|
import type { RngState } from './rng.ts';
|
|
|
|
export type PlayerId = 0 | 1;
|
|
export const PLAYERS: readonly PlayerId[] = [0, 1];
|
|
|
|
/** Category buckets from server/wiki.ts. */
|
|
export type Category = 'Space' | 'Nature' | 'People' | 'Science' | 'History' | 'Culture';
|
|
|
|
/** A card as the engine sees it. Built from enrichment data by cards.ts, or a starter/loaner card. */
|
|
export interface GameCard {
|
|
/** Unique within one deck (e.g. the NFT card hash, or `starter:<pageId>:<n>`). */
|
|
id: string;
|
|
name: string;
|
|
pageId: number | null;
|
|
category: Category;
|
|
cost: number;
|
|
power: number;
|
|
/** Keyword id from the ruleset's keyword list, or null. */
|
|
keyword: string | null;
|
|
/** 'owned' = an NFT the player holds (never moved or burned by a match). */
|
|
source: 'owned' | 'starter' | 'loaner';
|
|
/** Optional display/tie-break data; never used for rules unless a keyword says so. */
|
|
meta?: Record<string, string | number | boolean | null>;
|
|
}
|
|
|
|
/** All rule numbers. Peer-hosted modes override these as data (see ruleset.ts). */
|
|
export interface Ruleset {
|
|
id: string;
|
|
name: string;
|
|
version: number;
|
|
lanes: number;
|
|
/** Cards that may sit on one side of one lane. */
|
|
laneCapacity: number;
|
|
maxTurns: number;
|
|
deck: { min: number; max: number; maxCopiesPerPage: number };
|
|
hand: { start: number; max: number; drawPerTurn: number };
|
|
/** Energy available on turn t (1-based) = min(max, start + (t - 1) * perTurn). Unspent energy is lost. */
|
|
energy: { start: number; perTurn: number; max: number };
|
|
/** Keyword ids that cards may carry in this mode, with tunable numbers per keyword. */
|
|
keywords: Record<string, Record<string, number>>;
|
|
laneModifiers: {
|
|
/** Pool of lane modifier ids; one is drawn (without replacement) per lane at match start. */
|
|
pool: string[];
|
|
/** Turn on which lane i's modifier becomes visible and active (length = lanes). */
|
|
revealTurns: number[];
|
|
params: Record<string, Record<string, number>>;
|
|
};
|
|
/** How the match ends when lanes tie on count. */
|
|
tieBreak: 'totalPower' | 'draw';
|
|
}
|
|
|
|
export interface CardInPlay {
|
|
card: GameCard;
|
|
owner: PlayerId;
|
|
lane: number;
|
|
/** Turn the card was revealed. */
|
|
turn: number;
|
|
/** Permanent power changes from effects (onReveal buffs etc.). */
|
|
bonus: number;
|
|
}
|
|
|
|
export interface StagedPlay { cardId: string; lane: number }
|
|
|
|
export interface PlayerState {
|
|
deck: GameCard[];
|
|
hand: GameCard[];
|
|
/** Energy left this turn (after staging). */
|
|
energy: number;
|
|
/** Plays chosen this turn, hidden from the opponent until reveal. Order matters. */
|
|
staged: StagedPlay[];
|
|
ended: boolean;
|
|
discard: GameCard[];
|
|
}
|
|
|
|
export interface LaneState {
|
|
modifier: string | null;
|
|
cards: [CardInPlay[], CardInPlay[]];
|
|
}
|
|
|
|
export type MatchPhase = 'planning' | 'over';
|
|
|
|
export type LogEvent =
|
|
| { t: 'turnStart'; turn: number; energy: [number, number] }
|
|
| { t: 'draw'; player: PlayerId; cardId: string }
|
|
| { t: 'reveal'; player: PlayerId; cardId: string; lane: number }
|
|
| { t: 'laneRevealed'; lane: number; modifier: string | null }
|
|
| { t: 'effect'; source: string; player: PlayerId; text: string }
|
|
| { t: 'concede'; player: PlayerId }
|
|
| { t: 'matchOver'; result: MatchResult };
|
|
|
|
export interface MatchState {
|
|
schema: 'wikideck-match/1';
|
|
ruleset: Ruleset;
|
|
seed: string;
|
|
rng: RngState;
|
|
turn: number;
|
|
phase: MatchPhase;
|
|
/** Player who reveals first this turn. */
|
|
firstToReveal: PlayerId;
|
|
players: [PlayerState, PlayerState];
|
|
lanes: LaneState[];
|
|
log: LogEvent[];
|
|
/** Every action applied so far: (ruleset, decks, seed, actions) replays the match exactly. */
|
|
actions: Action[];
|
|
result: MatchResult | null;
|
|
}
|
|
|
|
export type Action =
|
|
| { type: 'play'; player: PlayerId; cardId: string; lane: number }
|
|
/** Take back a staged (unrevealed) play this turn; refunds its energy. */
|
|
| { type: 'unstage'; player: PlayerId; cardId: string }
|
|
| { type: 'endTurn'; player: PlayerId }
|
|
| { type: 'concede'; player: PlayerId };
|
|
|
|
export interface MatchResult {
|
|
/** null = draw. */
|
|
winner: PlayerId | null;
|
|
reason: 'lanes' | 'totalPower' | 'draw' | 'concede';
|
|
lanesWon: [number, number];
|
|
/** lanePower[lane][player] at the end. */
|
|
lanePower: [number, number][];
|
|
totalPower: [number, number];
|
|
turns: number;
|
|
}
|
|
|
|
/** What one player is allowed to see. Use this for UI and AI, never raw MatchState. */
|
|
export interface PlayerView {
|
|
you: PlayerId;
|
|
ruleset: Ruleset;
|
|
turn: number;
|
|
phase: MatchPhase;
|
|
firstToReveal: PlayerId;
|
|
energy: number;
|
|
hand: GameCard[];
|
|
staged: StagedPlay[];
|
|
ended: boolean;
|
|
deckCount: number;
|
|
opponent: { handCount: number; deckCount: number; stagedCount: number; ended: boolean };
|
|
lanes: {
|
|
/** null when not yet revealed. */
|
|
modifier: string | null;
|
|
modifierRevealed: boolean;
|
|
/** cards[0] = yours, cards[1] = opponent's (revealed only). */
|
|
cards: [CardInPlay[], CardInPlay[]];
|
|
/** power[0] = yours, power[1] = opponent's. */
|
|
power: [number, number];
|
|
}[];
|
|
result: MatchResult | null;
|
|
}
|
|
|
|
export class IllegalActionError extends Error {
|
|
constructor(message: string) { super(message); this.name = 'IllegalActionError'; }
|
|
}
|