Files
wikideck/shared/bots/types.ts
T

85 lines
3.7 KiB
TypeScript

// Bot and simulation types. Engine-agnostic: bots talk to the rules engine only
// through EngineAdapter, so the same bots run against shared/game (see adapter.ts)
// and against the toy engine used by the self-tests. Pure: no I/O.
export type Seat = 0 | 1;
export type Rng = () => number;
export interface DeckSpec {
id: string;
/** Free-form tags for win-rate breakdowns: archetype, faction, keywords. */
tags: string[];
/** Whatever the engine needs to build the deck (card list, starter seed, ...). */
payload: unknown;
}
export interface MatchOutcome {
winner: Seat | null; // null = draw
reason?: string;
}
export interface EngineAdapter<S = unknown, A = unknown> {
name: string;
/** Ruleset ids this adapter knows (e.g. "v1", "v1.1"). */
rulesets(): string[];
/** Decks available for matchmaking under a ruleset. */
decks(ruleset: string): DeckSpec[];
createMatch(ruleset: string, decks: [DeckSpec, DeckSpec], seed: number): S;
/** Seat that must act now. */
toAct(state: S): Seat;
legalActions(state: S, seat: Seat): A[];
/** Must not mutate `state`. */
applyAction(state: S, action: A): S;
isOver(state: S): boolean;
result(state: S): MatchOutcome;
/** Turn counter (1-based, counts both players' turns). */
turn(state: S): number;
/** Heuristic value of the state for `seat`, roughly in [-1, 1]. */
evaluate(state: S, seat: Seat): number;
/** Card ids touched by an action (played, deployed...), for per-card stats. */
cardsOf(state: S, action: A): string[];
/** Short stable label for an action kind ("play", "pass", ...). */
actionKind(action: A): string;
/** Optional card metadata (numeric stats, keywords, faction) for per-stat balance analysis. */
cardMeta?(cardId: string): Record<string, number | string | string[]> | undefined;
/** Printed power an action puts on the board (-1 for non-plays). Used by the naive maxpower bot. */
actionPower?(state: S, action: A): number;
/**
* Counterfactual keyword value for a finished match: for each (seat, keyword) on cards that seat played,
* replay the same actions with that keyword removed from that seat's cards. `power` = own final total power
* lost, `flip` = 1 if the result got worse for that seat (win->draw/loss, draw->loss), `cards` = cards played.
*/
keywordValues?(final: S, decks: [DeckSpec, DeckSpec]): { seat: Seat; keyword: string; power: number; flip: number; cards: number }[];
/** Seat with the first-player advantage (defaults to toAct at match start). */
firstSeat?(state: S): Seat;
/** What `seat` may see (e.g. shared/game viewFor). Bots receive only this. Default: the state itself. */
observe?(state: S, seat: Seat): unknown;
/** A full state consistent with an observation, hidden parts sampled with `rng` (determinization). */
assume?(observation: unknown, seat: Seat, rng: Rng): S;
}
/** A bot is a pure function of what its seat can see (EngineAdapter.observe). ui-b reuses it as the browser AI. */
export type BotFn<O = unknown, A = unknown> = (observation: O, player: Seat, rng: Rng) => A;
export interface MatchRecord {
ruleset: string;
seed: number;
decks: [string, string];
deckTags: [string[], string[]];
bots: [string, string];
firstSeat: Seat; // seat that acted first
winner: Seat | null;
reason?: string;
turns: number;
actions: number;
truncated: boolean;
/** Eval for seat 0 at the start of each turn. */
evalTrace: number[];
/** Turn from which the eventual winner led on eval until the end (null for draws). */
decidedTurn: number | null;
cardsPlayed: [string[], string[]];
keywordValues?: { seat: Seat; keyword: string; power: number; flip: number; cards: number }[];
actionKinds: Record<string, number>;
ms: number;
}