Files
wikideck/shared/game/types.ts
T
claudeandClaude Opus 5.5 7c86ed35f5 Game engine scaffold: seeded RNG, types, Ruleset schema, core loop
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>
2026-11-16 22:50:45 -05:00

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'; }
}