Files
wikideck/shared/game/types.ts
T
claudeandClaude Opus 5.5 f3b6097640 Engine core: align with DESIGN.md draft (Edit War)
mulberry32 uint32 seed with the §4 draw order, Topics with stats and Portals,
staggered reveal, initiative and underdog rules, queue/undo/commit/timeout
actions, §9 flat RulesConfig with zod bounds, viewFor hidden info, replay.
cards.ts left to engine-b; placeholder loaners in starter.ts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 22:55:51 -05:00

211 lines
7.0 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;
pageId: number;
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';
}
/** A Topic (lane) definition in a ruleset's topic pool (§3). */
export interface TopicDef {
id: string;
name: string;
stat: Stat;
/** Portal modifier id (§10.3), or null for a plain Topic. */
portal: string | null;
}
/**
* DESIGN §9 RulesConfig: every rule number as flat data so peer-hosted modes can
* override it. Use parseRuleset() for untrusted input.
* Engine additions beyond §9: topicPool holds TopicDefs inline (not a name);
* keywordParams / portalParams hold tunable numbers per keyword / portal id.
*/
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[];
bonusEnergy: number;
underdog: boolean;
topicCount: number;
distinctStats: boolean;
/** revealSchedule[i] = turn on which Topic i is revealed. Length = topicCount. */
revealSchedule: number[];
laneCapacity: number;
topicPool: TopicDef[];
costThresholds: number[];
/** Index = cost (0–6). */
powerByCost: number[];
onTopicBonus: number;
trendUp: number;
trendDown: number;
factionSynergyCap: number;
verifyStats: boolean;
/** Id of the percentile reference table used by cards.ts. */
percentiles: string;
/** Id of the starter deck list used by cards.ts. */
starterDecks: string;
keywordParams: Record<string, Record<string, number>>;
portalParams: Record<string, Record<string, number>>;
}
export interface CardInPlay {
card: GameCard;
owner: PlayerId;
lane: number;
/** Turn the card was revealed. */
turn: 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;
}
export interface LaneState {
topic: TopicDef;
revealed: boolean;
cards: [CardInPlay[], CardInPlay[]];
}
export type MatchPhase = 'planning' | 'over';
export type LogEvent =
| { t: 'turnStart'; turn: number; energy: [number, number]; initiative: PlayerId }
| { t: 'topicRevealed'; 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). */
initiative: 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 =
/** 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. */
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: {
/** null while face-down. */
topic: TopicDef | null;
/** 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'; }
}