[sim-balance] Bots, balance simulation harness and BALANCE.md report v1 #14

Merged
claude merged 20 commits from night/sim/balance-harness into night/2026-11-16 2026-11-17 06:01:53 +00:00
5 changed files with 93 additions and 35 deletions
Showing only changes of commit a70e0c57aa - Show all commits
+5 -3
View File
@@ -36,10 +36,12 @@ export async function loadEngine(name: string): Promise<EngineAdapter<any, any>>
/** Bot pairings and their share of the schedule. Symmetric pairs carry the balance stats. */
export const DEFAULT_MIX: [string, string, number][] = [
['greedy', 'greedy', 0.55],
['lookahead-lite', 'lookahead-lite', 0.15],
['random', 'random', 0.1],
['lookahead-lite', 'lookahead-lite', 0.12],
['random', 'random', 0.05],
['greedy', 'lookahead-lite', 0.1],
['random', 'greedy', 0.1],
['maxpower', 'lookahead-lite', 0.08],
['maxpower', 'greedy', 0.05],
['random', 'greedy', 0.05],
];
interface Job { i: number; seed: number; decks: [number, number]; bots: [string, string] }
+1 -1
View File
@@ -72,7 +72,7 @@ export function aggregate(records: MatchRecord[], errors = 0, engine?: EngineAda
};
}
const skill: Record<string, Rate> = {};
const order = ['random', 'greedy', 'lookahead-lite', 'lookahead'];
const order = ['random', 'maxpower', 'greedy', 'lookahead-lite', 'lookahead'];
for (const m of decisive) {
if (symmetric(m)) continue;
const [a, b] = m.bots;
+66 -30
View File
@@ -64,8 +64,6 @@ export function determinize(state: MatchState, seat: Seat, rng: Rng): MatchState
// ---------- decks ----------
type Spec = (typeof STARTER_POOL)[number];
function tagDeck(cards: GameCard[], base: string[]): string[] {
const tags = new Set(base);
const cats = new Map<string, number>();
@@ -75,42 +73,77 @@ function tagDeck(cards: GameCard[], base: string[]): string[] {
kws.set(c.keyword ?? 'vanilla', (kws.get(c.keyword ?? 'vanilla') ?? 0) + 1);
}
const [topCat, nCat] = [...cats].sort((a, b) => b[1] - a[1])[0];
if (nCat >= cards.length / 3) tags.add(`cat:${topCat}`);
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.75 ? 'curve:low' : avg >= 4 ? 'curve:high' : 'curve:mid');
tags.add(avg <= 2.5 ? 'curve:low' : avg >= 4.25 ? 'curve:high' : 'curve:mid');
return [...tags];
}
/** Build a deck of `size` from specs ranked by `score`, up to `copies` per page. */
function themed(score: (s: Spec) => number, size: number, copies: number): GameCard[] {
const ranked = [...STARTER_POOL].map(s => ({ s, v: score(s) })).filter(x => x.v > 0).sort((a, b) => b.v - a.v || a.s[3] - b.s[3]);
const out: GameCard[] = [];
for (let copy = 0; copy < copies && out.length < size; copy++)
for (const { s } of ranked) { if (out.length >= size) break; out.push(starterCard(s, copy)); }
return out;
/** Base (one copy) cards of the default sim pool: the engine's starter pool. */
export function starterPoolCards(): GameCard[] {
return STARTER_POOL.map(spec => { const c = starterCard(spec, 0); return { ...c, id: c.id.replace(/:\d+$/, '') }; });
}
export function defaultDecks(rules: Ruleset, extra: DeckSpec[] = []): DeckSpec[] {
const copyOf = (c: GameCard, copy: number): GameCard => ({ ...c, id: `${c.id}:${copy}` });
const pageKey = (c: GameCard) => (c.pageId ?? c.id);
/**
* 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): GameCard[] | null {
const target = [0, 2, 3, 3, 2, 1, 1].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()): DeckSpec[] {
const size = rules.deck.min, copies = rules.deck.maxCopiesPerPage;
const decks: DeckSpec[] = [];
for (let i = 0; i < 8; i++) {
const cards = starterDeck(`sim-${i}`, rules);
decks.push({ id: `starter-${i}`, tags: tagDeck(cards, ['arch:starter']), payload: cards });
}
const arche: [string, (s: Spec) => number][] = [
['rally', s => (s[5] === 'rally' ? 10 - s[3] : s[3] <= 2 ? 1 : 0)],
['anchor', s => (s[5] === 'anchor' ? 10 - s[3] : s[3] <= 2 ? 1 : 0)],
['vanilla', s => (s[5] === null ? 10 - Math.abs(3.5 - s[3]) : 0)],
['low-curve', s => (s[3] <= 3 ? 10 + s[4] - s[3] : 0)],
['high-curve', s => (s[3] >= 3 ? s[3] : 0)],
];
for (const [name, score] of arche) {
const cards = themed(score, size, copies);
if (!validateDeck(rules, cards).length) decks.push({ id: name, tags: tagDeck(cards, [`arch:${name}`]), payload: cards });
}
for (const d of extra) if (!validateDeck(rules, d.payload as GameCard[]).length)
decks.push({ ...d, tags: tagDeck(d.payload as GameCard[], d.tags) });
const add = (id: string, cards: GameCard[] | null, tags: string[]) => {
if (cards && !validateDeck(rules, cards).length) decks.push({ id, tags: tagDeck(cards, tags), payload: cards });
};
for (let i = 0; i < 6; i++) add(`starter-${i}`, starterDeck(`sim-${i}`, rules), ['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('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.category))].sort();
for (const cat of cats) if (pool.filter(c => c.category === cat).length >= 6)
add(`mono-${cat}`, curveDeck(pool, size, copies, c => c.category === 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;
}
@@ -119,6 +152,8 @@ export function defaultDecks(rules: Ruleset, extra: DeckSpec[] = []): DeckSpec[]
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[];
}
export function makeGameEngine(opts: GameEngineOptions = {}): EngineAdapter<MatchState, Action> {
@@ -135,7 +170,7 @@ export function makeGameEngine(opts: GameEngineOptions = {}): EngineAdapter<Matc
rulesets: () => Object.keys(rulesets),
decks(id) {
if (!deckCache.has(id)) {
const d = defaultDecks(rules(id), opts.extraDecks);
const d = defaultDecks(rules(id), opts.extraDecks, opts.pool);
for (const deck of d) for (const c of deck.payload as GameCard[]) meta.set(c.id, c);
deckCache.set(id, d);
}
@@ -160,6 +195,7 @@ export function makeGameEngine(opts: GameEngineOptions = {}): EngineAdapter<Matc
return { label: c.name, cost: c.cost, power: c.power, powerPerCost: c.power / Math.max(1, c.cost), keyword: c.keyword ?? 'vanilla', category: c.category };
},
firstSeat: s => s.firstToReveal,
actionPower: (s, a) => (a.type === 'play' ? s.players[a.player].hand.find(c => c.id === a.cardId)?.power ?? 0 : -1),
determinize,
};
}
+19 -1
View File
@@ -48,6 +48,23 @@ export function greedyBot<S, A>(engine: EngineAdapter<S, A>): BotFn<S, A> {
return (state, player, rng) => greedyChoice(engine, state, player, engine.legalActions(state, player), rng);
}
/**
* 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<S, A> {
return (state, 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 }
/**
@@ -88,12 +105,13 @@ export function lookaheadBot<S, A>(engine: EngineAdapter<S, A>, opts: LookaheadO
};
}
export const BOT_NAMES = ['random', 'greedy', 'lookahead', 'lookahead-lite'] as const;
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<S, 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 });
+2
View File
@@ -42,6 +42,8 @@ export interface EngineAdapter<S = unknown, A = unknown> {
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;
/** Seat with the first-player advantage (defaults to toAct at match start). */
firstSeat?(state: S): Seat;
/** Resample information hidden from `seat` (opponent hand/staged plays, deck order) before searching. */