/** * WikiDeck game engine types (off-chain). Implements docs/game/DESIGN.md ("Edit War"). * Everything here is plain JSON data: MatchState round-trips through * JSON.stringify/parse with no loss (no Maps, classes or functions). * 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; a card's faction (DESIGN §1.5). */ export type Faction = 'Space' | 'Nature' | 'People' | 'Science' | 'History' | 'Culture'; export const FACTIONS: readonly Faction[] = ['Space', 'Nature', 'People', 'Science', 'History', 'Culture']; export type Stat = 'attention' | 'depth' | 'reach'; export const STATS: readonly Stat[] = ['attention', 'depth', 'reach']; export type Rarity = 'Common' | 'Rare' | 'Epic' | 'Legendary'; /** * A card as the engine sees it: already derived (DESIGN §1) by cards.ts from a * host-frozen CardInput. The engine never reads raw snapshot stats. Hosts/modes * may adjust fields (e.g. power) before createMatch; the engine does not re-derive. */ export interface GameCard { /** Unique within one deck (the NFT card hash, or `loaner::`). */ cardId: string; /** null for unpinned loaners (DESIGN §2.1): copies then count per cardId. */ pageId: number | null; title: string; faction: Faction; /** Cosmetic in v1 (§1.7). */ rarity: Rarity; cost: number; power: number; home: Stat; /** Live trend arrow, frozen at match start (§1.6). Adds to power in every Topic. */ trend: -1 | 0 | 1; keyword: string | null; /** 'owned' = an NFT the player holds (never moved or burned by a match). */ source: 'owned' | 'loaner'; /** Host plausibility result (§1.10). Derivation already applied uncheckedCostCap. Default: 'loaner' for loaners, 'verified' for owned. */ check?: 'verified' | 'unverified' | 'unchecked' | 'loaner'; } /** A Topic (lane) definition in a ruleset's topic pool (§3). */ export interface TopicDef { id: string; name: string; stat: Stat; /** Portal kind id in PORTALS (§10.3), or null for a plain Topic. Numbers: Ruleset.portalParams[topic id] (falls back to [portal id]). */ portal: string | null; } /** * DESIGN §9 RulesConfig: every rule number as flat data so peer-hosted modes can * override it. Use parseRuleset() for untrusted input. */ export interface Ruleset { version: string; deckSize: number; maxCopiesPerPage: number; maxLoaners: number; openingHand: number; handLimit: number; mulligan: boolean; turns: number; turnSeconds: number; afkTurns: number; /** energyByTurn[t-1] is the base energy on turn t. Length must be ≥ turns. */ energyByTurn: number[]; /** Unspent energy carried to next turn, capped at this. */ energyCarryMax: number; bonusEnergy: number; underdog: boolean; topicCount: number; distinctStats: boolean; /** portalReveal[i] = turn on which Topic i's Portal is revealed (stats are always visible). Length = topicCount. */ portalReveal: number[]; laneCapacity: number; topicPool: TopicDef[]; /** Per-keyword numbers, keyed by keyword id. */ keywordParams: Record>; /** Per-Portal numbers, keyed by Topic id (or Portal kind id as a fallback). */ portalParams: Record>; costThresholds: number[]; /** Index = cost (0–6). */ powerByCost: number[]; /** Index = cost (0–6): on-topic bonus. */ onTopicBonus: number[]; vanillaBonus: number; /** Keyword ids whose hooks run. Cards with a disabled keyword are vanilla (derivation handles power). */ keywordsEnabled: string[]; ownedCards: boolean; trendUp: number; trendDown: number; trendMinDaily: number; uncheckedCostCap: number; factionSynergyCap: number; verifyStats: boolean; /** Id of the percentile reference table used by derive.ts. */ percentiles: string; /** Id of the starter deck list. */ starterDecks: string; } export interface CardInPlay { card: GameCard; owner: PlayerId; lane: number; /** Turn the card was revealed. */ turn: number; /** Global reveal sequence number (1, 2, 3 … across both seats and all turns). */ seq: number; /** Permanent power changes from effects (on-reveal buffs etc.). */ bonus: number; } export interface QueuedPlay { cardId: string; lane: number } export interface PlayerState { deck: GameCard[]; hand: GameCard[]; /** Energy available this turn (before queued plays). */ energy: number; /** Plays chosen this turn, hidden from the opponent until reveal. Order matters. */ queue: QueuedPlay[]; committed: boolean; /** Consecutive timeouts with nothing queued (§7 afkTurns). */ afk: number; /** Energy carried into this turn (already included in `energy`). */ carry: number; } export interface LaneState { /** Stat and name are always visible; the Portal only once portalRevealed. */ topic: TopicDef; portalRevealed: boolean; cards: [CardInPlay[], CardInPlay[]]; } export type MatchPhase = 'planning' | 'over'; export type LogEvent = | { t: 'turnStart'; turn: number; energy: [number, number]; initiative: PlayerId } | { t: 'portalRevealed'; lane: number; topic: TopicDef } | { t: 'underdog'; player: PlayerId } | { t: 'draw'; player: PlayerId; cardId: string } | { t: 'reveal'; player: PlayerId; cardId: string; lane: number } | { t: 'fizzle'; player: PlayerId; cardId: string; lane: number } | { t: 'effect'; source: string; player: PlayerId; text: string } | { t: 'concede'; player: PlayerId; afk: boolean } | { t: 'matchOver'; result: MatchResult }; export interface MatchState { schema: 'wikideck-match/1'; engineVersion: number; ruleset: Ruleset; seed: number; rng: RngState; /** 1-based current turn. */ turn: number; phase: MatchPhase; /** Player who reveals first this turn (§5.4). Alternates every turn. */ initiative: PlayerId; /** Last reveal sequence number handed out (CardInPlay.seq). */ revealSeq: number; 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 = /** Queue a card from hand into a lane (§5.3). */ | { type: 'play'; player: PlayerId; cardId: string; lane: number } /** Take back a queued play this turn (refunds its energy). */ | { type: 'undo'; player: PlayerId; cardId: string } /** Commit the queue (empty = pass). When both have committed, the turn resolves. */ | { type: 'commit'; player: PlayerId } /** The host's turn timer expired for this player: commits what's queued, counts toward afkTurns if empty. */ | { type: 'timeout'; player: PlayerId } | { type: 'concede'; player: PlayerId }; export interface MatchResult { /** null = draw. */ winner: PlayerId | null; reason: 'topics' | 'totalPower' | 'draw' | 'concede' | 'afk'; topicsLed: [number, number]; /** lanePower[lane][player] at the end, including "at scoring" Portals. */ lanePower: [number, number][]; totalPower: [number, number]; turns: number; } /** What one player is allowed to see. UI and AI read only this, never raw MatchState. */ export interface PlayerView { you: PlayerId; ruleset: Ruleset; turn: number; phase: MatchPhase; initiative: PlayerId; energy: number; /** Energy left after your queued plays. */ energyLeft: number; hand: GameCard[]; queue: QueuedPlay[]; committed: boolean; deckCount: number; opponent: { handCount: number; deckCount: number; queuedCount: number; committed: boolean }; lanes: { /** Always visible; `portal` is null until the Portal is revealed. */ topic: TopicDef; portalRevealed: boolean; /** cards[0] = yours, cards[1] = opponent's (revealed cards only). */ cards: [CardInPlay[], CardInPlay[]]; /** Lane power of each card in `cards`, same shape. */ cardPower: [number[], number[]]; /** power[0] = yours, power[1] = opponent's. */ power: [number, number]; /** Who leads this Topic from your point of view. */ leader: 'you' | 'opponent' | null; }[]; result: MatchResult | null; } export class IllegalActionError extends Error { constructor(message: string) { super(message); this.name = 'IllegalActionError'; } }