Files
wikideck/shared/game/types.ts
T

233 lines
8.3 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* 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:<pageId>:<n>`). */
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<string, Record<string, number>>;
/** Per-Portal numbers, keyed by Topic id (or Portal kind id as a fallback). */
portalParams: Record<string, Record<string, number>>;
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;
/** v1.1 hook (derive.ts): 'home' gives Culture cards a home-stat keyword. v1: 'faction'. */
cultureKeyword: 'faction' | 'home';
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'; }
}