Merge remote-tracking branch 'origin/night/sim/balance-harness' into night/ui-b/bots-engine

This commit is contained in:
2026-11-17 00:01:30 -05:00
18 changed files with 1317 additions and 0 deletions
+76
View File
@@ -0,0 +1,76 @@
# WikiDeck: Edit War — balance report
Owner: sim-balance (claude/wikideck#4). Harness: `shared/bots/`, `scripts/sim/` (PR #14).
<!-- RESULTS -->
## Method
**Engine.** Every match runs on the real rules engine (`shared/game`, public `index.ts` API only), through
`shared/bots/game-adapter.ts`. Nothing in the sim re-implements rules. The engine commit is named in each
results section.
**Bots** (`shared/bots/index.ts`, each a pure `(state, player, rng) => action`):
- `random`: a uniformly random legal play or commit.
- `maxpower`: always queues the highest printed-power card it can afford, in a random legal lane. This is the
DESIGN §8 "always play the highest-power card" line.
- `greedy`: one-ply. It takes the action whose result scores best on a lane heuristic: a soft lead per Topic
plus total power. The heuristic sees the bot's own queued plays and the opponent's *revealed* cards only.
- `lookahead-lite` / `lookahead`: flat Monte Carlo over the top 3–4 greedy candidates, with 4–8 rollouts
each. Before each rollout, the opponent's queued plays are taken back and its hand and deck reshuffled
(determinization), so the bot never reads hidden information.
**Seats.** Plans are simultaneous: seat 0 queues and commits, then seat 1. Neither bot can see the other's
queue, so the order leaks nothing. "First player" means the seat with **initiative on turn 1**.
**Schedule.** Per ruleset, matches are drawn from a fixed mix of bot pairings with random seats:
| pairing | share | used for |
|---|---|---|
| greedy vs greedy | 55% | balance (decks, cards, keywords, first player) |
| lookahead-lite vs lookahead-lite | 12% | balance with a stronger player |
| random vs random | 5% | baseline |
| greedy vs lookahead-lite, maxpower vs lookahead-lite, maxpower vs greedy, random vs greedy | 28% | skill expression |
Deck, card and keyword statistics use only **bot-symmetric** games (the same bot on both seats). Deck pairs are
drawn uniformly, mirrors included; the per-deck win rate excludes mirrors. `--mix fast` (greedy only) is used for
quick lever sweeps.
**Decks.** These are built from a card pool by `defaultDecks()`:
- 6 seeded starter decks (`starterDeck`)
- `curve` (cost counts 2/3/3/2/1/1)
- `top-heavy` (1/1/2/2/3/3)
- `heavy` (cost 5–6 first: the §8 "all-famous" line)
- `swarm` (cost ≤ 2 first)
- `mono-<faction>` curve decks for factions with ≥ 6 cards
- `kw-<keyword>` curve decks for keywords on ≥ 3 cards
The pool is the engine's preview pool, or council-data's `card-sample.json` derived per DESIGN §1
(percentile → fame → cost, home stat, faction keyword). Loaner power always follows the ruleset's
`powerByCost`.
**Metrics.**
- Win rates with Wilson 95% intervals. **↑/↓** marks an interval that excludes 50%.
- First-player WR: initiative holder on turn 1, symmetric games.
- Match length in turns.
- "Decided early": the turn from which the eventual winner led on the heuristic until the end, as a fraction of
the match.
- Per-card WR: the win rate of the side that played the card.
- Per-stat correlations.
- **Keyword value:** a counterfactual. Each finished match is replayed with the same actions and the keyword
removed from one side. We report the side's lost total power per keyword card, and how often removing the
keyword made the result worse for that side ("games decided by it"). DESIGN §10.1 asks for
`keywordParams.<id>.powerDelta` when a keyword is worth more than about 1 power.
**Reproduce.**
```
SIM_POOL=docs/game/card-sample.json SIM_RULESETS=scripts/sim/variants/v1.json \
npx tsx scripts/sim/run.ts --engine game --matches 5000 --workers 10 --out sim-out
python3 scripts/sim/summary.py sim-out
```
**Limits.**
- Bots are not humans. Greedy undervalues saving energy and bluffing.
- Lookahead rollouts are short.
- Deck archetypes are built automatically, not tuned by hand.
- The 100-card sample is skewed: Culture 53, People 30, Nature 9, History 5, Science 3, Space 0.
+85
View File
@@ -0,0 +1,85 @@
// Sim card pool from council-data's docs/game/card-sample.json (or starter-cards.json),
// derived per DESIGN §1 (percentile -> fame -> cost, home stat) and §10.1 (faction keyword).
// Percentile cut points come from the file itself. Power is (re)set from the ruleset by the adapter.
import { readFileSync } from 'node:fs';
import { KEYWORD_IDS, type GameCard, type Stat } from '../../shared/game/index.ts';
import { mulberry32 } from '../../shared/bots/index.ts';
import type { DeckSpec } from '../../shared/bots/types.ts';
const STATS: Stat[] = ['attention', 'depth', 'reach'];
const HOME_TIE: Stat[] = ['depth', 'reach', 'attention'];
/** DESIGN v1 §10.2 (PR #17): one keyword per faction. */
export const FACTION_KEYWORD: Record<string, string> = {
Culture: 'viral', Nature: 'rising', People: 'local', Science: 'encyclopedic', History: 'nostalgic', Space: 'translated',
};
interface RawCard { pageId: number; title: string; category?: string; legacyCategory?: string; stats: Record<Stat, number | null>; trendPercent?: number; pageviews?: { trendPercent?: number | null; dailyAverage?: number | null } }
function cuts(values: number[]): number[] {
const s = [...values].sort((a, b) => a - b);
return Array.from({ length: 99 }, (_, i) => s[Math.min(s.length - 1, Math.floor(((i + 1) / 100) * s.length))]);
}
function percentile(score: number, c: number[]): number {
let below = 0, equal = 0;
for (const x of c) { if (x < score) below++; else if (x === score) equal++; }
return Math.floor(below + equal / 2);
}
export interface PoolOptions { costThresholds?: number[]; keywords?: 'faction' | 'none'; table?: string; /** v1.1 proposal: Culture takes its home-stat keyword. */ cultureKeyword?: 'faction' | 'home' }
const CULTURE_HOME: Record<Stat, string> = { attention: 'viral', depth: 'encyclopedic', reach: 'translated' };
export function loadPool(file: string, opts: PoolOptions = {}): GameCard[] {
const raw = JSON.parse(readFileSync(file, 'utf8')).cards as RawCard[];
const tableRaw = opts.table ? (JSON.parse(readFileSync(opts.table, 'utf8')).cards as RawCard[]) : raw;
const table = Object.fromEntries(STATS.map(s => [s, cuts(tableRaw.map(c => c.stats[s]).filter((v): v is number => v !== null))])) as Record<Stat, number[]>;
const thresholds = opts.costThresholds ?? [15, 35, 55, 75, 90];
return raw.map(c => {
const pct = Object.fromEntries(STATS.map(s => [s, c.stats[s] === null ? null : percentile(c.stats[s]!, table[s])])) as Record<Stat, number | null>;
const vals = STATS.map(s => pct[s]).filter((v): v is number => v !== null);
const fame = Math.floor(vals.reduce((a, b) => a + b, 0) / vals.length + 0.5);
const cost = 1 + thresholds.filter(t => t <= fame).length;
let home: Stat = HOME_TIE[0];
for (const s of HOME_TIE) { const v = pct[s], cur = pct[home]; if (v !== null && (cur === null || v > cur)) home = s; }
const faction = (c.category ?? c.legacyCategory ?? 'Culture') as GameCard['faction'];
const kw = faction === 'Culture' && opts.cultureKeyword === 'home' ? CULTURE_HOME[home] : FACTION_KEYWORD[faction];
const keyword = cost === 1 || opts.keywords === 'none' || !kw || !(KEYWORD_IDS as readonly string[]).includes(kw) ? null : kw;
return {
cardId: `loaner:${c.pageId}`, pageId: c.pageId, title: c.title, faction, rarity: 'Common', cost, power: 0,
home, trend: 0, keyword, source: 'loaner',
} satisfies GameCard;
});
}
const kebab = (t: string) => t.toLowerCase().normalize('NFKD').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
/** The DESIGN §2.1 starter decks: "**A. Name: ...**" headings followed by | Cost | Card | Faction | Home | tables. */
export function loadStarterDecks(designMd: string): DeckSpec[] {
const text = readFileSync(designMd, 'utf8');
const sec = text.slice(text.indexOf('### 2.1'), text.indexOf('## 3.'));
const decks: DeckSpec[] = [];
let cur: { id: string; cards: GameCard[] } | null = null;
for (const line of sec.split('\n')) {
const h = line.match(/^\*\*([A-Z])\. ([^:*]+)/);
if (h) { cur = { id: `starter-${h[1]}-${kebab(h[2])}`, cards: [] }; decks.push({ id: cur.id, tags: ['arch:starter-v1'], payload: cur.cards }); continue; }
const r = line.match(/^\| (\d) \| ([^|]+) \| (\w+) \| (\w+) \|$/);
if (r && cur) {
const [, cost, title, faction, home] = r;
const c = Number(cost), kw = FACTION_KEYWORD[faction];
cur.cards.push({
cardId: `loaner:${kebab(title.trim())}`, pageId: null, title: title.trim(), faction: faction as GameCard['faction'], rarity: 'Common',
cost: c, power: 0, home: home as Stat, trend: 0, keyword: c === 1 || !(KEYWORD_IDS as readonly string[]).includes(kw) ? null : kw, source: 'loaner',
});
}
}
return decks.filter(d => (d.payload as GameCard[]).length === 12);
}
/** "Realistic owned" decks (DESIGN §2.1 v1.1 note): `n` seeded draws of 12 distinct cards from the pool, real category mix. */
export function ownedDecks(pool: GameCard[], n: number, size = 12, seed = 7): DeckSpec[] {
const rng = mulberry32(seed);
return Array.from({ length: n }, (_, i) => {
const p = [...pool];
for (let k = p.length - 1; k > 0; k--) { const j = Math.floor(rng() * (k + 1)); [p[k], p[j]] = [p[j], p[k]]; }
return { id: `owned-${i}`, tags: ['arch:owned-random'], payload: p.slice(0, size).map(c => ({ ...c, cardId: `${c.cardId}:0` })) };
});
}
+53
View File
@@ -0,0 +1,53 @@
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<unknown, A>, BotFn<unknown, 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);
// Bots see only their seat's observation (shared/game: viewFor), never the full state.
const a = bots[seat](engine.observe ? engine.observe(s, 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,
keywordValues: !truncated && engine.keywordValues ? engine.keywordValues(s, decks) : undefined,
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);
}
+151
View File
@@ -0,0 +1,151 @@
// 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;
}
}
let pool;
const extraDecks = [];
const cp = await import('./card-pool.ts');
if (process.env.SIM_STARTERS) extraDecks.push(...cp.loadStarterDecks(process.env.SIM_STARTERS));
if (process.env.SIM_POOL) {
const { loadPool } = cp;
pool = loadPool(process.env.SIM_POOL, { keywords: process.env.SIM_KEYWORDS === 'none' ? 'none' : 'faction', costThresholds: process.env.SIM_COST_THRESHOLDS ? JSON.parse(process.env.SIM_COST_THRESHOLDS) : undefined, cultureKeyword: process.env.SIM_CULTURE_KW === 'home' ? 'home' : 'faction' });
}
if (pool && process.env.SIM_OWNED) extraDecks.push(...cp.ownedDecks(pool, Number(process.env.SIM_OWNED)));
return makeGameEngine({ rulesets, pool, extraDecks });
}
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.12],
['random', 'random', 0.05],
['greedy', 'lookahead-lite', 0.1],
['maxpower', 'lookahead-lite', 0.08],
['maxpower', 'greedy', 0.05],
['random', 'greedy', 0.05],
];
export const MIXES: Record<string, [string, string, number][]> = {
default: DEFAULT_MIX,
// Fast sweep: balance from greedy mirrors, plus a little skill signal.
fast: [['greedy', 'greedy', 0.8], ['maxpower', 'greedy', 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;
}
/** Decks for a ruleset, filtered by the SIM_DECKS regex (inherited by child processes). */
export function decksFor(engine: EngineAdapter<any, any>, ruleset: string): DeckSpec[] {
const re = process.env.SIM_DECKS ? new RegExp(process.env.SIM_DECKS) : null;
return engine.decks(ruleset).filter(d => !re || re.test(d.id));
}
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 = decksFor(engine, ruleset);
const jobs = schedule(n, decks.length, seed, MIXES[arg('mix', 'default')!]);
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, decksFor(engine, ruleset), jobs, r => process.send!(r));
process.send!('done');
});
} else if (isEntry) main().catch(e => { console.error(e); process.exit(1); });
+217
View File
@@ -0,0 +1,217 @@
// 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;
}
/** delta = deck-adjusted lift: mean over games of (won − that deck's overall WR in symmetric games). */
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>;
/** Counterfactual keyword value (see EngineAdapter.keywordValues), per keyword. */
keywords: Record<string, { n: number; cards: number; powerPerCard: number; flipRate: number; wr: Rate }>;
}
/** 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', 'maxpower', '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; lift: number }>();
const deckAll: Record<string, { w: number; n: number }> = {};
for (const m of sym) for (const seat of [0, 1] as Seat[]) tally(deckAll, m.decks[seat], m.winner === seat);
const deckRate = (d: string) => deckAll[d].w / deckAll[d].n;
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, lift: 0 };
cs.plays++;
if (!seen.has(c)) { seen.add(c); cs.games++; if (won) cs.wins++; cs.lift += Number(won) - deckRate(m.decks[seat]); }
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, games: c.games, plays: c.plays, wins: c.wins, wr, delta: c.lift / c.games };
}).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.delta); } });
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.delta * c.games; t.n += c.games; }
}
});
for (const [k, v] of Object.entries(tagW)) statCorrelation[`card ${k}`] = { r: v.w / v.n, n: v.n };
}
const kwT: Record<string, { n: number; cards: number; power: number; flip: number; wins: number }> = {};
for (const m of sym) for (const k of m.keywordValues ?? []) {
const t = kwT[k.keyword] ?? (kwT[k.keyword] = { n: 0, cards: 0, power: 0, flip: 0, wins: 0 });
t.n++; t.cards += k.cards; t.power += k.power; t.flip += k.flip; if (m.winner === k.seat) t.wins++;
}
const keywords = Object.fromEntries(Object.entries(kwT).map(([k, t]) => [k, { n: t.n, cards: t.cards, powerPerCard: t.power / t.cards, flipRate: t.flip / t.n, wr: rate(t.wins, t.n) }]));
return {
ruleset, matches: records.length, errors, keywords,
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). Lift = win rate when played minus the win rate of the deck it was in (deck-adjusted); raw WR for reference:`, '');
const meta = (c: CardStat) => c.label ?? c.id;
L.push('| Top cards | games | lift | raw WR |', '|---|---|---|---|');
for (const c of elig.slice(0, 10)) L.push(`| ${meta(c)} | ${c.games} | ${c.delta >= 0 ? '+' : ''}${(c.delta * 100).toFixed(1)} pp | ${pct(c.wr.rate)} |`);
L.push('', '| Bottom cards | games | lift | raw WR |', '|---|---|---|---|');
for (const c of elig.slice(-10).reverse()) L.push(`| ${meta(c)} | ${c.games} | ${c.delta >= 0 ? '+' : ''}${(c.delta * 100).toFixed(1)} pp | ${pct(c.wr.rate)} |`);
if (Object.keys(s.keywords).length) {
L.push('', '**Keyword value** (counterfactual replay with the keyword removed from that side; same actions):', '');
L.push('| Keyword | side-games | cards played | power per card | games decided by it | WR of side playing it |', '|---|---|---|---|---|---|');
for (const [k, v] of Object.entries(s.keywords).sort((a, b) => b[1].powerPerCard - a[1].powerPerCard))
L.push(`| ${k} | ${v.n} | ${v.cards} | ${v.powerPerCard >= 0 ? '+' : ''}${v.powerPerCard.toFixed(2)} | ${pct(v.flipRate)} | ${fmtRate(v.wr)}${sig(v.wr)} |`);
}
const corr = Object.entries(s.statCorrelation).filter(([, v]) => v.n >= 10);
if (corr.length) {
L.push('', '**Card stats vs lift** (numeric: Pearson r across cards; `card k:v`: mean lift, as a fraction):', '');
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');
}
+11
View File
@@ -0,0 +1,11 @@
# Usage: python3 scripts/sim/summary.py <out-dir> -> one-line-per-ruleset summary table (markdown)
import json, glob, sys, os
d = sys.argv[1]
print('| ruleset | n | draws | first-player WR | heavy | swarm | curve | starters | greedy>maxpower | decided in 1st third |')
print('|---|---|---|---|---|---|---|---|---|---|')
for f in sorted(glob.glob(os.path.join(d, '*.stats.json'))):
s = json.load(open(f)); by = s['byDeck']
g = lambda k: f"{by[k]['rate']*100:.1f}%" if k in by else 'n/a'
sk = s['skill'].get('greedy>maxpower', {}).get('rate')
fp = s['firstPlayer']
print(f"| {s['ruleset']} | {s['matches']} | {s['draws']} | {fp['rate']*100:.1f}% [{fp['lo']*100:.1f}–{fp['hi']*100:.1f}] | {g('heavy')} | {g('swarm')} | {g('curve')} | {s['byTag'].get('arch:starter',{}).get('rate',0)*100:.1f}% | {sk*100 if sk else float('nan'):.1f}% | {s['early']['decidedByThird']*100:.1f}% |")
+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,
};
+8
View File
@@ -0,0 +1,8 @@
{
"v1-power": { "powerByCost": [0, 1, 2, 4, 6, 8, 10] },
"v1-power-cap3": { "powerByCost": [0, 1, 2, 4, 6, 8, 10], "laneCapacity": 3, "underdog": false },
"v1-cap3-ot1": { "powerByCost": [0, 1, 2, 4, 6, 8, 10], "laneCapacity": 3, "underdog": false, "onTopicBonus": 1 },
"v1-heavy-buff": { "powerByCost": [0, 1, 2, 4, 6, 9, 12], "laneCapacity": 3, "underdog": false },
"v1-energy-plus1":{ "powerByCost": [0, 1, 2, 4, 6, 8, 10], "laneCapacity": 3, "underdog": false, "energyByTurn": [2, 3, 4, 5, 6, 7] },
"v1-turns7": { "powerByCost": [0, 1, 2, 4, 6, 8, 10], "laneCapacity": 3, "underdog": false, "turns": 7, "energyByTurn": [1, 2, 3, 4, 5, 6, 7] }
}
+10
View File
@@ -0,0 +1,10 @@
{
"cheap-power": { "powerByCost": [0, 2, 3, 4, 6, 8, 10] },
"vanilla2": { "vanillaBonus": 2 },
"carry2": { "energyCarryMax": 2 },
"energy2to7": { "energyByTurn": [2, 3, 4, 5, 6, 7] },
"cap4": { "laneCapacity": 4 },
"ontopic-cheap": { "onTopicBonus": [0, 2, 2, 2, 2, 3, 3] },
"cheap+carry2": { "powerByCost": [0, 2, 3, 4, 6, 8, 10], "energyCarryMax": 2 },
"combo": { "powerByCost": [0, 2, 3, 5, 6, 8, 10], "energyCarryMax": 2, "onTopicBonus": [0, 1, 1, 1, 2, 2, 3] }
}
+6
View File
@@ -0,0 +1,6 @@
{
"v1.1-critic": { "keywordParams": {
"rising": { "amount": 1, "cap": 2, "powerDelta": -1 },
"viral": { "amount": 1, "cap": 2, "powerDelta": 1 },
"encyclopedic": { "amount": 2, "powerDelta": 1 } } }
}
+13
View File
@@ -0,0 +1,13 @@
{
"k1-nerf3": { "keywordParams": {
"rising": { "amount": 1, "cap": 2, "powerDelta": -1 }, "nostalgic": { "amount": 2, "powerDelta": -1 }, "translated": { "amount": 1, "powerDelta": -1 } } },
"k2-nerf3-viral": { "keywordParams": {
"rising": { "amount": 1, "cap": 2, "powerDelta": -1 }, "nostalgic": { "amount": 2, "powerDelta": -1 }, "translated": { "amount": 1, "powerDelta": -1 },
"viral": { "amount": 2, "cap": 3, "powerDelta": 0 } } },
"k3-plus-ency": { "keywordParams": {
"rising": { "amount": 1, "cap": 2, "powerDelta": -1 }, "nostalgic": { "amount": 2, "powerDelta": -1 }, "translated": { "amount": 1, "powerDelta": -1 },
"viral": { "amount": 2, "cap": 3, "powerDelta": 0 }, "encyclopedic": { "amount": 3, "powerDelta": 0 } } },
"k4-soft": { "keywordParams": {
"rising": { "amount": 1, "cap": 1, "powerDelta": 0 }, "nostalgic": { "amount": 1, "powerDelta": 0 }, "translated": { "amount": 1, "powerDelta": -1 },
"viral": { "amount": 2, "cap": 3, "powerDelta": 0 }, "encyclopedic": { "amount": 3, "powerDelta": 0 } } }
}
+8
View File
@@ -0,0 +1,8 @@
{
"flat-a": { "powerByCost": [0, 2, 3, 5, 6, 8, 9] },
"flat-b": { "powerByCost": [0, 2, 4, 5, 7, 8, 10] },
"flat-c": { "powerByCost": [0, 2, 4, 6, 7, 9, 10] },
"flat-b+e27": { "powerByCost": [0, 2, 4, 5, 7, 8, 10], "energyByTurn": [2, 3, 4, 5, 6, 7] },
"flat-a+carry2": { "powerByCost": [0, 2, 3, 5, 6, 8, 9], "energyCarryMax": 2 },
"flat-b+carry2": { "powerByCost": [0, 2, 4, 5, 7, 8, 10], "energyCarryMax": 2 }
}
+6
View File
@@ -0,0 +1,6 @@
{
"v1.1-candidate": { "keywordParams": {
"rising": { "amount": 1, "cap": 2, "powerDelta": -1 }, "nostalgic": { "amount": 2, "powerDelta": -1 }, "translated": { "amount": 1, "powerDelta": -1 },
"viral": { "amount": 2, "cap": 3, "powerDelta": 0 }, "encyclopedic": { "amount": 3, "powerDelta": 0 },
"local": { "amount": 1, "powerDelta": 0 } } }
}
+3
View File
@@ -0,0 +1,3 @@
{
"v1": { "powerByCost": [0, 1, 2, 4, 6, 8, 10], "laneCapacity": 3, "underdog": false }
}
+290
View File
@@ -0,0 +1,290 @@
// 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, applyAction, createMatch, isOver, lanePower, legalActions, previewPool, replay, result, starterDeck, starterDeckById, STARTER_DECKS, validateDeck, viewFor, Rng as EngineRng,
type DerivationRules,
type Action, type CardInPlay, type GameCard, type MatchState, type PlayerId, type PlayerState, type PlayerView, type Ruleset,
} from '../game/index.ts';
import type { DeckSpec, EngineAdapter, Rng, Seat } from './types.ts';
import { makeBot } from './index.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.queue.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.queue) {
const card = me.hand.find(c => c.cardId === play.cardId);
if (card) lanes[play.lane].cards[seat].push({ card, owner: seat, lane: play.lane, turn: state.turn, bonus: 0, seq: 1e9 + lanes[play.lane].cards[seat].length });
}
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]]);
/**
* Lanes after hypothetically resolving this turn with `seat`'s queue and an opponent who passes
* (its hidden queue is dropped), so on-reveal and end-of-turn keywords and reveal order count.
* Falls back to projectedLanes if the engine refuses.
*/
export function resolvedLanes(state: MatchState, seat: Seat): [number, number][] | MatchState {
try {
let s = { ...state, players: state.players.map(p => ({ ...p })) as MatchState['players'] };
const o = other(seat);
s.players[o].queue = [];
s.players[o].committed = false;
if (!s.players[seat].committed) s = applyAction(s, { type: 'commit', player: seat });
s = applyAction(s, { type: 'commit', player: o });
if (s.result) return s;
return s.lanes.map((_, i) => orient(lanePower(s, i), seat));
} catch {
return projectedLanes(state, seat);
}
}
/** Heuristic for `seat` in [-1, 1]: soft lane wins plus total power, from the hypothetically resolved turn. */
export function evaluateFor(state: MatchState, seat: Seat): number {
if (state.result) return state.result.winner === null ? 0 : state.result.winner === seat ? 1 : -1;
const r = state.players[seat].queue.length ? resolvedLanes(state, seat) : projectedLanes(state, seat);
if (!Array.isArray(r)) return r.result!.winner === null ? 0 : r.result!.winner === seat ? 0.95 : -0.95;
const lanes = r;
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.queue.length - (them.hand.length - them.queue.length)) * 0.02;
const unspent = energyLeft(me) * -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));
}
/**
* Rebuild a full MatchState from what `view.you` can see (viewFor), for bots to search on.
* Hidden parts are sampled from `filler`: the opponent's hand and deck, and our own deck order and contents
* (the view gives counts only). The opponent's queue is empty and uncommitted: it re-decides in rollouts.
*/
export function stateFromView(view: PlayerView, rng: Rng, filler: readonly GameCard[]): MatchState {
let k = 0;
const draw = (n: number) => Array.from({ length: n }, () => ({ ...filler[Math.floor(rng() * filler.length)], cardId: `hidden:${k++}` }));
const me = view.you, them = other(me);
const players = [] as unknown as [PlayerState, PlayerState];
players[me] = { deck: draw(view.deckCount), hand: view.hand, energy: view.energy, queue: view.queue, committed: view.committed, afk: 0, carry: 0 };
players[them] = { deck: draw(view.opponent.deckCount), hand: draw(view.opponent.handCount), energy: view.energy, queue: [], committed: false, afk: 0, carry: 0 };
let seq = 0;
const lanes = view.lanes.map(l => {
const cards = [] as unknown as [CardInPlay[], CardInPlay[]];
cards[me] = l.cards[0]; cards[them] = l.cards[1];
for (const side of l.cards) for (const c of side) seq = Math.max(seq, c.seq);
return { topic: l.topic, portalRevealed: l.portalRevealed, cards };
});
return {
schema: 'wikideck-match/1', engineVersion: 1, ruleset: view.ruleset, seed: 0,
rng: new EngineRng(Math.floor(rng() * 4294967296)).state,
turn: view.turn, phase: view.phase, initiative: view.initiative, revealSeq: seq,
players, lanes, log: [], actions: [], result: view.result,
};
}
/** Energy left after queued plays (the engine deducts queued costs at reveal). */
export function energyLeft(p: PlayerState): number {
return p.energy - p.queue.reduce((t, q) => t + (p.hand.find(c => c.cardId === q.cardId)?.cost ?? 0), 0);
}
// ---------- decks ----------
/** DESIGN §10.1: cost-1 cards have no keyword and get +vanillaBonus (if the ruleset has that key). */
function vanillaBonus(rules: Ruleset, c: GameCard): number {
const v = (rules as unknown as Record<string, unknown>).vanillaBonus;
return typeof v === 'number' && c.cost === 1 ? v : 0;
}
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.faction, (cats.get(c.faction) ?? 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 / 2) 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.5 ? 'curve:low' : avg >= 4.25 ? 'curve:high' : 'curve:mid');
return [...tags];
}
/** Base (one copy) cards of the default sim pool: the engine's preview pool. */
export function starterPoolCards(): GameCard[] {
return previewPool().map(c => ({ ...c, cardId: baseId(c.cardId) }));
}
/** Card id without its copy suffix (`loaner:123:1` -> `loaner:123`). */
export const baseId = (id: string) => id.replace(/:\d+$/, '');
const copyOf = (c: GameCard, copy: number): GameCard => ({ ...c, cardId: `${c.cardId}:${copy}` });
const pageKey = (c: GameCard): string | number => c.pageId ?? baseId(c.cardId);
/**
* Fill a deck of `size` from `pool`, best `score` first (score <= 0 = excluded, ties: higher power),
* up to `copies` per page. Returns null if the pool can't fill it.
*/
export function buildDeck(pool: GameCard[], score: (c: GameCard) => number, size: number, copies: number): GameCard[] | null {
const ranked = pool.map(c => ({ c, v: score(c) })).filter(x => x.v > 0).sort((a, b) => b.v - a.v || b.c.power - a.c.power);
const out: GameCard[] = [];
const used = new Map<string | number, number>();
for (let copy = 0; copy < copies && out.length < size; copy++)
for (const { c } of ranked) {
if (out.length >= size) break;
const k = pageKey(c), n = used.get(k) ?? 0;
if (n > copy) continue;
used.set(k, n + 1);
out.push(copyOf(c, copy));
}
return out.length === size ? out : null;
}
/** Deck that follows a target cost curve (counts per cost 1..6), using `filter`ed cards first. */
function curveDeck(pool: GameCard[], size: number, copies: number, filter: (c: GameCard) => boolean = () => true, curve = [0, 2, 3, 3, 2, 1, 1]): GameCard[] | null {
const target = curve.map(n => Math.round((n * size) / 12));
const out: GameCard[] = [];
const used = new Map<string | number, number>();
const take = (c: GameCard) => { const k = pageKey(c), n = used.get(k) ?? 0; if (n >= copies) return false; used.set(k, n + 1); out.push(copyOf(c, n)); return true; };
for (let cost = 1; cost <= 6; cost++) {
const cands = pool.filter(c => c.cost === cost).sort((a, b) => Number(filter(b)) - Number(filter(a)) || b.power - a.power);
let need = target[cost];
for (let pass = 0; pass < copies && need > 0; pass++) for (const c of cands) { if (need <= 0) break; if (take(c)) need--; }
}
const rest = [...pool].sort((a, b) => Number(filter(b)) - Number(filter(a)) || Math.abs(a.cost - 3) - Math.abs(b.cost - 3));
for (let pass = 0; pass < copies && out.length < size; pass++) for (const c of rest) { if (out.length >= size) break; take(c); }
return out.length === size ? out.slice(0, size) : null;
}
/**
* Sim decks: seeded starter decks (if the engine provides them) plus archetypes built from `pool`:
* curve, heavy (cost >= 5 first), swarm (cost <= 2), mono-faction and keyword-focused curve decks.
*/
export function defaultDecks(rules: Ruleset, extra: DeckSpec[] = [], pool: GameCard[] = starterPoolCards(), seededStarters = true): DeckSpec[] {
const size = rules.deckSize, copies = rules.maxCopiesPerPage;
const decks: DeckSpec[] = [];
// DESIGN §1.3: power depends only on cost, so loaners follow the ruleset's powerByCost.
// §10.1 powerDelta (applied at derivation, not by the engine).
const delta = (c: GameCard) => (c.keyword ? (rules.keywordParams?.[c.keyword]?.powerDelta ?? 0) : 0);
const repower = (c: GameCard): GameCard => (c.source === 'loaner' && rules.powerByCost[c.cost] !== undefined ? { ...c, power: Math.max(0, rules.powerByCost[c.cost] + (c.keyword ? 0 : vanillaBonus(rules, c)) + delta(c)) } : c);
pool = pool.map(repower);
const add = (id: string, cards: GameCard[] | null, tags: string[]) => {
if (cards) cards = cards.map(repower);
if (cards && !validateDeck(rules, cards).length) decks.push({ id, tags: tagDeck(cards, tags), payload: cards });
};
// DESIGN §2.1 starter decks (engine-pinned loaners).
for (const def of STARTER_DECKS) add(`starter-${def.id}`, starterDeckById(def.id, rules as unknown as DerivationRules), ['arch:starter-v1']);
if (seededStarters) for (let i = 0; i < 6; i++) add(`seeded-${i}`, starterDeck(`sim-${i}`), ['arch:starter']);
add('curve', curveDeck(pool, size, copies), ['arch:curve']);
add('heavy', buildDeck(pool, c => (c.cost >= 5 ? 10 + c.cost : c.cost >= 4 ? 5 : 0), size, copies), ['arch:heavy']);
add('top-heavy', curveDeck(pool, size, copies, undefined, [0, 1, 1, 2, 2, 3, 3]), ['arch:top-heavy']);
add('swarm', buildDeck(pool, c => (c.cost <= 2 ? 10 - c.cost : c.cost === 3 ? 1 : 0), size, copies), ['arch:swarm']);
const cats = [...new Set(pool.map(c => c.faction))].sort();
for (const cat of cats) if (pool.filter(c => c.faction === cat).length >= 6)
add(`mono-${cat}`, curveDeck(pool, size, copies, c => c.faction === cat), ['arch:mono-faction']);
const kws = [...new Set(pool.map(c => c.keyword).filter((k): k is string => !!k))].sort();
for (const kw of kws) if (pool.filter(c => c.keyword === kw).length >= 3)
add(`kw-${kw}`, curveDeck(pool, size, copies, c => c.keyword === kw), ['arch:keyword']);
for (const d of extra) add(d.id, d.payload as GameCard[], d.tags);
return decks;
}
// ---------- adapter ----------
export interface GameEngineOptions {
rulesets?: Record<string, Ruleset>;
extraDecks?: DeckSpec[];
/** Card pool for archetype decks (one copy per page). Default: the engine's starter pool. */
pool?: GameCard[];
/** Also include the engine's seeded placeholder decks `starterDeck(seed)` (default false). */
seededStarters?: boolean;
}
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>();
// Filler for hidden cards: the sim's card pool, powered by the view's ruleset.
const fillerCache = new Map<Ruleset, GameCard[]>();
const fillerFor = (r: Ruleset) => {
if (!fillerCache.has(r)) fillerCache.set(r, (opts.pool ?? starterPoolCards()).map(c => ({ ...c, power: r.powerByCost[c.cost] ?? c.power })));
return fillerCache.get(r)!;
};
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, opts.pool, opts.seededStarters ?? false);
for (const deck of d) for (const c of deck.payload as GameCard[]) meta.set(baseId(c.cardId), 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 queues first, then seat 1. Bots never read the other side's queued plays
// (evaluateFor hides them; lookahead determinizes), so the order leaks nothing.
toAct: s => (s.players[0].committed ? 1 : 0),
// Undo/timeout/concede are excluded: they never help a bot and let random bots loop.
legalActions: (s, seat) => legalActions(s, seat).filter(a => a.type === 'play' || a.type === 'commit'),
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' ? [baseId(a.cardId)] : []),
actionKind: a => a.type,
cardMeta(id) {
const c = meta.get(id);
if (!c) return undefined;
return { label: c.title, cost: c.cost, power: c.power, powerPerCost: c.power / Math.max(1, c.cost), keyword: c.keyword ?? 'vanilla', faction: c.faction, home: c.home };
},
firstSeat: s => s.initiative,
observe: (s, seat) => viewFor(s, seat),
assume: (view, _seat, rng) => stateFromView(view as PlayerView, rng, fillerFor((view as PlayerView).ruleset)),
keywordValues(final, decks) {
const out: { seat: Seat; keyword: string; power: number; flip: number; cards: number }[] = [];
const r0 = final.result;
if (!r0) return out;
const payload = [decks[0].payload as GameCard[], decks[1].payload as GameCard[]] as const;
const score = (w: PlayerId | null, seat: Seat) => (w === null ? 0 : w === seat ? 1 : -1);
for (const seat of [0, 1] as Seat[]) {
const played = new Set(final.actions.filter(a => a.type === 'play' && a.player === seat).map(a => (a as { cardId: string }).cardId));
const byKw = new Map<string, number>();
for (const c of payload[seat]) if (c.keyword && played.has(c.cardId)) byKw.set(c.keyword, (byKw.get(c.keyword) ?? 0) + 1);
for (const [kw, cards] of byKw) {
const stripped = payload[seat].map(c => (c.keyword === kw ? { ...c, keyword: null } : c));
const decks2 = (seat === 0 ? [stripped, payload[1]] : [payload[0], stripped]) as [GameCard[], GameCard[]];
try {
const r1 = replay(final.ruleset, decks2, final.seed, final.actions).result;
if (!r1) continue;
out.push({ seat, keyword: kw, cards, power: r0.totalPower[seat] - r1.totalPower[seat], flip: score(r0.winner, seat) > score(r1.winner, seat) ? 1 : 0 });
} catch { /* replay diverged (e.g. a keyword changed legality); skip */ }
}
}
return out;
},
actionPower: (s, a) => (a.type === 'play' ? s.players[a.player].hand.find(c => c.cardId === a.cardId)?.power ?? 0 : -1),
};
}
export const gameEngine = makeGameEngine();
/** For the browser AI (ui-b): a bot that takes only the engine PlayerView. */
export function makeViewBot(name: string, engine: EngineAdapter<MatchState, Action> = gameEngine): (view: PlayerView, rng: Rng) => Action {
const bot = makeBot(name, engine);
return (view, rng) => bot(view, view.you, rng);
}
+130
View File
@@ -0,0 +1,130 @@
// 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)];
/** The state a bot reasons about: a determinization of its observation (or the state itself if the engine has no views). */
function see<S, A>(engine: EngineAdapter<S, A>, obs: unknown, seat: Seat, rng: Rng): S {
return engine.assume ? engine.assume(obs, seat, rng) : (obs as S);
}
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<unknown, A> {
return (obs, player, rng) => pick(engine.legalActions(see(engine, obs, player, rng), 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<unknown, A> {
return (obs, player, rng) => {
const state = see(engine, obs, player, rng);
return greedyChoice(engine, state, player, engine.legalActions(state, player), rng);
};
}
/**
* Naive "always play the highest-power card" player (DESIGN §8 target: < 55% vs a smart bot).
* Plays the highest printed-power affordable card into a random legal lane; ends the turn when nothing fits.
*/
export function maxPowerBot<S, A>(engine: EngineAdapter<S, A>): BotFn<unknown, A> {
return (obs, player, rng) => {
const state = see(engine, obs, player, rng);
const actions = engine.legalActions(state, player);
if (!engine.actionPower) return greedyChoice(engine, state, player, actions, rng);
let best: A[] = [], bestP = -Infinity;
for (const a of actions) {
const p = engine.actionPower(state, a);
if (p > bestP) { bestP = p; best = [a]; } else if (p === bestP) best.push(a);
}
return pick(best, 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<unknown, A> {
const k = opts.k ?? 4, rollouts = opts.rollouts ?? 8, horizon = opts.horizon ?? 40, eps = opts.epsilon ?? 0.25;
return (obs, seat, rng) => {
const state = see(engine, obs, 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.assume ? engine.applyAction(engine.assume(obs, seat, rng), c.a) : c.next, steps = 0; // fresh hidden sample per rollout
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', 'maxpower', 'greedy', 'lookahead-lite', 'lookahead'] as const;
export type BotName = typeof BOT_NAMES[number];
export function makeBot<S, A>(name: string, engine: EngineAdapter<S, A>): BotFn<unknown, A> {
switch (name) {
case 'random': return randomBot(engine);
case 'maxpower': return maxPowerBot(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}`);
}
}
+84
View File
@@ -0,0 +1,84 @@
// 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;
}
+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(engine.rulesets()[0]);
for (const name of ['random', 'greedy', 'lookahead-lite']) {
const bot = makeBot(name, engine);
let s = engine.createMatch(engine.rulesets()[0], [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(engine.observe ? engine.observe(s, seat) : 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`);
}
});