diff --git a/docs/game/BALANCE.md b/docs/game/BALANCE.md new file mode 100644 index 0000000..8204c77 --- /dev/null +++ b/docs/game/BALANCE.md @@ -0,0 +1,76 @@ +# WikiDeck: Edit War — balance report + +Owner: sim-balance (claude/wikideck#4). Harness: `shared/bots/`, `scripts/sim/` (PR #14). + + + +## 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-` curve decks for factions with ≥ 6 cards +- `kw-` 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..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. diff --git a/scripts/sim/card-pool.ts b/scripts/sim/card-pool.ts new file mode 100644 index 0000000..6d8d538 --- /dev/null +++ b/scripts/sim/card-pool.ts @@ -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 = { + Culture: 'viral', Nature: 'rising', People: 'local', Science: 'encyclopedic', History: 'nostalgic', Space: 'translated', +}; + +interface RawCard { pageId: number; title: string; category?: string; legacyCategory?: string; stats: Record; 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 = { 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; + 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; + 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` })) }; + }); +} diff --git a/scripts/sim/match.ts b/scripts/sim/match.ts new file mode 100644 index 0000000..c5cda21 --- /dev/null +++ b/scripts/sim/match.ts @@ -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( + engine: EngineAdapter, ruleset: string, decks: [DeckSpec, DeckSpec], botNames: [string, string], seed: number, +): MatchRecord { + const t0 = performance.now(); + const bots: [BotFn, BotFn] = [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 = {}; + 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); +} diff --git a/scripts/sim/run.ts b/scripts/sim/run.ts new file mode 100644 index 0000000..9f0e88b --- /dev/null +++ b/scripts/sim/run.ts @@ -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 /.jsonl (records), /.stats.json and /.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> { + 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 = { base: DEFAULT_RULESET }; + if (file) { + // { "": { "extends": "base", ...partial Ruleset } } — shallow-merged per top-level key. + const variants = JSON.parse(readFileSync(file, 'utf8')) as Record; + 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 = { + 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, 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, 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((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); }); diff --git a/scripts/sim/stats.ts b/scripts/sim/stats.ts new file mode 100644 index 0000000..ff2efca --- /dev/null +++ b/scripts/sim/stats.ts @@ -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; + skill: Record; // "lookahead>greedy": win rate of the stronger bot + byDeck: Record; // excluding mirrors + byTag: Record; // excluding games where both sides share the tag + matchups: Record>; + cards: CardStat[]; + statCorrelation: Record; + reasons: Record; + /** Counterfactual keyword value (see EngineAdapter.keywordValues), per keyword. */ + keywords: Record; +} + +/** 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): RulesetStats { + const ruleset = records[0]?.ruleset ?? '?'; + const decisive = records.filter(m => m.winner !== null); + const sym = decisive.filter(symmetric); + const reasons: Record = {}; + 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(); + 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 = {}; + 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, key: string, won: boolean) => { + const t = map[key] ?? (map[key] = { w: 0, n: 0 }); t.n++; if (won) t.w++; + }; + const deckT: Record = {}, tagT: Record = {}; + const mu: Record> = {}; + const cardT = new Map(); + const deckAll: Record = {}; + 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(); + 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) => 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(); + 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 = {}; + 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 = {}; + 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'); +} diff --git a/scripts/sim/summary.py b/scripts/sim/summary.py new file mode 100644 index 0000000..8091ef3 --- /dev/null +++ b/scripts/sim/summary.py @@ -0,0 +1,11 @@ +# Usage: python3 scripts/sim/summary.py -> 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}% |") diff --git a/scripts/sim/toy-engine.ts b/scripts/sim/toy-engine.ts new file mode 100644 index 0000000..e565ac2 --- /dev/null +++ b/scripts/sim/toy-engine.ts @@ -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 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 = { + 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, +}; diff --git a/scripts/sim/variants/design-sweep.json b/scripts/sim/variants/design-sweep.json new file mode 100644 index 0000000..14996fb --- /dev/null +++ b/scripts/sim/variants/design-sweep.json @@ -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] } +} diff --git a/scripts/sim/variants/v1.1-candidates.json b/scripts/sim/variants/v1.1-candidates.json new file mode 100644 index 0000000..7d3e495 --- /dev/null +++ b/scripts/sim/variants/v1.1-candidates.json @@ -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] } +} diff --git a/scripts/sim/variants/v1.1-critic.json b/scripts/sim/variants/v1.1-critic.json new file mode 100644 index 0000000..ee33a08 --- /dev/null +++ b/scripts/sim/variants/v1.1-critic.json @@ -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 } } } +} diff --git a/scripts/sim/variants/v1.1-keywords.json b/scripts/sim/variants/v1.1-keywords.json new file mode 100644 index 0000000..f20ee71 --- /dev/null +++ b/scripts/sim/variants/v1.1-keywords.json @@ -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 } } } +} diff --git a/scripts/sim/variants/v1.1-power.json b/scripts/sim/variants/v1.1-power.json new file mode 100644 index 0000000..37d2811 --- /dev/null +++ b/scripts/sim/variants/v1.1-power.json @@ -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 } +} diff --git a/scripts/sim/variants/v1.1.json b/scripts/sim/variants/v1.1.json new file mode 100644 index 0000000..f4a777e --- /dev/null +++ b/scripts/sim/variants/v1.1.json @@ -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 } } } +} diff --git a/scripts/sim/variants/v1.json b/scripts/sim/variants/v1.json new file mode 100644 index 0000000..31413f4 --- /dev/null +++ b/scripts/sim/variants/v1.json @@ -0,0 +1,3 @@ +{ + "v1": { "powerByCost": [0, 1, 2, 4, 6, 8, 10], "laneCapacity": 3, "underdog": false } +} diff --git a/shared/bots/game-adapter.ts b/shared/bots/game-adapter.ts new file mode 100644 index 0000000..20329bc --- /dev/null +++ b/shared/bots/game-adapter.ts @@ -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).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(); + const kws = new Map(); + 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(); + 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(); + 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; + 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 { + const rulesets = opts.rulesets ?? { base: DEFAULT_RULESET }; + const deckCache = new Map(); + const meta = new Map(); + // Filler for hidden cards: the sim's card pool, powered by the view's ruleset. + const fillerCache = new Map(); + 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(); + 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 = gameEngine): (view: PlayerView, rng: Rng) => Action { + const bot = makeBot(name, engine); + return (view, rng) => bot(view, view.you, rng); +} diff --git a/shared/bots/index.ts b/shared/bots/index.ts new file mode 100644 index 0000000..3e2dc28 --- /dev/null +++ b/shared/bots/index.ts @@ -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 = (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(engine: EngineAdapter, obs: unknown, seat: Seat, rng: Rng): S { + return engine.assume ? engine.assume(obs, seat, rng) : (obs as S); +} + +function terminalValue(engine: EngineAdapter, s: S, seat: Seat): number { + const { winner } = engine.result(s); + return winner === null ? 0 : winner === seat ? 1 : -1; +} + +function value(engine: EngineAdapter, 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(engine: EngineAdapter): BotFn { + return (obs, player, rng) => pick(engine.legalActions(see(engine, obs, player, rng), player), rng); +} + +function greedyChoice(engine: EngineAdapter, 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(engine: EngineAdapter): BotFn { + 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(engine: EngineAdapter): BotFn { + 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(engine: EngineAdapter, opts: LookaheadOptions = {}): BotFn { + 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(name: string, engine: EngineAdapter): BotFn { + 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}`); + } +} diff --git a/shared/bots/types.ts b/shared/bots/types.ts new file mode 100644 index 0000000..3d0b32f --- /dev/null +++ b/shared/bots/types.ts @@ -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 { + 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 | 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 = (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; + ms: number; +} diff --git a/tests/bots-sim.test.ts b/tests/bots-sim.test.ts new file mode 100644 index 0000000..7f4bfc3 --- /dev/null +++ b/tests/bots-sim.test.ts @@ -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; + 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`); + } +});