sim-balance: bots (random/greedy/lookahead), sim runner and stats

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>
This commit is contained in:
2026-11-16 22:54:53 -05:00
co-authored by Claude Opus 5.5
parent 1d3c5e5743
commit 9841622ac7
8 changed files with 884 additions and 0 deletions
+51
View File
@@ -0,0 +1,51 @@
import { makeBot, mulberry32 } from '../../shared/bots/index.ts';
import type { BotFn, DeckSpec, EngineAdapter, MatchRecord, Seat } from '../../shared/bots/types.ts';
export const MAX_ACTIONS = 2000;
export function playMatch<S, A>(
engine: EngineAdapter<S, A>, ruleset: string, decks: [DeckSpec, DeckSpec], botNames: [string, string], seed: number,
): MatchRecord {
const t0 = performance.now();
const bots: [BotFn<S, A>, BotFn<S, A>] = [makeBot(botNames[0], engine), makeBot(botNames[1], engine)];
const rng = [mulberry32(seed ^ 0x9e3779b9), mulberry32(seed ^ 0x85ebca6b)];
let s = engine.createMatch(ruleset, decks, seed);
const firstSeat = engine.firstSeat ? engine.firstSeat(s) : engine.toAct(s);
const evalTrace: number[] = [];
const cardsPlayed: [string[], string[]] = [[], []];
const actionKinds: Record<string, number> = {};
let actions = 0, lastTurn = -1;
while (!engine.isOver(s) && actions < MAX_ACTIONS) {
const turn = engine.turn(s);
if (turn !== lastTurn) { evalTrace.push(engine.evaluate(s, 0)); lastTurn = turn; }
const seat = engine.toAct(s);
const a = bots[seat](s, seat, rng[seat]);
for (const c of engine.cardsOf(s, a)) cardsPlayed[seat].push(c);
const k = engine.actionKind(a);
actionKinds[k] = (actionKinds[k] ?? 0) + 1;
s = engine.applyAction(s, a);
actions++;
}
const truncated = !engine.isOver(s);
const { winner, reason } = truncated ? { winner: null, reason: 'action-cap' } : engine.result(s);
return {
ruleset, seed,
decks: [decks[0].id, decks[1].id],
deckTags: [decks[0].tags, decks[1].tags],
bots: [botNames[0], botNames[1]],
firstSeat, winner, reason,
turns: engine.turn(s), actions, truncated,
evalTrace, decidedTurn: decidedTurn(evalTrace, winner),
cardsPlayed, actionKinds,
ms: performance.now() - t0,
};
}
/** First turn (1-based) from which the eventual winner stayed ahead on eval through the end. */
export function decidedTurn(trace: number[], winner: Seat | null): number | null {
if (winner === null || !trace.length) return null;
const sign = winner === 0 ? 1 : -1;
let t = trace.length;
while (t > 0 && trace[t - 1] * sign > 0.05) t--;
return Math.min(t + 1, trace.length);
}
+128
View File
@@ -0,0 +1,128 @@
// Balance simulation runner.
// npx tsx scripts/sim/run.ts --engine game --ruleset v1 --matches 5000 --workers 6 --out sim-out
// Writes <out>/<ruleset>.jsonl (records), <out>/<ruleset>.stats.json and <out>/<ruleset>.md.
import { fork } from 'node:child_process';
import { fileURLToPath } from 'node:url';
import { mkdirSync, writeFileSync, createWriteStream, readFileSync } from 'node:fs';
import { join } from 'node:path';
import { mulberry32 } from '../../shared/bots/index.ts';
import type { DeckSpec, EngineAdapter, MatchRecord } from '../../shared/bots/types.ts';
import { playMatch } from './match.ts';
import { aggregate, toMarkdown } from './stats.ts';
export async function loadEngine(name: string): Promise<EngineAdapter<any, any>> {
if (name === 'toy') return (await import('./toy-engine.ts')).toyEngine;
if (name === 'game') {
const { makeGameEngine } = await import('../../shared/bots/game-adapter.ts');
const { DEFAULT_RULESET } = await import('../../shared/game/index.ts');
const file = process.env.SIM_RULESETS;
const rulesets: Record<string, any> = { base: DEFAULT_RULESET };
if (file) {
// { "<id>": { "extends": "base", ...partial Ruleset } } — shallow-merged per top-level key.
const variants = JSON.parse(readFileSync(file, 'utf8')) as Record<string, any>;
for (const [id, v] of Object.entries(variants)) {
const { extends: parent = 'base', ...patch } = v;
const base = rulesets[parent];
const merged: any = { ...base };
for (const [k, val] of Object.entries(patch)) merged[k] = val && typeof val === 'object' && !Array.isArray(val) ? { ...base[k], ...val } : val;
rulesets[id] = { ...merged, id: v.id ?? `sim-${id}`.replace(/[^a-z0-9-]/g, '-').slice(0, 48) };
}
}
return makeGameEngine({ rulesets });
}
throw new Error(`unknown engine ${name}`);
}
/** Bot pairings and their share of the schedule. Symmetric pairs carry the balance stats. */
export const DEFAULT_MIX: [string, string, number][] = [
['greedy', 'greedy', 0.55],
['lookahead-lite', 'lookahead-lite', 0.15],
['random', 'random', 0.1],
['greedy', 'lookahead-lite', 0.1],
['random', 'greedy', 0.1],
];
interface Job { i: number; seed: number; decks: [number, number]; bots: [string, string] }
export function schedule(n: number, nDecks: number, baseSeed: number, mix = DEFAULT_MIX): Job[] {
const rng = mulberry32(baseSeed);
const total = mix.reduce((t, m) => t + m[2], 0);
const jobs: Job[] = [];
for (let i = 0; i < n; i++) {
let r = rng() * total, k = 0;
while (r > mix[k][2] && k < mix.length - 1) { r -= mix[k][2]; k++; }
const flip = rng() < 0.5; // randomise seats so asymmetric pairs measure skill, not seat
const bots: [string, string] = flip ? [mix[k][1], mix[k][0]] : [mix[k][0], mix[k][1]];
jobs.push({ i, seed: (baseSeed * 1000003 + i * 7919) >>> 0, decks: [Math.floor(rng() * nDecks), Math.floor(rng() * nDecks)], bots });
}
return jobs;
}
function runJobs(engine: EngineAdapter<any, any>, ruleset: string, decks: DeckSpec[], jobs: Job[], onRecord: (r: MatchRecord | { error: string; job: Job }) => void) {
for (const j of jobs) {
try { onRecord(playMatch(engine, ruleset, [decks[j.decks[0]], decks[j.decks[1]]], j.bots, j.seed)); }
catch (e) { onRecord({ error: String((e as Error)?.stack ?? e).slice(0, 600), job: j }); }
}
}
function arg(name: string, def?: string): string | undefined {
const i = process.argv.indexOf(`--${name}`);
return i >= 0 ? process.argv[i + 1] : def;
}
async function main() {
const engineName = arg('engine', 'toy')!;
const engine = await loadEngine(engineName);
const rulesets = (arg('ruleset') ?? engine.rulesets().join(',')).split(',');
const n = Number(arg('matches', '1000'));
const workers = Number(arg('workers', '6'));
const seed = Number(arg('seed', '1'));
const out = arg('out', 'sim-out')!;
mkdirSync(out, { recursive: true });
const sections: string[] = [];
for (const ruleset of rulesets) {
const decks = engine.decks(ruleset);
const jobs = schedule(n, decks.length, seed);
const records: MatchRecord[] = [];
const errors: string[] = [];
const file = createWriteStream(join(out, `${ruleset}.jsonl`));
const t0 = Date.now();
const handle = (r: any) => {
if (r.error) { errors.push(r.error); return; }
records.push(r);
file.write(JSON.stringify({ ...r, evalTrace: undefined, cardsPlayed: undefined, cards: r.cardsPlayed.map((x: string[]) => x.length) }) + '\n');
if ((records.length + errors.length) % 500 === 0) process.stderr.write(`[${ruleset}] ${records.length + errors.length}/${n} ${((Date.now() - t0) / 1000).toFixed(0)}s\n`);
};
if (workers <= 1) runJobs(engine, ruleset, decks, jobs, handle);
else {
const chunks: Job[][] = Array.from({ length: workers }, () => []);
jobs.forEach((j, i) => chunks[i % workers].push(j));
await Promise.all(chunks.map(chunk => new Promise<void>((resolve, reject) => {
const w = fork(fileURLToPath(import.meta.url), ['--child'], { execArgv: ['--import', 'tsx'], serialization: 'advanced' });
w.on('message', (m: any) => (m === 'done' ? w.kill() : handle(m)));
w.on('error', reject);
w.on('exit', () => resolve());
w.send({ engineName, ruleset, jobs: chunk });
})));
}
file.end();
const stats = aggregate(records, errors.length, engine);
writeFileSync(join(out, `${ruleset}.stats.json`), JSON.stringify(stats, null, 1));
if (errors.length) writeFileSync(join(out, `${ruleset}.errors.txt`), errors.slice(0, 50).join('\n----\n'));
const md = toMarkdown(stats);
writeFileSync(join(out, `${ruleset}.md`), md);
sections.push(md);
process.stderr.write(`[${ruleset}] done: ${records.length} matches, ${errors.length} errors, ${((Date.now() - t0) / 1000).toFixed(1)}s\n`);
}
process.stdout.write(sections.join('\n'));
}
const isEntry = !!process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
if (isEntry && process.argv.includes('--child')) {
process.once('message', async (msg: any) => {
const { engineName, ruleset, jobs } = msg as { engineName: string; ruleset: string; jobs: Job[] };
const engine = await loadEngine(engineName);
runJobs(engine, ruleset, engine.decks(ruleset), jobs, r => process.send!(r));
process.send!('done');
});
} else if (isEntry) main().catch(e => { console.error(e); process.exit(1); });
+197
View File
@@ -0,0 +1,197 @@
// Aggregate MatchRecords into balance statistics and a markdown section.
import type { EngineAdapter, MatchRecord, Seat } from '../../shared/bots/types.ts';
export interface Rate { n: number; wins: number; rate: number; lo: number; hi: number }
/** Wilson 95% interval. */
export function rate(wins: number, n: number): Rate {
if (!n) return { n, wins, rate: NaN, lo: NaN, hi: NaN };
const z = 1.96, p = wins / n, d = 1 + z * z / n;
const c = (p + z * z / (2 * n)) / d, h = (z * Math.sqrt(p * (1 - p) / n + z * z / (4 * n * n))) / d;
return { n, wins, rate: p, lo: c - h, hi: c + h };
}
const quant = (xs: number[], q: number) => {
if (!xs.length) return NaN;
const s = [...xs].sort((a, b) => a - b);
return s[Math.min(s.length - 1, Math.floor(q * s.length))];
};
const mean = (xs: number[]) => xs.reduce((a, b) => a + b, 0) / (xs.length || 1);
function pearson(xs: number[], ys: number[]): number {
const mx = mean(xs), my = mean(ys);
let sxy = 0, sxx = 0, syy = 0;
for (let i = 0; i < xs.length; i++) { const dx = xs[i] - mx, dy = ys[i] - my; sxy += dx * dy; sxx += dx * dx; syy += dy * dy; }
return sxx && syy ? sxy / Math.sqrt(sxx * syy) : NaN;
}
export interface CardStat { id: string; label?: string; games: number; plays: number; wins: number; wr: Rate; delta: number }
export interface RulesetStats {
ruleset: string;
matches: number;
draws: number;
truncated: number;
errors: number;
turns: { mean: number; p10: number; p50: number; p90: number };
firstPlayer: Rate;
early: { decidedMedianFrac: number; decidedByHalf: number; decidedByThird: number };
byBotPair: Record<string, { n: number; seat0: Rate; firstPlayer: Rate; turns: number }>;
skill: Record<string, Rate>; // "lookahead>greedy": win rate of the stronger bot
byDeck: Record<string, Rate>; // excluding mirrors
byTag: Record<string, Rate>; // excluding games where both sides share the tag
matchups: Record<string, Record<string, Rate>>;
cards: CardStat[];
statCorrelation: Record<string, { r: number; n: number }>;
reasons: Record<string, number>;
}
/** Only bot-symmetric games are used for deck/tag/card/first-player balance. */
const symmetric = (m: MatchRecord) => m.bots[0] === m.bots[1];
export function aggregate(records: MatchRecord[], errors = 0, engine?: EngineAdapter<any, any>): RulesetStats {
const ruleset = records[0]?.ruleset ?? '?';
const decisive = records.filter(m => m.winner !== null);
const sym = decisive.filter(symmetric);
const reasons: Record<string, number> = {};
for (const m of records) reasons[m.reason ?? 'none'] = (reasons[m.reason ?? 'none'] ?? 0) + 1;
const turns = records.map(m => m.turns);
const fracs = decisive.filter(m => m.decidedTurn !== null && m.turns > 1).map(m => (m.decidedTurn! - 1) / Math.max(1, m.turns - 1));
const byBotPair: RulesetStats['byBotPair'] = {};
const pairs = new Map<string, MatchRecord[]>();
for (const m of records) { const k = `${m.bots[0]} vs ${m.bots[1]}`; pairs.set(k, [...(pairs.get(k) ?? []), m]); }
for (const [k, ms] of pairs) {
const d = ms.filter(m => m.winner !== null);
byBotPair[k] = {
n: ms.length,
seat0: rate(d.filter(m => m.winner === 0).length, d.length),
firstPlayer: rate(d.filter(m => m.winner === m.firstSeat).length, d.length),
turns: mean(ms.map(m => m.turns)),
};
}
const skill: Record<string, Rate> = {};
const order = ['random', 'greedy', 'lookahead-lite', 'lookahead'];
for (const m of decisive) {
if (symmetric(m)) continue;
const [a, b] = m.bots;
const strong: Seat = order.indexOf(a) >= order.indexOf(b) ? 0 : 1;
const k = `${m.bots[strong]}>${m.bots[1 - strong]}`;
const r = skill[k] ?? (skill[k] = rate(0, 0));
r.n++; if (m.winner === strong) r.wins++;
}
for (const k of Object.keys(skill)) skill[k] = rate(skill[k].wins, skill[k].n);
const tally = (map: Record<string, { w: number; n: number }>, key: string, won: boolean) => {
const t = map[key] ?? (map[key] = { w: 0, n: 0 }); t.n++; if (won) t.w++;
};
const deckT: Record<string, { w: number; n: number }> = {}, tagT: Record<string, { w: number; n: number }> = {};
const mu: Record<string, Record<string, { w: number; n: number }>> = {};
const cardT = new Map<string, { games: number; plays: number; wins: number }>();
for (const m of sym) {
for (const seat of [0, 1] as Seat[]) {
const won = m.winner === seat, o = (1 - seat) as Seat;
if (m.decks[0] !== m.decks[1]) tally(deckT, m.decks[seat], won);
for (const t of m.deckTags[seat]) if (!m.deckTags[o].includes(t)) tally(tagT, t, won);
tally(mu[m.decks[seat]] ?? (mu[m.decks[seat]] = {}), m.decks[o], won);
const seen = new Set<string>();
for (const c of m.cardsPlayed[seat]) {
const cs = cardT.get(c) ?? { games: 0, plays: 0, wins: 0 };
cs.plays++;
if (!seen.has(c)) { seen.add(c); cs.games++; if (won) cs.wins++; }
cardT.set(c, cs);
}
}
}
const toRates = (t: Record<string, { w: number; n: number }>) => Object.fromEntries(Object.entries(t).map(([k, v]) => [k, rate(v.w, v.n)]));
const cards: CardStat[] = [...cardT].map(([id, c]) => {
const wr = rate(c.wins, c.games);
const label = engine?.cardMeta?.(id)?.label;
return { id, label: typeof label === 'string' ? label : undefined, ...c, wr, delta: wr.rate - 0.5 };
}).sort((a, b) => b.delta - a.delta);
const statCorrelation: RulesetStats['statCorrelation'] = {};
if (engine?.cardMeta) {
const eligible = cards.filter(c => c.games >= 30);
const keys = new Set<string>();
const metas = eligible.map(c => engine.cardMeta!(c.id) ?? {});
for (const m of metas) for (const [k, v] of Object.entries(m)) if (typeof v === 'number') keys.add(k);
for (const k of keys) {
const xs: number[] = [], ys: number[] = [];
eligible.forEach((c, i) => { const v = metas[i][k]; if (typeof v === 'number') { xs.push(v); ys.push(c.wr.rate); } });
statCorrelation[k] = { r: pearson(xs, ys), n: xs.length };
}
// keyword / faction tags on cards
const tagW: Record<string, { w: number; n: number }> = {};
eligible.forEach((c, i) => {
for (const [k, v] of Object.entries(metas[i])) {
const vals = Array.isArray(v) ? v : typeof v === 'string' ? [v] : [];
if (k === 'label') continue;
for (const x of vals) { const t = tagW[`${k}:${x}`] ?? (tagW[`${k}:${x}`] = { w: 0, n: 0 }); t.w += c.wins; t.n += c.games; }
}
});
for (const [k, v] of Object.entries(tagW)) statCorrelation[`card ${k}`] = { r: v.w / v.n - 0.5, n: v.n };
}
return {
ruleset, matches: records.length, errors,
draws: records.filter(m => m.winner === null).length,
truncated: records.filter(m => m.truncated).length,
turns: { mean: mean(turns), p10: quant(turns, 0.1), p50: quant(turns, 0.5), p90: quant(turns, 0.9) },
firstPlayer: rate(sym.filter(m => m.winner === m.firstSeat).length, sym.length),
early: {
decidedMedianFrac: quant(fracs, 0.5),
decidedByHalf: fracs.filter(f => f <= 0.5).length / (fracs.length || 1),
decidedByThird: fracs.filter(f => f <= 1 / 3).length / (fracs.length || 1),
},
byBotPair, skill, byDeck: toRates(deckT), byTag: toRates(tagT),
matchups: Object.fromEntries(Object.entries(mu).map(([k, v]) => [k, toRates(v)])),
cards, statCorrelation, reasons,
};
}
const pct = (x: number) => (Number.isFinite(x) ? `${(x * 100).toFixed(1)}%` : 'n/a');
const fmtRate = (r: Rate) => `${pct(r.rate)} [${pct(r.lo)}–${pct(r.hi)}] (n=${r.n})`;
const sig = (r: Rate) => (r.lo > 0.5 ? ' **↑**' : r.hi < 0.5 ? ' **↓**' : '');
export function toMarkdown(s: RulesetStats): string {
const L: string[] = [];
L.push(`### Ruleset \`${s.ruleset}\``, '');
L.push(`- Matches: **${s.matches}** (draws ${s.draws}, hit action cap ${s.truncated}, engine errors ${s.errors})`);
L.push(`- First-player win rate (bot-symmetric games): **${fmtRate(s.firstPlayer)}**${sig(s.firstPlayer)}`);
L.push(`- Match length (turns, both players): mean ${s.turns.mean.toFixed(1)}, p10 ${s.turns.p10}, median ${s.turns.p50}, p90 ${s.turns.p90}`);
L.push(`- Decided early: median game is locked in at ${pct(s.early.decidedMedianFrac)} of its length; ${pct(s.early.decidedByThird)} decided in the first third, ${pct(s.early.decidedByHalf)} by half-time`);
L.push(`- End reasons: ${Object.entries(s.reasons).map(([k, v]) => `${k} ${v}`).join(', ')}`, '');
L.push('| Bot pairing | n | seat-0 WR | first-player WR | mean turns |', '|---|---|---|---|---|');
for (const [k, v] of Object.entries(s.byBotPair)) L.push(`| ${k} | ${v.n} | ${fmtRate(v.seat0)} | ${fmtRate(v.firstPlayer)} | ${v.turns.toFixed(1)} |`);
if (Object.keys(s.skill).length) {
L.push('', '**Skill expression** (stronger bot win rate):', '');
for (const [k, v] of Object.entries(s.skill)) L.push(`- ${k}: ${fmtRate(v)}`);
}
L.push('', '| Deck | WR vs other decks |', '|---|---|');
for (const [k, v] of Object.entries(s.byDeck).sort((a, b) => b[1].rate - a[1].rate)) L.push(`| ${k} | ${fmtRate(v)}${sig(v)} |`);
const tags = Object.entries(s.byTag).filter(([, v]) => v.n >= 30).sort((a, b) => b[1].rate - a[1].rate);
if (tags.length) {
L.push('', '| Tag (archetype/faction/keyword) | WR |', '|---|---|');
for (const [k, v] of tags) L.push(`| ${k} | ${fmtRate(v)}${sig(v)} |`);
}
const decks = Object.keys(s.matchups).sort();
if (decks.length <= 12) {
L.push('', `| row vs col | ${decks.join(' | ')} |`, `|---|${decks.map(() => '---').join('|')}|`);
for (const r of decks) L.push(`| ${r} | ${decks.map(c => (s.matchups[r][c] ? pct(s.matchups[r][c].rate) : '')).join(' | ')} |`);
}
const elig = s.cards.filter(c => c.games >= 50);
L.push('', `**Cards** (${s.cards.length} seen, ${elig.length} with ≥50 games; WR = win rate of the side that played it):`, '');
L.push('| Top cards | games | WR |', '|---|---|---|');
for (const c of elig.slice(0, 10)) L.push(`| ${c.label ?? c.id} | ${c.games} | ${fmtRate(c.wr)}${sig(c.wr)} |`);
L.push('', '| Bottom cards | games | WR |', '|---|---|---|');
for (const c of elig.slice(-10).reverse()) L.push(`| ${c.label ?? c.id} | ${c.games} | ${fmtRate(c.wr)}${sig(c.wr)} |`);
const corr = Object.entries(s.statCorrelation).filter(([, v]) => v.n >= 10);
if (corr.length) {
L.push('', '**Card stats vs win rate** (numeric: Pearson r across cards; `card k:v`: WR − 50%):', '');
for (const [k, v] of corr.sort((a, b) => Math.abs(b[1].r) - Math.abs(a[1].r))) L.push(`- ${k}: ${v.r >= 0 ? '+' : ''}${v.r.toFixed(3)} (n=${v.n})`);
}
L.push('');
return L.join('\n');
}
+116
View File
@@ -0,0 +1,116 @@
// Toy engine: a tiny lane-less creature game used to self-test the simulation harness
// before shared/game exists. Not the WikiDeck design; do not tune it.
import { mulberry32 } from '../../shared/bots/index.ts';
import type { DeckSpec, EngineAdapter, MatchOutcome, Seat } from '../../shared/bots/types.ts';
interface Card { id: string; cost: number; atk: number; hp: number; guard?: boolean; haste?: boolean }
interface Unit { card: Card; hp: number; ready: boolean }
interface Side { hp: number; deck: Card[]; hand: Card[]; board: Unit[]; mana: number; maxMana: number }
export interface ToyState { ruleset: string; turn: number; active: Seat; sides: [Side, Side]; over: boolean; winner: Seat | null; seed: number }
export type ToyAction = { kind: 'end' } | { kind: 'play'; hand: number } | { kind: 'attack'; unit: number; target: number /* -1 = face */ };
const POOL: Card[] = [];
for (let cost = 1; cost <= 6; cost++) {
POOL.push({ id: `c${cost}-beater`, cost, atk: cost + 1, hp: cost });
POOL.push({ id: `c${cost}-wall`, cost, atk: Math.max(1, cost - 1), hp: cost + 2, guard: true });
POOL.push({ id: `c${cost}-rush`, cost, atk: cost, hp: Math.max(1, cost - 1), haste: true });
}
const ARCHETYPES: Record<string, (c: Card) => number> = {
aggro: c => (c.cost <= 3 ? 3 : 0) + (c.haste ? 1 : 0),
control: c => (c.guard ? 2 : 0) + (c.cost >= 4 ? 2 : 0),
midrange: c => (c.cost >= 2 && c.cost <= 5 ? 2 : 0),
};
function buildDeck(arch: string): Card[] {
const w = ARCHETYPES[arch];
return POOL.filter(c => w(c) > 0).flatMap(c => Array(w(c)).fill(c)).slice(0, 20);
}
const clone = (s: ToyState): ToyState => ({
...s, sides: s.sides.map(p => ({ ...p, deck: [...p.deck], hand: [...p.hand], board: p.board.map(u => ({ ...u })) })) as [Side, Side],
});
function startTurn(s: ToyState): void {
const p = s.sides[s.active];
p.maxMana = Math.min(s.ruleset === 'toy-fast' ? 10 : 8, p.maxMana + 1);
p.mana = p.maxMana;
for (const u of p.board) u.ready = true;
const c = p.deck.shift();
if (c) p.hand.push(c); else p.hp -= 2; // fatigue
check(s);
}
function check(s: ToyState): void {
const [a, b] = s.sides;
if (a.hp <= 0 || b.hp <= 0) { s.over = true; s.winner = a.hp <= 0 && b.hp <= 0 ? null : a.hp <= 0 ? 1 : 0; }
}
export const toyEngine: EngineAdapter<ToyState, ToyAction> = {
name: 'toy',
rulesets: () => ['toy', 'toy-fast'],
decks: () => Object.keys(ARCHETYPES).map(a => ({ id: a, tags: [`arch:${a}`], payload: a })),
createMatch(ruleset, decks, seed) {
const rng = mulberry32(seed);
const side = (d: DeckSpec): Side => {
const deck = buildDeck(d.payload as string);
for (let i = deck.length - 1; i > 0; i--) { const j = Math.floor(rng() * (i + 1)); [deck[i], deck[j]] = [deck[j], deck[i]]; }
return { hp: 20, deck, hand: deck.splice(0, 3), board: [], mana: 0, maxMana: 0 };
};
const s: ToyState = { ruleset, turn: 1, active: (seed & 1) as Seat, sides: [side(decks[0]), side(decks[1])], over: false, winner: null, seed };
s.sides[1 - s.active].hand.push(s.sides[1 - s.active].deck.shift()!); // second player gets an extra card
startTurn(s);
return s;
},
toAct: s => s.active,
legalActions(s, seat) {
if (s.over || seat !== s.active) return [];
const me = s.sides[seat], them = s.sides[1 - seat];
const out: ToyAction[] = [{ kind: 'end' }];
me.hand.forEach((c, i) => { if (c.cost <= me.mana && me.board.length < 6) out.push({ kind: 'play', hand: i }); });
const guards = them.board.map((u, i) => (u.card.guard ? i : -2)).filter(i => i >= 0);
me.board.forEach((u, i) => {
if (!u.ready) return;
const targets = guards.length ? guards : [-1, ...them.board.map((_, j) => j)];
for (const t of targets) out.push({ kind: 'attack', unit: i, target: t });
});
return out;
},
applyAction(s0, a) {
const s = clone(s0);
const me = s.sides[s.active], them = s.sides[1 - s.active];
if (a.kind === 'end') {
s.active = (1 - s.active) as Seat;
s.turn++;
startTurn(s);
if (s.turn > 60) { s.over = true; s.winner = null; }
} else if (a.kind === 'play') {
const [c] = me.hand.splice(a.hand, 1);
me.mana -= c.cost;
me.board.push({ card: c, hp: c.hp, ready: !!c.haste });
} else {
const u = me.board[a.unit];
u.ready = false;
if (a.target < 0) them.hp -= u.card.atk;
else {
const v = them.board[a.target];
v.hp -= u.card.atk; u.hp -= v.card.atk;
them.board = them.board.filter(x => x.hp > 0);
me.board = me.board.filter(x => x.hp > 0);
}
check(s);
}
return s;
},
isOver: s => s.over,
result: (s): MatchOutcome => ({ winner: s.winner, reason: s.over ? (s.winner === null ? 'draw' : 'hp') : undefined }),
turn: s => s.turn,
evaluate(s, seat) {
const me = s.sides[seat], them = s.sides[1 - seat];
const board = (p: Side) => p.board.reduce((t, u) => t + u.card.atk + u.hp, 0);
const v = (me.hp - them.hp) / 20 + (board(me) - board(them)) / 20 + (me.hand.length - them.hand.length) / 20;
return Math.max(-1, Math.min(1, v));
},
cardsOf: (s, a) => (a.kind === 'play' ? [s.sides[s.active].hand[a.hand].id] : []),
actionKind: a => a.kind,
};
+167
View File
@@ -0,0 +1,167 @@
// EngineAdapter over the public shared/game API, plus the starter/archetype decks used
// by the balance simulation. Pure: rulesets and extra decks are passed in, no I/O.
import {
DEFAULT_RULESET, STARTER_POOL, applyAction, createMatch, isOver, lanePower,
legalActions, result, starterCard, starterDeck, validateDeck,
type Action, type CardInPlay, type GameCard, type MatchState, type PlayerId, type Ruleset,
} from '../game/index.ts';
import type { DeckSpec, EngineAdapter, Rng, Seat } from './types.ts';
const other = (p: PlayerId): PlayerId => (p === 0 ? 1 : 0);
/**
* Lane outcome as `seat` sees it: its own revealed and staged cards against the opponent's
* revealed cards only (staged opponent plays are hidden). Ongoing effects included, onReveal not.
*/
export function projectedLanes(state: MatchState, seat: Seat): [number, number][] {
const me = state.players[seat];
if (!me.staged.length) return state.lanes.map((_, i) => orient(lanePower(state, i), seat));
const lanes = state.lanes.map(l => ({ ...l, cards: [[...l.cards[0]], [...l.cards[1]]] as [CardInPlay[], CardInPlay[]] }));
for (const play of me.staged) {
const card = me.hand.find(c => c.id === play.cardId);
if (card) lanes[play.lane].cards[seat].push({ card, owner: seat, lane: play.lane, turn: state.turn, bonus: 0 });
}
const view = { ...state, lanes } as MatchState;
return lanes.map((_, i) => orient(lanePower(view, i), seat));
}
const orient = (p: [number, number], seat: Seat): [number, number] => (seat === 0 ? p : [p[1], p[0]]);
/** Heuristic for `seat` in [-1, 1]: soft lane wins, weighted up as the match nears its end. */
export function evaluateFor(state: MatchState, seat: Seat): number {
if (state.result) return state.result.winner === null ? 0 : state.result.winner === seat ? 1 : -1;
const lanes = projectedLanes(state, seat);
const scale = 4;
let lane = 0, total = 0;
for (const [a, b] of lanes) { lane += Math.tanh((a - b) / scale); total += a - b; }
const me = state.players[seat], them = state.players[other(seat)];
const handEdge = (me.hand.length - me.staged.length - (them.hand.length - them.staged.length)) * 0.02;
const unspent = me.energy * -0.01; // nudge greedy to use its energy
const v = (lane + Math.tanh(total / 20) * 0.3) / (state.lanes.length + 0.3) + handEdge + unspent;
return Math.max(-1, Math.min(1, v));
}
/**
* Determinize hidden information before a lookahead for `seat`: the opponent's staged plays
* are taken back (it re-decides in the rollouts) and its hand and deck are reshuffled together.
*/
export function determinize(state: MatchState, seat: Seat, rng: Rng): MatchState {
const s = structuredClone(state);
const o = other(seat), opp = s.players[o];
if (opp.staged.length || opp.ended) {
const refund = opp.staged.reduce((t, p) => t + (opp.hand.find(c => c.id === p.cardId)?.cost ?? 0), 0);
opp.energy += refund;
opp.staged = [];
opp.ended = false;
}
const pool = [...opp.hand, ...opp.deck];
for (let i = pool.length - 1; i > 0; i--) { const j = Math.floor(rng() * (i + 1)); [pool[i], pool[j]] = [pool[j], pool[i]]; }
opp.hand = pool.slice(0, opp.hand.length);
opp.deck = pool.slice(opp.hand.length);
const mine = s.players[seat].deck;
for (let i = mine.length - 1; i > 0; i--) { const j = Math.floor(rng() * (i + 1)); [mine[i], mine[j]] = [mine[j], mine[i]]; }
return s;
}
// ---------- decks ----------
type Spec = (typeof STARTER_POOL)[number];
function tagDeck(cards: GameCard[], base: string[]): string[] {
const tags = new Set(base);
const cats = new Map<string, number>();
const kws = new Map<string, number>();
for (const c of cards) {
cats.set(c.category, (cats.get(c.category) ?? 0) + 1);
kws.set(c.keyword ?? 'vanilla', (kws.get(c.keyword ?? 'vanilla') ?? 0) + 1);
}
const [topCat, nCat] = [...cats].sort((a, b) => b[1] - a[1])[0];
if (nCat >= cards.length / 3) tags.add(`cat:${topCat}`);
for (const [k, n] of kws) if (n >= cards.length / 2) tags.add(`kw:${k}-heavy`);
const avg = cards.reduce((t, c) => t + c.cost, 0) / cards.length;
tags.add(avg <= 2.75 ? 'curve:low' : avg >= 4 ? 'curve:high' : 'curve:mid');
return [...tags];
}
/** Build a deck of `size` from specs ranked by `score`, up to `copies` per page. */
function themed(score: (s: Spec) => number, size: number, copies: number): GameCard[] {
const ranked = [...STARTER_POOL].map(s => ({ s, v: score(s) })).filter(x => x.v > 0).sort((a, b) => b.v - a.v || a.s[3] - b.s[3]);
const out: GameCard[] = [];
for (let copy = 0; copy < copies && out.length < size; copy++)
for (const { s } of ranked) { if (out.length >= size) break; out.push(starterCard(s, copy)); }
return out;
}
export function defaultDecks(rules: Ruleset, extra: DeckSpec[] = []): DeckSpec[] {
const size = rules.deck.min, copies = rules.deck.maxCopiesPerPage;
const decks: DeckSpec[] = [];
for (let i = 0; i < 8; i++) {
const cards = starterDeck(`sim-${i}`, rules);
decks.push({ id: `starter-${i}`, tags: tagDeck(cards, ['arch:starter']), payload: cards });
}
const arche: [string, (s: Spec) => number][] = [
['rally', s => (s[5] === 'rally' ? 10 - s[3] : s[3] <= 2 ? 1 : 0)],
['anchor', s => (s[5] === 'anchor' ? 10 - s[3] : s[3] <= 2 ? 1 : 0)],
['vanilla', s => (s[5] === null ? 10 - Math.abs(3.5 - s[3]) : 0)],
['low-curve', s => (s[3] <= 3 ? 10 + s[4] - s[3] : 0)],
['high-curve', s => (s[3] >= 3 ? s[3] : 0)],
];
for (const [name, score] of arche) {
const cards = themed(score, size, copies);
if (!validateDeck(rules, cards).length) decks.push({ id: name, tags: tagDeck(cards, [`arch:${name}`]), payload: cards });
}
for (const d of extra) if (!validateDeck(rules, d.payload as GameCard[]).length)
decks.push({ ...d, tags: tagDeck(d.payload as GameCard[], d.tags) });
return decks;
}
// ---------- adapter ----------
export interface GameEngineOptions {
rulesets?: Record<string, Ruleset>;
extraDecks?: DeckSpec[];
}
export function makeGameEngine(opts: GameEngineOptions = {}): EngineAdapter<MatchState, Action> {
const rulesets = opts.rulesets ?? { base: DEFAULT_RULESET };
const deckCache = new Map<string, DeckSpec[]>();
const meta = new Map<string, GameCard>();
const rules = (id: string) => {
const r = rulesets[id];
if (!r) throw new Error(`unknown ruleset ${id}`);
return r;
};
return {
name: 'shared/game',
rulesets: () => Object.keys(rulesets),
decks(id) {
if (!deckCache.has(id)) {
const d = defaultDecks(rules(id), opts.extraDecks);
for (const deck of d) for (const c of deck.payload as GameCard[]) meta.set(c.id, c);
deckCache.set(id, d);
}
return deckCache.get(id)!;
},
createMatch: (id, decks, seed) => createMatch(rules(id), [decks[0].payload as GameCard[], decks[1].payload as GameCard[]], `sim-${seed}`),
// Simultaneous turns: seat 0 stages first, then seat 1. Bots never read the other side's staged plays
// (evaluateFor hides them; lookahead determinizes), so the order leaks nothing.
toAct: s => (s.players[0].ended ? 1 : 0),
// Unstage is excluded: it never helps a bot and lets random bots loop.
legalActions: (s, seat) => legalActions(s, seat).filter(a => a.type !== 'unstage'),
applyAction,
isOver,
result: s => { const r = result(s); return { winner: r?.winner ?? null, reason: r?.reason }; },
turn: s => s.turn,
evaluate: evaluateFor,
cardsOf: (_s, a) => (a.type === 'play' ? [a.cardId.replace(/:\d+$/, '')] : []),
actionKind: a => a.type,
cardMeta(id) {
const c = meta.get(id) ?? meta.get(`${id}:0`);
if (!c) return undefined;
return { label: c.name, cost: c.cost, power: c.power, powerPerCost: c.power / Math.max(1, c.cost), keyword: c.keyword ?? 'vanilla', category: c.category };
},
firstSeat: s => s.firstToReveal,
determinize,
};
}
export const gameEngine = makeGameEngine();
+102
View File
@@ -0,0 +1,102 @@
// Reference bots: random, greedy (one-ply) and flat Monte Carlo lookahead.
// Each factory takes an EngineAdapter and returns a pure BotFn (state, player, rng) => action.
import type { BotFn, EngineAdapter, Rng, Seat } from './types.ts';
export type * from './types.ts';
export function mulberry32(seed: number): Rng {
let a = seed >>> 0;
return () => {
a = (a + 0x6d2b79f5) >>> 0;
let t = a;
t = Math.imul(t ^ (t >>> 15), t | 1);
t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
};
}
const pick = <T>(xs: T[], rng: Rng): T => xs[Math.floor(rng() * xs.length)];
function terminalValue<S, A>(engine: EngineAdapter<S, A>, s: S, seat: Seat): number {
const { winner } = engine.result(s);
return winner === null ? 0 : winner === seat ? 1 : -1;
}
function value<S, A>(engine: EngineAdapter<S, A>, s: S, seat: Seat): number {
return engine.isOver(s) ? terminalValue(engine, s, seat) * 10 : engine.evaluate(s, seat);
}
/** Uniformly random legal action. */
export function randomBot<S, A>(engine: EngineAdapter<S, A>): BotFn<S, A> {
return (state, player, rng) => pick(engine.legalActions(state, player), rng);
}
function greedyChoice<S, A>(engine: EngineAdapter<S, A>, state: S, seat: Seat, actions: A[], rng: Rng): A {
if (actions.length === 1) return actions[0];
let best: A[] = [];
let bestV = -Infinity;
for (const a of actions) {
const v = value(engine, engine.applyAction(state, a), seat);
if (v > bestV + 1e-9) { bestV = v; best = [a]; }
else if (Math.abs(v - bestV) <= 1e-9) best.push(a);
}
return pick(best, rng);
}
/** One-ply: take the action whose resulting state evaluates best for us. Ties broken randomly. */
export function greedyBot<S, A>(engine: EngineAdapter<S, A>): BotFn<S, A> {
return (state, player, rng) => greedyChoice(engine, state, player, engine.legalActions(state, player), rng);
}
export interface LookaheadOptions { k?: number; rollouts?: number; horizon?: number; epsilon?: number }
/**
* Flat Monte Carlo lookahead: shortlist the top-k greedy candidates, then for each run
* `rollouts` epsilon-greedy playouts for both seats, up to `horizon` actions, scoring
* terminal results (or the clamped heuristic at the horizon).
* Rollouts run on the true state, so the bot is clairvoyant about hidden info and seeded
* draws: an upper bound on skill, not a fair human-like player.
*/
export function lookaheadBot<S, A>(engine: EngineAdapter<S, A>, opts: LookaheadOptions = {}): BotFn<S, A> {
const k = opts.k ?? 4, rollouts = opts.rollouts ?? 8, horizon = opts.horizon ?? 40, eps = opts.epsilon ?? 0.25;
return (state, seat, rng) => {
const actions = engine.legalActions(state, seat);
if (actions.length === 1) return actions[0];
const shortlist = actions.map(a => {
const next = engine.applyAction(state, a);
return { a, next, v: value(engine, next, seat) };
}).sort((x, y) => y.v - x.v).slice(0, k);
let best = shortlist[0], bestScore = -Infinity;
for (const c of shortlist) {
let total = 0;
for (let r = 0; r < rollouts; r++) {
let s = engine.determinize ? engine.applyAction(engine.determinize(state, seat, rng), c.a) : c.next, steps = 0;
while (!engine.isOver(s) && steps < horizon) {
const who = engine.toAct(s);
const legal = engine.legalActions(s, who);
if (!legal.length) break;
const a = rng() < eps ? pick(legal, rng) : greedyChoice(engine, s, who, legal, rng);
s = engine.applyAction(s, a);
steps++;
}
total += engine.isOver(s) ? terminalValue(engine, s, seat) : Math.max(-1, Math.min(1, engine.evaluate(s, seat)));
}
const score = total / rollouts + c.v * 1e-3; // tiny greedy tiebreak
if (score > bestScore) { bestScore = score; best = c; }
}
return best.a;
};
}
export const BOT_NAMES = ['random', 'greedy', 'lookahead', 'lookahead-lite'] as const;
export type BotName = typeof BOT_NAMES[number];
export function makeBot<S, A>(name: string, engine: EngineAdapter<S, A>): BotFn<S, A> {
switch (name) {
case 'random': return randomBot(engine);
case 'greedy': return greedyBot(engine);
case 'lookahead': return lookaheadBot(engine);
case 'lookahead-lite': return lookaheadBot(engine, { k: 3, rollouts: 4, horizon: 24 });
default: throw new Error(`unknown bot ${name}`);
}
}
+73
View File
@@ -0,0 +1,73 @@
// 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;
}
+50
View File
@@ -0,0 +1,50 @@
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { existsSync } from 'node:fs';
import { makeBot, mulberry32 } from '../shared/bots/index.ts';
import type { EngineAdapter } from '../shared/bots/types.ts';
import { playMatch, decidedTurn } from '../scripts/sim/match.ts';
import { aggregate, rate, toMarkdown } from '../scripts/sim/stats.ts';
import { toyEngine } from '../scripts/sim/toy-engine.ts';
test('toy matches are deterministic and terminate', () => {
const decks = toyEngine.decks('toy');
const a = playMatch(toyEngine, 'toy', [decks[0], decks[1]], ['greedy', 'random'], 42);
const b = playMatch(toyEngine, 'toy', [decks[0], decks[1]], ['greedy', 'random'], 42);
assert.equal(a.truncated, false);
assert.deepEqual({ ...a, ms: 0 }, { ...b, ms: 0 });
});
test('greedy beats random on the toy engine', () => {
const decks = toyEngine.decks('toy');
const recs = Array.from({ length: 60 }, (_, i) => playMatch(toyEngine, 'toy', [decks[i % 3], decks[(i + 1) % 3]], i % 2 ? ['greedy', 'random'] : ['random', 'greedy'], i));
const stats = aggregate(recs);
assert.ok(stats.skill['greedy>random'].rate > 0.7, JSON.stringify(stats.skill));
assert.match(toMarkdown(stats), /First-player win rate/);
});
test('stats helpers', () => {
const r = rate(50, 100);
assert.ok(r.lo < 0.5 && r.hi > 0.5);
assert.equal(decidedTurn([0.2, -0.3, 0.4, 0.6], 0), 3);
assert.equal(decidedTurn([0.2, 0.3], null), null);
});
test('bots only return legal actions on shared/game', { skip: !existsSync(new URL('../shared/game/index.ts', import.meta.url)) }, async () => {
const { gameEngine } = await import('../shared/bots/game-adapter.ts');
const engine = gameEngine as EngineAdapter<any, any>;
const decks = engine.decks('base');
for (const name of ['random', 'greedy', 'lookahead-lite']) {
const bot = makeBot(name, engine);
let s = engine.createMatch('base', [decks[0], decks[decks.length - 1]], 7);
const rng = mulberry32(1);
let steps = 0;
while (!engine.isOver(s) && steps++ < 500) {
const seat = engine.toAct(s);
const a = bot(s, seat, rng);
assert.ok(engine.legalActions(s, seat).some(x => JSON.stringify(x) === JSON.stringify(a)), `${name} chose illegal ${JSON.stringify(a)}`);
s = engine.applyAction(s, a);
}
assert.ok(engine.isOver(s), `${name} match did not finish`);
}
});