forked from WikiDeck/wikideck
Bots are pure (state, player, rng) => action over an EngineAdapter; shared/bots/game-adapter.ts adapts the shared/game API (hidden staged plays, determinized lookahead). scripts/sim/run.ts runs N matches per ruleset across child processes and writes per-ruleset markdown/JSON. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
74 lines
2.8 KiB
TypeScript
74 lines
2.8 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;
|
|
/** Seat with the first-player advantage (defaults to toAct at match start). */
|
|
firstSeat?(state: S): Seat;
|
|
/** Resample information hidden from `seat` (opponent hand/staged plays, deck order) before searching. */
|
|
determinize?(state: S, seat: Seat, rng: Rng): S;
|
|
}
|
|
|
|
/** A bot is a pure function of the state it sees. ui-b can reuse it as the browser AI. */
|
|
export type BotFn<S = unknown, A = unknown> = (state: S, 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[]];
|
|
actionKinds: Record<string, number>;
|
|
ms: number;
|
|
}
|