forked from WikiDeck/wikideck
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>
211 lines
7.0 KiB
TypeScript
211 lines
7.0 KiB
TypeScript
/**
|
||
* 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'; }
|
||
}
|