85 lines
3.7 KiB
TypeScript
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;
|
|
}
|