sim-balance: bots see only viewFor(state, seat); stateFromView determinization; makeViewBot for ui-b; engine 2.1 starter decks

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-16 23:57:31 -05:00
co-authored by Claude Opus 5.5
parent 79384ed77b
commit 003c8f2315
6 changed files with 77 additions and 38 deletions
+3 -2
View File
@@ -7,7 +7,7 @@ export function playMatch<S, A>(
engine: EngineAdapter<S, A>, ruleset: string, decks: [DeckSpec, DeckSpec], botNames: [string, string], seed: number, engine: EngineAdapter<S, A>, ruleset: string, decks: [DeckSpec, DeckSpec], botNames: [string, string], seed: number,
): MatchRecord { ): MatchRecord {
const t0 = performance.now(); const t0 = performance.now();
const bots: [BotFn<S, A>, BotFn<S, A>] = [makeBot(botNames[0], engine), makeBot(botNames[1], engine)]; const bots: [BotFn<unknown, A>, BotFn<unknown, A>] = [makeBot(botNames[0], engine), makeBot(botNames[1], engine)];
const rng = [mulberry32(seed ^ 0x9e3779b9), mulberry32(seed ^ 0x85ebca6b)]; const rng = [mulberry32(seed ^ 0x9e3779b9), mulberry32(seed ^ 0x85ebca6b)];
let s = engine.createMatch(ruleset, decks, seed); let s = engine.createMatch(ruleset, decks, seed);
const firstSeat = engine.firstSeat ? engine.firstSeat(s) : engine.toAct(s); const firstSeat = engine.firstSeat ? engine.firstSeat(s) : engine.toAct(s);
@@ -19,7 +19,8 @@ export function playMatch<S, A>(
const turn = engine.turn(s); const turn = engine.turn(s);
if (turn !== lastTurn) { evalTrace.push(engine.evaluate(s, 0)); lastTurn = turn; } if (turn !== lastTurn) { evalTrace.push(engine.evaluate(s, 0)); lastTurn = turn; }
const seat = engine.toAct(s); const seat = engine.toAct(s);
const a = bots[seat](s, seat, rng[seat]); // 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); for (const c of engine.cardsOf(s, a)) cardsPlayed[seat].push(c);
const k = engine.actionKind(a); const k = engine.actionKind(a);
actionKinds[k] = (actionKinds[k] ?? 0) + 1; actionKinds[k] = (actionKinds[k] ?? 0) + 1;
+1 -1
View File
@@ -37,7 +37,7 @@ export async function loadEngine(name: string): Promise<EngineAdapter<any, any>>
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 }); 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 });
} }
if (pool && process.env.SIM_OWNED) extraDecks.push(...cp.ownedDecks(pool, Number(process.env.SIM_OWNED))); if (pool && process.env.SIM_OWNED) extraDecks.push(...cp.ownedDecks(pool, Number(process.env.SIM_OWNED)));
return makeGameEngine({ rulesets, pool, extraDecks, seededStarters: !process.env.SIM_STARTERS }); return makeGameEngine({ rulesets, pool, extraDecks });
} }
throw new Error(`unknown engine ${name}`); throw new Error(`unknown engine ${name}`);
} }
+46 -20
View File
@@ -1,10 +1,12 @@
// EngineAdapter over the public shared/game API, plus the starter/archetype decks used // 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. // by the balance simulation. Pure: rulesets and extra decks are passed in, no I/O.
import { import {
DEFAULT_RULESET, applyAction, createMatch, isOver, lanePower, legalActions, previewPool, replay, result, starterDeck, validateDeck, DEFAULT_RULESET, applyAction, createMatch, isOver, lanePower, legalActions, previewPool, replay, result, starterDeck, starterDeckById, STARTER_DECKS, validateDeck, viewFor, Rng as EngineRng,
type Action, type CardInPlay, type GameCard, type MatchState, type PlayerId, type PlayerState, type Ruleset, type DerivationRules,
type Action, type CardInPlay, type GameCard, type MatchState, type PlayerId, type PlayerState, type PlayerView, type Ruleset,
} from '../game/index.ts'; } from '../game/index.ts';
import type { DeckSpec, EngineAdapter, Rng, Seat } from './types.ts'; import type { DeckSpec, EngineAdapter, Rng, Seat } from './types.ts';
import { makeBot } from './index.ts';
const other = (p: PlayerId): PlayerId => (p === 0 ? 1 : 0); const other = (p: PlayerId): PlayerId => (p === 0 ? 1 : 0);
@@ -62,21 +64,30 @@ export function evaluateFor(state: MatchState, seat: Seat): number {
} }
/** /**
* Determinize hidden information before a lookahead for `seat`: the opponent's queued plays * Rebuild a full MatchState from what `view.you` can see (viewFor), for bots to search on.
* are taken back (it re-decides in the rollouts) and its hand and deck are reshuffled together. * 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 determinize(state: MatchState, seat: Seat, rng: Rng): MatchState { export function stateFromView(view: PlayerView, rng: Rng, filler: readonly GameCard[]): MatchState {
const s = structuredClone(state); let k = 0;
const o = other(seat), opp = s.players[o]; const draw = (n: number) => Array.from({ length: n }, () => ({ ...filler[Math.floor(rng() * filler.length)], cardId: `hidden:${k++}` }));
opp.queue = []; const me = view.you, them = other(me);
opp.committed = false; const players = [] as unknown as [PlayerState, PlayerState];
const pool = [...opp.hand, ...opp.deck]; players[me] = { deck: draw(view.deckCount), hand: view.hand, energy: view.energy, queue: view.queue, committed: view.committed, afk: 0, carry: 0 };
for (let i = pool.length - 1; i > 0; i--) { const j = Math.floor(rng() * (i + 1)); [pool[i], pool[j]] = [pool[j], pool[i]]; } players[them] = { deck: draw(view.opponent.deckCount), hand: draw(view.opponent.handCount), energy: view.energy, queue: [], committed: false, afk: 0, carry: 0 };
opp.hand = pool.slice(0, opp.hand.length); let seq = 0;
opp.deck = pool.slice(opp.hand.length); const lanes = view.lanes.map(l => {
const mine = s.players[seat].deck; const cards = [] as unknown as [CardInPlay[], CardInPlay[]];
for (let i = mine.length - 1; i > 0; i--) { const j = Math.floor(rng() * (i + 1)); [mine[i], mine[j]] = [mine[j], mine[i]]; } cards[me] = l.cards[0]; cards[them] = l.cards[1];
return s; 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). */ /** Energy left after queued plays (the engine deducts queued costs at reveal). */
@@ -169,7 +180,9 @@ export function defaultDecks(rules: Ruleset, extra: DeckSpec[] = [], pool: GameC
if (cards) cards = cards.map(repower); if (cards) cards = cards.map(repower);
if (cards && !validateDeck(rules, cards).length) decks.push({ id, tags: tagDeck(cards, tags), payload: cards }); if (cards && !validateDeck(rules, cards).length) decks.push({ id, tags: tagDeck(cards, tags), payload: cards });
}; };
if (seededStarters) for (let i = 0; i < 6; i++) add(`starter-${i}`, starterDeck(`sim-${i}`), ['arch:starter']); // 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('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('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('top-heavy', curveDeck(pool, size, copies, undefined, [0, 1, 1, 2, 2, 3, 3]), ['arch:top-heavy']);
@@ -191,7 +204,7 @@ export interface GameEngineOptions {
extraDecks?: DeckSpec[]; extraDecks?: DeckSpec[];
/** Card pool for archetype decks (one copy per page). Default: the engine's starter pool. */ /** Card pool for archetype decks (one copy per page). Default: the engine's starter pool. */
pool?: GameCard[]; pool?: GameCard[];
/** Include the engine's seeded placeholder starter decks (default true). */ /** Also include the engine's seeded placeholder decks `starterDeck(seed)` (default false). */
seededStarters?: boolean; seededStarters?: boolean;
} }
@@ -199,6 +212,12 @@ export function makeGameEngine(opts: GameEngineOptions = {}): EngineAdapter<Matc
const rulesets = opts.rulesets ?? { base: DEFAULT_RULESET }; const rulesets = opts.rulesets ?? { base: DEFAULT_RULESET };
const deckCache = new Map<string, DeckSpec[]>(); const deckCache = new Map<string, DeckSpec[]>();
const meta = new Map<string, GameCard>(); 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 rules = (id: string) => {
const r = rulesets[id]; const r = rulesets[id];
if (!r) throw new Error(`unknown ruleset ${id}`); if (!r) throw new Error(`unknown ruleset ${id}`);
@@ -209,7 +228,7 @@ export function makeGameEngine(opts: GameEngineOptions = {}): EngineAdapter<Matc
rulesets: () => Object.keys(rulesets), rulesets: () => Object.keys(rulesets),
decks(id) { decks(id) {
if (!deckCache.has(id)) { if (!deckCache.has(id)) {
const d = defaultDecks(rules(id), opts.extraDecks, opts.pool, opts.seededStarters ?? true); 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); for (const deck of d) for (const c of deck.payload as GameCard[]) meta.set(baseId(c.cardId), c);
deckCache.set(id, d); deckCache.set(id, d);
} }
@@ -234,6 +253,8 @@ export function makeGameEngine(opts: GameEngineOptions = {}): EngineAdapter<Matc
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 }; 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, 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) { keywordValues(final, decks) {
const out: { seat: Seat; keyword: string; power: number; flip: number; cards: number }[] = []; const out: { seat: Seat; keyword: string; power: number; flip: number; cards: number }[] = [];
const r0 = final.result; const r0 = final.result;
@@ -257,8 +278,13 @@ export function makeGameEngine(opts: GameEngineOptions = {}): EngineAdapter<Matc
return out; return out;
}, },
actionPower: (s, a) => (a.type === 'play' ? s.players[a.player].hand.find(c => c.cardId === a.cardId)?.power ?? 0 : -1), actionPower: (s, a) => (a.type === 'play' ? s.players[a.player].hand.find(c => c.cardId === a.cardId)?.power ?? 0 : -1),
determinize,
}; };
} }
export const gameEngine = makeGameEngine(); 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);
}
+20 -10
View File
@@ -17,6 +17,11 @@ export function mulberry32(seed: number): Rng {
const pick = <T>(xs: T[], rng: Rng): T => xs[Math.floor(rng() * xs.length)]; 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 { function terminalValue<S, A>(engine: EngineAdapter<S, A>, s: S, seat: Seat): number {
const { winner } = engine.result(s); const { winner } = engine.result(s);
return winner === null ? 0 : winner === seat ? 1 : -1; return winner === null ? 0 : winner === seat ? 1 : -1;
@@ -27,8 +32,8 @@ function value<S, A>(engine: EngineAdapter<S, A>, s: S, seat: Seat): number {
} }
/** Uniformly random legal action. */ /** Uniformly random legal action. */
export function randomBot<S, A>(engine: EngineAdapter<S, A>): BotFn<S, A> { export function randomBot<S, A>(engine: EngineAdapter<S, A>): BotFn<unknown, A> {
return (state, player, rng) => pick(engine.legalActions(state, player), rng); 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 { function greedyChoice<S, A>(engine: EngineAdapter<S, A>, state: S, seat: Seat, actions: A[], rng: Rng): A {
@@ -44,16 +49,20 @@ function greedyChoice<S, A>(engine: EngineAdapter<S, A>, state: S, seat: Seat, a
} }
/** One-ply: take the action whose resulting state evaluates best for us. Ties broken randomly. */ /** One-ply: take the action whose resulting state evaluates best for us. Ties broken randomly. */
export function greedyBot<S, A>(engine: EngineAdapter<S, A>): BotFn<S, A> { export function greedyBot<S, A>(engine: EngineAdapter<S, A>): BotFn<unknown, A> {
return (state, player, rng) => greedyChoice(engine, state, player, engine.legalActions(state, player), rng); 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). * 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. * 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> { export function maxPowerBot<S, A>(engine: EngineAdapter<S, A>): BotFn<unknown, A> {
return (state, player, rng) => { return (obs, player, rng) => {
const state = see(engine, obs, player, rng);
const actions = engine.legalActions(state, player); const actions = engine.legalActions(state, player);
if (!engine.actionPower) return greedyChoice(engine, state, player, actions, rng); if (!engine.actionPower) return greedyChoice(engine, state, player, actions, rng);
let best: A[] = [], bestP = -Infinity; let best: A[] = [], bestP = -Infinity;
@@ -74,9 +83,10 @@ export interface LookaheadOptions { k?: number; rollouts?: number; horizon?: num
* Rollouts run on the true state, so the bot is clairvoyant about hidden info and seeded * 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. * draws: an upper bound on skill, not a fair human-like player.
*/ */
export function lookaheadBot<S, A>(engine: EngineAdapter<S, A>, opts: LookaheadOptions = {}): BotFn<S, A> { 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; const k = opts.k ?? 4, rollouts = opts.rollouts ?? 8, horizon = opts.horizon ?? 40, eps = opts.epsilon ?? 0.25;
return (state, seat, rng) => { return (obs, seat, rng) => {
const state = see(engine, obs, seat, rng);
const actions = engine.legalActions(state, seat); const actions = engine.legalActions(state, seat);
if (actions.length === 1) return actions[0]; if (actions.length === 1) return actions[0];
const shortlist = actions.map(a => { const shortlist = actions.map(a => {
@@ -87,7 +97,7 @@ export function lookaheadBot<S, A>(engine: EngineAdapter<S, A>, opts: LookaheadO
for (const c of shortlist) { for (const c of shortlist) {
let total = 0; let total = 0;
for (let r = 0; r < rollouts; r++) { for (let r = 0; r < rollouts; r++) {
let s = engine.determinize ? engine.applyAction(engine.determinize(state, seat, rng), c.a) : c.next, steps = 0; 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) { while (!engine.isOver(s) && steps < horizon) {
const who = engine.toAct(s); const who = engine.toAct(s);
const legal = engine.legalActions(s, who); const legal = engine.legalActions(s, who);
@@ -108,7 +118,7 @@ export function lookaheadBot<S, A>(engine: EngineAdapter<S, A>, opts: LookaheadO
export const BOT_NAMES = ['random', 'maxpower', 'greedy', 'lookahead-lite', 'lookahead'] as const; export const BOT_NAMES = ['random', 'maxpower', 'greedy', 'lookahead-lite', 'lookahead'] as const;
export type BotName = typeof BOT_NAMES[number]; export type BotName = typeof BOT_NAMES[number];
export function makeBot<S, A>(name: string, engine: EngineAdapter<S, A>): BotFn<S, A> { export function makeBot<S, A>(name: string, engine: EngineAdapter<S, A>): BotFn<unknown, A> {
switch (name) { switch (name) {
case 'random': return randomBot(engine); case 'random': return randomBot(engine);
case 'maxpower': return maxPowerBot(engine); case 'maxpower': return maxPowerBot(engine);
+6 -4
View File
@@ -52,12 +52,14 @@ export interface EngineAdapter<S = unknown, A = unknown> {
keywordValues?(final: S, decks: [DeckSpec, DeckSpec]): { seat: Seat; keyword: string; power: number; flip: number; cards: number }[]; 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). */ /** Seat with the first-player advantage (defaults to toAct at match start). */
firstSeat?(state: S): Seat; firstSeat?(state: S): Seat;
/** Resample information hidden from `seat` (opponent hand/staged plays, deck order) before searching. */ /** What `seat` may see (e.g. shared/game viewFor). Bots receive only this. Default: the state itself. */
determinize?(state: S, seat: Seat, rng: Rng): S; 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 the state it sees. ui-b can reuse it as the browser AI. */ /** 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<S = unknown, A = unknown> = (state: S, player: Seat, rng: Rng) => A; export type BotFn<O = unknown, A = unknown> = (observation: O, player: Seat, rng: Rng) => A;
export interface MatchRecord { export interface MatchRecord {
ruleset: string; ruleset: string;
+1 -1
View File
@@ -41,7 +41,7 @@ test('bots only return legal actions on shared/game', { skip: !existsSync(new UR
let steps = 0; let steps = 0;
while (!engine.isOver(s) && steps++ < 500) { while (!engine.isOver(s) && steps++ < 500) {
const seat = engine.toAct(s); const seat = engine.toAct(s);
const a = bot(s, seat, rng); 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)}`); 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); s = engine.applyAction(s, a);
} }