Files
wikideck/shared/duel/engine.ts
T
claudeanderic dbb89ce9c5 Night 2: 40-card Magic-style duel, PvP with owned decks, polite Wikimedia client, Android mining (#23)
Night 2 (2026-11-17), from the `claude/wikideck` fork's `night/2026-11-17` branch. It follows Night 1 (#22).

## What's in it
- **Duel engine** (fork #72, #80): 40-card decks of cards you own, Notability/Citations, keywords, effects T1–T12, Connected, a hidden-information-safe `viewFor`/`logFor`, and replay. Balance v1 tuning (#84) gives the first player about 51%.
- **Card profiles** (#70, #82): Figure, Location, Event, Institution or Doctrine, plus stats, keywords and rules text, all derived from real article data. Templates only.
- **Design and story** (#66, #69, #83): DUEL_DESIGN.md, plus the match log and the encyclopedic "Battle of X (2026)" recap.
- **PvP** (#74, #77, #81, #76, #85):
  - The server checks ownership, and 40-card eligibility is enforced.
  - Modes: Classic (ranked), Draft and Trending.
  - Invites, quick match, Elo, a ladder and recap pages. Online matches render on the duel board.
- **Duel board UI** (#79): MTG-style card faces and combat declaration, built for 360 px first.
- **Polite Wikimedia client** (#73, #75): throttled, cached and identified requests, the mint-path fix, and a prefetch pool.
- **Android mining** (#78): native RandomX, as a sideload build. The emulator mined a testnet block.
- **Testnet ops** (#67, #68).

PR numbers refer to `claude/wikideck`.

## Status
- **Tests:** 423, of which 422 pass, 0 fail and 1 is skipped. The build is OK (`node:24-alpine`, `--network none`).
- **Testnet:** running this commit (036489c) on r350.
- **Untouched:** no changes to `server/testnet/consensus.ts`, `randomx.ts`, `native/` or the mainnet compose.
- **Review:** night-review reviewed fork #66–#79. #80–#85 came from the agents' unfinished branches and were not reviewed.
- **Known gaps:**
  - The PvP end-to-end test hasn't been run (it needs two eom.dev accounts).
  - Bot matches aren't reachable from Play.
  - Card identity pre-bake hasn't been done.
  - The RandomX verifier latch (`server/testnet/randomx.ts:140`) is still open.

This PR is for Eric to merge.

🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: #23

Co-authored-by: Claude <claude@eom.dev>
2026-11-18 18:12:24 +00:00

909 lines
43 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* WikiDeck Duel engine (off-chain, pure, deterministic). Spec: docs/game/DUEL_API.md.
* No stack, sorcery speed only, atomic actions, clone-on-apply.
*/
import { Rng } from '../game/rng.ts';
import { DEFAULT_DUEL_RULESET, parseDuelRuleset } from './ruleset.ts';
import type {
CardInstance, CardRef, ConnectedTier, DuelAction, DuelCard, DuelResult, DuelRuleset, DuelState, EffectSpec, EndReason,
Keyword, LogEvent, Permanent, PermanentView, PlayerState, PlayerView, Seat, SideView, TargetRef, TargetSpec,
} from './types.ts';
import { CARD_TYPES, KEYWORDS } from './types.ts';
type LogBody = LogEvent extends infer E ? (E extends LogEvent ? Omit<E, 'seq' | 'turn'> : never) : never;
type Source = Permanent | CardInstance;
const other = (seat: Seat): Seat => (seat === 0 ? 1 : 0);
const pw = (card: DuelCard) => card.power ?? 0;
const tg = (card: DuelCard) => card.toughness ?? 0;
const CHOSEN: ReadonlySet<TargetSpec> = new Set(['figure', 'figureOrLocation', 'ownFigure', 'opponentFigure', 'anyTarget']);
const NO_KIN = new Set(['Q5', 'Q16521']);
const MAX_COMBOS = 64;
function targetOf(e: EffectSpec): TargetSpec {
if (e.target) return e.target;
switch (e.op) {
case 'damage': return 'anyTarget';
case 'damageEach': return 'each';
case 'pump': return 'self';
case 'drain': return 'opponent';
case 'attach': return 'ownFigure';
case 'fight': return 'opponentFigure';
case 'destroy': case 'bounce': case 'tap': return 'opponentFigure';
default: return 'controller';
}
}
const isEntry = (e: EffectSpec) => e.trigger === 'onPlay' || e.trigger === 'onEnter';
// ---------------------------------------------------------------------------
// Decks
// ---------------------------------------------------------------------------
export function validateDeck(rules: DuelRuleset, cards: DuelCard[]): void {
if (!Array.isArray(cards)) throw new TypeError('Deck must be an array');
if (cards.length !== rules.deckSize) throw new RangeError(`Deck must have exactly ${rules.deckSize} cards (has ${cards.length})`);
const ids = new Set<string>();
const pages = new Map<number, number>();
for (const card of cards) {
if (!card || typeof card.cardId !== 'string' || !card.cardId) throw new TypeError('Card needs a cardId');
if (card.token) throw new RangeError(`Tokens can't be in decks (${card.cardId})`);
if (ids.has(card.cardId)) throw new RangeError(`Duplicate card ${card.cardId}`);
ids.add(card.cardId);
if (card.pageId !== null) {
const n = (pages.get(card.pageId) ?? 0) + 1;
if (n > rules.maxCopiesPerPage) throw new RangeError(`More than ${rules.maxCopiesPerPage} copies of page ${card.pageId}`);
pages.set(card.pageId, n);
}
if (!CARD_TYPES.includes(card.type)) throw new RangeError(`Bad card type ${card.type}`);
if (!Number.isInteger(card.cost) || card.cost < 0 || card.cost > 20) throw new RangeError(`Bad cost on ${card.cardId}`);
for (const n of [pw(card), tg(card)]) if (!Number.isInteger(n) || n < 0 || n > 50) throw new RangeError(`Bad stats on ${card.cardId}`);
if (card.type === 'Figure' && tg(card) < 1) throw new RangeError(`Figure ${card.cardId} needs toughness ≥ 1`);
if (!Array.isArray(card.keywords)) throw new TypeError(`Bad keywords on ${card.cardId}`);
// Trending is granted by the host at match start (applyLive) and doesn't count toward the limit.
if (card.keywords.filter(k => k !== 'Trending').length > rules.maxKeywords) throw new RangeError(`Too many keywords on ${card.cardId}`);
for (const k of card.keywords) if (!KEYWORDS.includes(k)) throw new RangeError(`Unknown keyword ${k}`);
if (!Array.isArray(card.effects) || card.effects.length > 4) throw new RangeError(`Bad effects on ${card.cardId}`);
if (card.territory !== undefined && (!Number.isInteger(card.territory) || card.territory < 0 || card.territory > 5)) throw new RangeError(`Bad territory on ${card.cardId}`);
}
}
// ---------------------------------------------------------------------------
// Creation
// ---------------------------------------------------------------------------
function emptyPlayer(rules: DuelRuleset, library: CardInstance[]): PlayerState {
return {
life: rules.startingLife, citations: 0, baseCitations: 0, library, hand: [], graveyard: [], mulligansTaken: 0, ready: false,
locationsThisTurn: 0, bankSeconds: rules.bankSeconds, timeouts: 0, fatigue: 0,
};
}
export function createDuel(rules: DuelRuleset, decks: [DuelCard[], DuelCard[]], seed: string): DuelState {
const r = parseDuelRuleset(rules);
const rng = Rng.fromSeed(seed);
const firstSeat = rng.int(2) as Seat;
const players = ([0, 1] as Seat[]).map(seat => {
const instances = decks[seat].map((card, i) => ({ uid: `${seat}:${i}`, owner: seat, card: structuredClone(card) }));
return emptyPlayer(r, rng.shuffle(instances));
}) as [PlayerState, PlayerState];
const state: DuelState = {
engine: 'duel', rules: r, seed, rng: rng.state, turn: 0, active: firstSeat, firstSeat, phase: 'mulligan',
players, battlefield: [], combat: { attackers: [], blocks: {} }, log: [], result: null, version: 0, nextToken: 0, nextEntry: 0,
};
log(state, { kind: 'start', firstSeat });
for (const p of state.players) p.hand = p.library.splice(0, r.openingHand);
return state;
}
// ---------------------------------------------------------------------------
// Queries
// ---------------------------------------------------------------------------
export function toAct(state: DuelState): Seat | null {
if (state.result) return null;
if (state.phase === 'mulligan') {
for (const seat of [0, 1] as Seat[]) if (!state.players[seat].ready) return seat;
return null;
}
return state.phase === 'block' ? other(state.active) : state.active;
}
export const isOver = (state: DuelState) => state.result !== null;
export const result = (state: DuelState): DuelResult | null => state.result;
export const turnOf = (state: DuelState) => state.turn;
const find = (state: DuelState, uid: string) => state.battlefield.find(p => p.uid === uid);
export function maxCitations(state: DuelState, seat: Seat): number {
const territory = state.battlefield.filter(p => p.controller === seat && p.card.type === 'Location').reduce((n, p) => n + (p.card.territory ?? 0), 0);
return state.players[seat].baseCitations + Math.min(state.rules.territoryCap, territory);
}
/** Connected tier between two cards (DUEL_DESIGN §6), best tier first, limited to rules.connectedTiers. */
export function tierBetween(rules: DuelRuleset, a: DuelCard, b: DuelCard): { tier: ConnectedTier; via: string } | null {
const ca = a.connect, cb = b.connect;
if (!ca || !cb) return null;
const on = (t: ConnectedTier) => rules.connectedTiers.includes(t);
const linked = (b.pageId !== null && ca.links.includes(b.pageId)) || (a.pageId !== null && cb.links.includes(a.pageId));
const cited = (!!cb.qid && !!ca.cites?.includes(cb.qid)) || (!!ca.qid && !!cb.cites?.includes(ca.qid));
if (on('Linked') && (linked || cited)) return { tier: 'Linked', via: cited ? 'claim' : 'link' };
if (on('Compatriot')) { const c = ca.countries.find(x => cb.countries.includes(x)); if (c !== undefined) return { tier: 'Compatriot', via: `country: ${c}` }; }
if (on('Contemporary') && a.type !== b.type) { const c = ca.centuries.find(x => cb.centuries.includes(x)); if (c !== undefined) return { tier: 'Contemporary', via: `century: ${c}` }; }
if (on('Kin')) { const c = ca.p31.find(x => !NO_KIN.has(x) && cb.p31.includes(x)); if (c !== undefined) return { tier: 'Kin', via: `instance of: ${c}` }; }
return null;
}
function connectionOf(state: DuelState, perm: Permanent): { with: Permanent; tier: ConnectedTier; via: string; bonus: number } | null {
if (perm.card.type !== 'Figure' || !perm.card.connect) return null;
let best: { with: Permanent; tier: ConnectedTier; via: string; bonus: number } | null = null;
for (const mate of state.battlefield) {
if (mate.uid === perm.uid || mate.controller !== perm.controller) continue;
const t = tierBetween(state.rules, perm.card, mate.card);
if (!t) continue;
const bonus = t.tier === 'Linked' ? state.rules.linkedBonus : state.rules.connectedBonus;
if (!best || bonus > best.bonus) best = { with: mate, tier: t.tier, via: t.via, bonus };
}
return best;
}
/** Does a static effect of `src` apply to `perm`? Conditions use printed power (no feedback). */
function staticApplies(state: DuelState, src: Permanent, e: EffectSpec, perm: Permanent): boolean {
const fig = perm.card.type === 'Figure';
const t = targetOf(e);
const hit = t === 'attached' ? src.attachedTo === perm.uid
: t === 'self' ? src.uid === perm.uid
: t === 'ownFigures' ? fig && perm.controller === src.controller
: t === 'opponentFigures' ? fig && perm.controller !== src.controller
: t === 'each' ? fig || perm.card.type === 'Location' : false;
if (!hit) return false;
const c = e.condition;
if (!c) return true;
if (c.maxPower !== undefined && pw(perm.card) > c.maxPower) return false;
if (c.samePortal) {
const anchorUid = src.card.type === 'Doctrine' ? src.attachedTo : src.uid;
const anchor = anchorUid ? find(state, anchorUid) : undefined;
if (!anchor || perm.uid === anchor.uid || perm.card.portal !== anchor.card.portal) return false;
}
if (c.connected && !tierBetween(state.rules, perm.card, src.card)) return false;
return true;
}
function statics(state: DuelState, perm: Permanent): { p: number; t: number; grants: Keyword[] } {
let p = 0, t = 0;
const grants: Keyword[] = [];
for (const src of state.battlefield) {
for (const e of src.card.effects) {
if (e.trigger !== 'static' || !staticApplies(state, src, e, perm)) continue;
if (e.op === 'pump') { p += e.power ?? e.amount ?? 0; t += e.toughness ?? e.amount ?? 0; }
if (e.grant) grants.push(...e.grant);
}
}
return { p, t, grants };
}
export function keywordsOf(state: DuelState, perm: Permanent): Keyword[] {
const out = new Set<Keyword>([...perm.card.keywords, ...perm.permKeywords, ...perm.tempKeywords, ...statics(state, perm).grants]);
return KEYWORDS.filter(k => out.has(k));
}
const hasKw = (state: DuelState, perm: Permanent, k: Keyword) => keywordsOf(state, perm).includes(k);
export function statsOfPermanent(state: DuelState, perm: Permanent): { power: number; toughness: number } {
if (perm.card.type === 'Location') {
return { power: Math.max(0, perm.tempPower), toughness: tg(perm.card) > 0 ? tg(perm.card) + perm.tempToughness : 0 };
}
if (perm.card.type !== 'Figure') return { power: 0, toughness: 0 };
const s = statics(state, perm);
const c = connectionOf(state, perm)?.bonus ?? 0;
const kws = new Set([...perm.card.keywords, ...perm.permKeywords, ...perm.tempKeywords, ...s.grants]);
let local = 0;
if (kws.has('Local') && perm.card.connect?.countries.length) {
const mine = perm.card.connect.countries;
if (state.battlefield.some(l => l.controller === perm.controller && l.card.type === 'Location' && l.card.connect?.countries.some(x => mine.includes(x)))) local = 1;
}
const trend = kws.has('Trending') ? state.rules.trendingPower : 0;
const extra = perm.counters + c + local;
return {
power: Math.max(0, pw(perm.card) + extra + perm.permPower + perm.tempPower + s.p + trend),
toughness: tg(perm.card) + extra + perm.permToughness + perm.tempToughness + s.t,
};
}
export function statsOf(state: DuelState, uid: string): { power: number; toughness: number } {
const perm = find(state, uid);
if (!perm) throw new RangeError(`No permanent ${uid}`);
return statsOfPermanent(state, perm);
}
/** Figures, and Locations with a Garrison, can block and can be destroyed by damage. */
const isBody = (perm: Permanent) => perm.card.type === 'Figure' || (perm.card.type === 'Location' && tg(perm.card) > 0);
function canBlock(state: DuelState, blocker: Permanent, attacker: Permanent): boolean {
const ka = keywordsOf(state, attacker);
const kb = blocker.card.type === 'Figure' ? keywordsOf(state, blocker) : [];
if (ka.includes('Featured') && !kb.some(k => k === 'Featured' || k === 'Translated' || k === 'Multilingual')) return false;
if (ka.includes('Multilingual') && kb.includes('Local')) return false;
return true;
}
function candidates(state: DuelState, seat: Seat, card: DuelCard, e: EffectSpec): TargetRef[] {
const t = targetOf(e);
const out: TargetRef[] = [];
const shielded = (p: Permanent) => p.controller !== seat && (card.type === 'Event' || card.type === 'Doctrine') && hasKw(state, p, 'Protected');
for (const p of state.battlefield) {
const fig = p.card.type === 'Figure';
const ok = t === 'figure' ? fig
: t === 'figureOrLocation' || t === 'anyTarget' ? fig || (p.card.type === 'Location' && tg(p.card) > 0)
: t === 'ownFigure' ? fig && p.controller === seat
: t === 'opponentFigure' ? fig && p.controller !== seat : false;
if (!ok || shielded(p)) continue;
if (e.condition?.maxPower !== undefined && pw(p.card) > e.condition.maxPower) continue;
out.push({ kind: 'card', uid: p.uid });
}
if (t === 'anyTarget') out.push({ kind: 'player', seat: other(seat) }, { kind: 'player', seat });
return out;
}
/** All target combinations for playing `card` now (capped), [] if it can't be played, [[]] if it needs none. */
function targetCombos(state: DuelState, seat: Seat, card: DuelCard): TargetRef[][] {
const chosen = card.effects.filter(e => isEntry(e) && CHOSEN.has(targetOf(e)));
if (!chosen.length) return [[]];
const lists = chosen.map(e => candidates(state, seat, card, e));
const permanent = card.type !== 'Event' && card.type !== 'Doctrine';
if (lists.some(l => !l.length)) return permanent ? [[]] : [];
let combos: TargetRef[][] = [[]];
for (const list of lists) {
const next: TargetRef[][] = [];
for (const c of combos) for (const t of list) {
if (t.kind === 'card' && c.some(x => x.kind === 'card' && x.uid === t.uid)) continue;
if (next.length < MAX_COMBOS) next.push([...c, t]);
}
combos = next;
}
return combos.length ? combos : permanent ? [[]] : [];
}
export function legalActions(state: DuelState, seat: Seat): DuelAction[] {
if (toAct(state) !== seat) return [];
const p = state.players[seat];
switch (state.phase) {
case 'mulligan':
return p.mulligansTaken < state.rules.mulligans ? [{ type: 'keep' }, { type: 'mulligan' }] : [{ type: 'keep' }];
case 'main': {
const out: DuelAction[] = [];
for (const inst of p.hand) {
if (inst.card.cost > p.citations) continue;
if (inst.card.type === 'Location' && p.locationsThisTurn >= state.rules.locationsPerTurn) continue;
for (const targets of targetCombos(state, seat, inst.card)) {
out.push(targets.length ? { type: 'play', uid: inst.uid, targets } : { type: 'play', uid: inst.uid });
}
}
out.push({ type: 'endPhase' });
return out;
}
case 'attack': {
const out: DuelAction[] = [];
for (const perm of state.battlefield) {
if (perm.controller !== seat || perm.card.type !== 'Figure' || perm.tapped || state.combat.attackers.includes(perm.uid)) continue;
if (perm.sick && !hasKw(state, perm, 'Trending')) continue;
out.push({ type: 'toggleAttacker', uid: perm.uid });
}
out.push({ type: 'confirmAttack' });
return out;
}
case 'block':
return [...blockOptions(state), { type: 'confirmBlocks' }];
default:
return [];
}
}
function blockOptions(state: DuelState): DuelAction[] {
const defender = other(state.active);
const out: DuelAction[] = [];
const blocked = new Set(Object.values(state.combat.blocks));
for (const b of state.battlefield) {
if (b.controller !== defender || b.tapped || !isBody(b) || state.combat.blocks[b.uid]) continue;
for (const aUid of state.combat.attackers) {
if (blocked.has(aUid)) continue;
const a = find(state, aUid);
if (a && canBlock(state, b, a)) out.push({ type: 'block', blocker: b.uid, attacker: aUid });
}
}
return out;
}
// ---------------------------------------------------------------------------
// Mutation helpers (operate on a private clone)
// ---------------------------------------------------------------------------
function log(state: DuelState, body: LogBody): void {
state.log.push({ seq: state.log.length, turn: state.turn, ...body } as LogEvent);
}
function ref(state: DuelState, inst: Source): CardRef {
const out: CardRef = { uid: inst.uid, cardId: inst.card.cardId, title: inst.card.title, pageId: inst.card.pageId, type: inst.card.type };
const perm = find(state, inst.uid);
if (perm && isBody(perm)) Object.assign(out, statsOfPermanent(state, perm));
return out;
}
const life = (state: DuelState): [number, number] => [state.players[0].life, state.players[1].life];
function finish(state: DuelState, winner: Seat | null, reason: EndReason): void {
if (state.result) return;
state.result = { winner, reason };
state.phase = 'over';
log(state, { kind: 'gameOver', winner, reason, life: life(state) });
}
function draw(state: DuelState, seat: Seat, n: number): void {
const p = state.players[seat];
for (let i = 0; i < n && !state.result; i++) {
if (!p.library.length) {
const mode = state.rules.libraryEmpty;
if (mode === 'reshuffle' && p.graveyard.length) {
const rng = new Rng(state.rng);
p.library = rng.shuffle(p.graveyard);
p.graveyard = [];
state.rng = rng.state;
} else if (mode === 'fatigue') {
p.fatigue += 1;
log(state, { kind: 'fatigue', seat, amount: p.fatigue });
loseLife(state, seat, p.fatigue, null, false);
continue;
} else {
finish(state, other(seat), 'library');
return;
}
}
const inst = p.library.shift()!;
p.hand.push(inst);
log(state, { kind: 'draw', seat, card: ref(state, inst) });
}
}
function loseLife(state: DuelState, seat: Seat, amount: number, source: Source | null, combat: boolean): void {
if (amount <= 0) return;
const p = state.players[seat];
p.life -= amount;
log(state, { kind: 'playerDamage', source: source ? ref(state, source) : null, seat, amount, life: p.life, combat });
}
function gainLife(state: DuelState, seat: Seat, amount: number, source: Source): void {
if (amount <= 0) return;
const p = state.players[seat];
p.life += amount;
log(state, { kind: 'lifeGain', source: ref(state, source), seat, amount, life: p.life });
}
/** Returns damage actually dealt. */
function dealDamage(state: DuelState, source: Source, target: TargetRef, amount: number, combat: boolean): number {
if (amount <= 0) return 0;
if (target.kind === 'player') { loseLife(state, target.seat, amount, source, combat); return amount; }
const perm = find(state, target.uid);
if (!perm || !isBody(perm)) return 0;
let dmg = amount;
if (!perm.shielded && hasKw(state, perm, 'Well-sourced')) { perm.shielded = true; dmg -= 1; }
if (dmg <= 0) return 0;
perm.damage += dmg;
log(state, { kind: combat ? 'combatDamage' : 'effectDamage', source: ref(state, source), target: ref(state, perm), amount: dmg });
return dmg;
}
function leave(state: DuelState, uid: string): Permanent | null {
const i = state.battlefield.findIndex(p => p.uid === uid);
if (i < 0) return null;
const [perm] = state.battlefield.splice(i, 1);
delete state.combat.blocks[uid];
for (const [b, a] of Object.entries(state.combat.blocks)) if (a === uid) delete state.combat.blocks[b];
state.combat.attackers = state.combat.attackers.filter(a => a !== uid);
return perm;
}
const toInstance = (perm: Permanent): CardInstance => ({ uid: perm.uid, owner: perm.owner, card: perm.card });
/** Destroy a set of permanents at once, then fire their triggers (active player's first, then entry order). */
function destroyAll(state: DuelState, uids: string[]): void {
const gone: Permanent[] = [];
for (const uid of uids) {
const perm = find(state, uid);
if (!perm) continue;
const card = ref(state, perm);
leave(state, uid);
if (!perm.card.token) state.players[perm.owner].graveyard.push(toInstance(perm));
log(state, { kind: 'destroyed', card, owner: perm.owner });
gone.push(perm);
}
gone.sort((a, b) => Number(a.controller !== state.active) - Number(b.controller !== state.active) || a.entered - b.entered);
for (const perm of gone) {
if (state.result) return;
for (const e of perm.card.effects) if (e.trigger === 'onDestroyed') resolveEffect(state, perm, perm.controller, e, undefined, undefined);
if (perm.card.keywords.includes('Legacy') || perm.permKeywords.includes('Legacy')) draw(state, perm.controller, 1);
}
}
function bounce(state: DuelState, uid: string): void {
const perm = find(state, uid);
if (!perm) return;
const card = ref(state, perm);
leave(state, uid);
if (!perm.card.token) state.players[perm.owner].hand.push(toInstance(perm));
log(state, { kind: 'bounced', card, owner: perm.owner });
}
/** State-based checks to a fixpoint: lethal damage, orphaned Doctrines, life totals; then Connected logging. */
function settle(state: DuelState): void {
for (let guard = 0; guard < 100 && !state.result; guard++) {
const dead = state.battlefield.filter(p => {
if (p.card.type === 'Doctrine') return !p.attachedTo || !find(state, p.attachedTo);
if (!isBody(p)) return false;
const { toughness } = statsOfPermanent(state, p);
return toughness <= 0 || p.damage >= toughness;
}).map(p => p.uid);
if (!dead.length) break;
destroyAll(state, dead);
}
if (state.result) return;
const lost = ([0, 1] as Seat[]).filter(s => state.players[s].life <= 0);
if (lost.length === 2) finish(state, null, 'life');
else if (lost.length === 1) finish(state, other(lost[0]), 'life');
if (!state.result) logConnections(state);
}
function logConnections(state: DuelState): void {
for (const perm of state.battlefield) {
if (perm.connectedLogged) continue;
const c = connectionOf(state, perm);
if (!c) continue;
perm.connectedLogged = true;
log(state, { kind: 'connected', seat: perm.controller, card: ref(state, perm), with: ref(state, c.with), tier: c.tier, via: c.via, bonus: c.bonus });
}
}
/** Rivalry (log only): when a card enters, note its best Connected tie to an opposing permanent, once. */
function logRivalry(state: DuelState, perm: Permanent): void {
let best: { with: Permanent; tier: ConnectedTier; via: string } | null = null;
for (const o of state.battlefield) {
if (o.controller === perm.controller) continue;
const t = tierBetween(state.rules, perm.card, o.card);
if (t && (!best || state.rules.connectedTiers.indexOf(t.tier) < state.rules.connectedTiers.indexOf(best.tier))) best = { with: o, ...t };
}
if (best) log(state, { kind: 'rivalry', card: ref(state, perm), with: ref(state, best.with), tier: best.tier, via: best.via });
}
function autoTargets(state: DuelState, source: Source, seat: Seat, t: TargetSpec): TargetRef[] {
const cards = (pred: (p: Permanent) => boolean) => state.battlefield.filter(pred).map(p => ({ kind: 'card', uid: p.uid }) as TargetRef);
switch (t) {
case 'controller': return [{ kind: 'player', seat }];
case 'opponent': return [{ kind: 'player', seat: other(seat) }];
case 'self': return find(state, source.uid) ? [{ kind: 'card', uid: source.uid }] : [];
case 'attached': {
const at = find(state, source.uid)?.attachedTo;
return at && find(state, at) ? [{ kind: 'card', uid: at }] : [];
}
case 'each': return cards(p => p.card.type === 'Figure' || p.card.type === 'Location');
case 'ownFigures': return cards(p => p.card.type === 'Figure' && p.controller === seat);
case 'opponentFigures': return cards(p => p.card.type === 'Figure' && p.controller !== seat);
default: return [];
}
}
function makeToken(state: DuelState, seat: Seat, source: Source, e: EffectSpec): void {
const spec = e.token;
if (!spec) return;
const n = e.amount ?? 1;
for (let i = 0; i < n; i++) {
if (e.condition?.maxTokens !== undefined) {
const count = state.battlefield.filter(p => p.controller === seat && p.card.token).length;
if (count >= e.condition.maxTokens) return;
}
const id = state.nextToken++;
const card: DuelCard = {
cardId: `token:${id}`, pageId: null, title: spec.name, type: 'Figure', portal: spec.portal, cost: 0,
power: spec.power, toughness: spec.toughness, keywords: [], effects: [], rulesText: '', flavor: '', token: true,
};
const perm = enter(state, { uid: `t:${id}`, owner: seat, card }, seat);
log(state, { kind: 'tokenCreated', seat, card: ref(state, perm), source: ref(state, source) });
}
}
/** Resolve one effect. `chosen` is this effect's target (chosen effects); `prev` the previous chosen target (fight). */
function resolveEffect(state: DuelState, source: Source, seat: Seat, e: EffectSpec, chosen: TargetRef | undefined, prev: TargetRef | undefined): void {
if (state.result || e.trigger === 'static') return;
const t = targetOf(e);
let targets: TargetRef[];
if (CHOSEN.has(t)) {
if (!chosen) return; // fizzles (no target, or chosen targets in automatic triggers)
const still = chosen.kind === 'player' ? t === 'anyTarget'
: candidates(state, seat, source.card, e).some(x => x.kind === 'card' && x.uid === chosen.uid);
if (!still) return;
targets = [chosen];
} else {
targets = autoTargets(state, source, seat, t);
}
const needs = !['draw', 'gainLife', 'createToken'].includes(e.op);
if (needs && !targets.length) return;
log(state, { kind: 'effect', seat, source: ref(state, source), op: e.op, ...(e.template ? { template: e.template } : {}), targets });
const amount = e.amount ?? 0;
const permOf = (x: TargetRef) => (x.kind === 'card' ? find(state, x.uid) : undefined);
switch (e.op) {
case 'damage': case 'damageEach':
for (const x of targets) dealDamage(state, source, x, amount, false);
break;
case 'createToken': makeToken(state, seat, source, e); break;
case 'pump': {
const p = e.power ?? amount, q = e.toughness ?? amount;
for (const x of targets) {
const perm = permOf(x);
if (!perm) continue;
if (e.duration === 'permanent') { perm.permPower += p; perm.permToughness += q; if (e.grant) perm.permKeywords.push(...e.grant); }
else { perm.tempPower += p; perm.tempToughness += q; if (e.grant) perm.tempKeywords.push(...e.grant); }
}
break;
}
case 'fight': {
const a = prev?.kind === 'card' ? find(state, prev.uid) : find(state, source.uid);
const b = permOf(targets[0]);
if (!a || !b || a.uid === b.uid) break;
const [ap, bp] = [statsOfPermanent(state, a).power, statsOfPermanent(state, b).power];
dealDamage(state, a, { kind: 'card', uid: b.uid }, ap, false);
dealDamage(state, b, { kind: 'card', uid: a.uid }, bp, false);
break;
}
case 'draw': draw(state, t === 'opponent' ? other(seat) : seat, e.amount ?? 1); break;
case 'attach': {
const perm = find(state, source.uid);
const to = permOf(targets[0]);
if (perm && to) { perm.attachedTo = to.uid; log(state, { kind: 'adopt', seat, card: ref(state, perm), to: ref(state, to) }); }
break;
}
case 'gainLife': gainLife(state, seat, amount, source); break;
case 'drain':
for (const x of targets) {
const victim = x.kind === 'player' ? x.seat : permOf(x)?.controller;
if (victim === undefined) continue;
loseLife(state, victim, amount, source, false);
if (victim !== seat) gainLife(state, seat, amount, source);
}
break;
case 'destroy': destroyAll(state, targets.filter(x => x.kind === 'card').map(x => (x as { uid: string }).uid)); break;
case 'bounce': for (const x of targets) if (x.kind === 'card') bounce(state, x.uid); break;
case 'tap': for (const x of targets) { const perm = permOf(x); if (perm) perm.tapped = true; } break;
}
}
function enter(state: DuelState, inst: CardInstance, seat: Seat): Permanent {
const perm: Permanent = {
...inst, controller: seat, tapped: false, sick: true, damage: 0, counters: 0, permPower: 0, permToughness: 0,
tempPower: 0, tempToughness: 0, tempKeywords: [], permKeywords: [], shielded: false, entered: state.nextEntry++, connectedLogged: false,
};
state.battlefield.push(perm);
return perm;
}
/** Run a card's entry effects, feeding chosen targets in order. */
function runEntry(state: DuelState, source: Source, seat: Seat, targets: TargetRef[]): void {
let i = 0;
let prev: TargetRef | undefined;
for (const e of source.card.effects) {
if (!isEntry(e) || state.result) continue;
if (CHOSEN.has(targetOf(e))) {
const chosen = targets[i++];
resolveEffect(state, source, seat, e, chosen, prev);
prev = chosen;
} else {
resolveEffect(state, source, seat, e, undefined, prev);
}
}
}
// ---------------------------------------------------------------------------
// Turn structure
// ---------------------------------------------------------------------------
function totalPower(state: DuelState, seat: Seat): number {
return state.battlefield.filter(p => p.controller === seat && p.card.type === 'Figure').reduce((n, p) => n + statsOfPermanent(state, p).power, 0);
}
function startTurn(state: DuelState, seat: Seat): void {
if (state.rules.turnCap !== null && state.turn >= state.rules.turnCap) {
const [a, b] = life(state);
const [pa, pb] = [totalPower(state, 0), totalPower(state, 1)];
const winner: Seat = a !== b ? (a > b ? 0 : 1) : pa !== pb ? (pa > pb ? 0 : 1) : other(state.firstSeat);
finish(state, winner, 'turnCap');
return;
}
state.turn += 1;
state.active = seat;
state.phase = 'main';
state.combat = { attackers: [], blocks: {} };
const p = state.players[seat];
p.locationsThisTurn = 0;
p.baseCitations = Math.min(state.rules.maxCitations, p.baseCitations + state.rules.citationsPerTurn);
p.citations = maxCitations(state, seat);
if (state.turn === 2 && seat !== state.firstSeat) p.citations += state.rules.secondPlayerCitations;
for (const perm of state.battlefield) {
perm.shielded = false;
if (perm.controller === seat) { perm.tapped = false; perm.sick = false; }
}
log(state, { kind: 'turnStart', seat, citations: p.citations, life: life(state) });
const mine = state.battlefield.filter(x => x.controller === seat).sort((a, b) => a.entered - b.entered);
for (const perm of mine) {
if (!find(state, perm.uid) || state.result) continue;
if (perm.card.keywords.includes('Stub') && perm.counters < state.rules.stubMax) perm.counters += 1;
for (const e of perm.card.effects) if (e.trigger === 'startOfTurn' && find(state, perm.uid)) resolveEffect(state, perm, seat, e, undefined, undefined);
}
settle(state);
if (state.result) return;
if (!(state.turn === 1 && !state.rules.firstPlayerDraws)) draw(state, seat, 1);
settle(state);
}
function endTurn(state: DuelState): void {
for (const perm of state.battlefield) { perm.damage = 0; perm.tempPower = 0; perm.tempToughness = 0; perm.tempKeywords = []; }
state.combat = { attackers: [], blocks: {} };
const seat = state.active;
const p = state.players[seat];
while (p.hand.length > state.rules.handSize) {
let worst = p.hand.length - 1;
for (let i = p.hand.length - 1; i >= 0; i--) if (p.hand[i].card.cost > p.hand[worst].card.cost) worst = i;
const [inst] = p.hand.splice(worst, 1);
p.graveyard.push(inst);
log(state, { kind: 'discard', seat, card: ref(state, inst) });
}
settle(state);
if (!state.result) startTurn(state, other(seat));
}
function play(state: DuelState, seat: Seat, uid: string, targets: TargetRef[]): void {
const p = state.players[seat];
const [inst] = p.hand.splice(p.hand.findIndex(c => c.uid === uid), 1);
p.citations -= inst.card.cost;
if (inst.card.type === 'Event') {
log(state, { kind: 'cast', seat, card: ref(state, inst), targets });
runEntry(state, inst, seat, targets);
p.graveyard.push(inst);
settle(state);
return;
}
if (inst.card.type === 'Location') p.locationsThisTurn += 1;
const perm = enter(state, inst, seat);
if (inst.card.type !== 'Doctrine') log(state, { kind: 'deploy', seat, card: ref(state, perm) });
logRivalry(state, perm);
runEntry(state, perm, seat, targets);
settle(state);
}
function confirmAttack(state: DuelState): void {
const seat = state.active;
if (!state.combat.attackers.length) { endTurn(state); return; }
const attackers = state.combat.attackers.map(uid => find(state, uid)).filter((x): x is Permanent => !!x);
for (const a of attackers) a.tapped = true;
log(state, { kind: 'attack', seat, attackers: attackers.map(a => ref(state, a)) });
for (const a of attackers) for (const e of a.card.effects) if (e.trigger === 'onAttack' && find(state, a.uid)) resolveEffect(state, a, seat, e, undefined, undefined);
settle(state);
if (state.result) return;
if (!state.combat.attackers.length) { endTurn(state); return; }
state.phase = 'block';
if (!blockOptions(state).length) resolveCombat(state);
}
function resolveCombat(state: DuelState): void {
const defender = other(state.active);
const pairs = Object.entries(state.combat.blocks)
.map(([b, a]) => ({ blocker: find(state, b), attacker: find(state, a) }))
.filter((x): x is { blocker: Permanent; attacker: Permanent } => !!x.blocker && !!x.attacker);
if (pairs.length) log(state, { kind: 'block', seat: defender, blocks: pairs.map(x => ({ blocker: ref(state, x.blocker), attacker: ref(state, x.attacker) })) });
// Simultaneous: compute every amount first, then apply.
const hits: { source: Permanent; target: TargetRef; amount: number }[] = [];
const blockerOf = new Map(pairs.map(x => [x.attacker.uid, x.blocker]));
for (const uid of state.combat.attackers) {
const a = find(state, uid);
if (!a) continue;
const ap = statsOfPermanent(state, a).power;
const b = blockerOf.get(uid);
if (b) {
hits.push({ source: a, target: { kind: 'card', uid: b.uid }, amount: ap });
hits.push({ source: b, target: { kind: 'card', uid: a.uid }, amount: statsOfPermanent(state, b).power });
} else {
hits.push({ source: a, target: { kind: 'player', seat: defender }, amount: ap });
}
}
const toPlayer: Permanent[] = [];
for (const h of hits) if (dealDamage(state, h.source, h.target, h.amount, true) > 0 && h.target.kind === 'player') toPlayer.push(h.source);
for (const a of toPlayer) {
for (const e of a.card.effects) if (e.trigger === 'onCombatDamageToPlayer') resolveEffect(state, a, a.controller, e, undefined, undefined);
for (const d of state.battlefield.filter(x => x.card.type === 'Doctrine' && x.attachedTo === a.uid)) {
for (const e of d.card.effects) if (e.trigger === 'onCombatDamageToPlayer') resolveEffect(state, d, d.controller, e, undefined, undefined);
}
}
settle(state);
if (!state.result) endTurn(state);
}
// ---------------------------------------------------------------------------
// applyAction
// ---------------------------------------------------------------------------
/**
* Structural clone for clone-on-apply. DuelCards, CardInstances, log events and the
* ruleset are never mutated after creation, so they are shared between states;
* Permanents, players and combat are copied. (structuredClone was 85% of runtime.)
*/
function cloneState(s: DuelState): DuelState {
const player = (p: PlayerState): PlayerState => ({ ...p, library: p.library.slice(), hand: p.hand.slice(), graveyard: p.graveyard.slice() });
return {
...s,
players: [player(s.players[0]), player(s.players[1])],
battlefield: s.battlefield.map(p => ({ ...p, tempKeywords: p.tempKeywords.slice(), permKeywords: p.permKeywords.slice() })),
combat: { attackers: s.combat.attackers.slice(), blocks: { ...s.combat.blocks } },
log: s.log.slice(),
result: s.result ? { ...s.result } : null,
};
}
function normalize(action: DuelAction): DuelAction {
// Canonical key order so deep-equal against legalActions is stable.
switch (action.type) {
case 'play': {
const targets = (action.targets ?? []).map(t => (t.kind === 'card' ? { kind: 'card' as const, uid: t.uid } : { kind: 'player' as const, seat: t.seat }));
return targets.length ? { type: 'play', uid: action.uid, targets } : { type: 'play', uid: action.uid };
}
case 'toggleAttacker': return { type: 'toggleAttacker', uid: action.uid };
case 'block': return { type: 'block', blocker: action.blocker, attacker: action.attacker };
default: return { type: action.type } as DuelAction;
}
}
export function applyAction(input: DuelState, seat: Seat, action: DuelAction): DuelState {
if (input.result) throw new Error('Match is over');
if (seat !== 0 && seat !== 1) throw new RangeError('Bad seat');
if (!action || typeof action !== 'object' || typeof (action as { type?: unknown }).type !== 'string') throw new TypeError('Bad action');
if (action.type === 'concede') {
const state = cloneState(input);
state.version += 1;
log(state, { kind: 'concede', seat });
finish(state, other(seat), 'concede');
return state;
}
if (toAct(input) !== seat) throw new Error('Not your turn to act');
if (action.type === 'timeout') {
const state = cloneState(input);
state.version += 1;
log(state, { kind: 'timeout', seat });
const p = state.players[seat];
p.timeouts += 1;
if (p.timeouts >= state.rules.timeoutsToConcede) { finish(state, other(seat), 'timeout'); return state; }
switch (state.phase) {
case 'mulligan': keep(state, seat); break;
case 'main': case 'attack': state.combat.attackers = []; endTurn(state); break;
case 'block': resolveCombat(state); break;
}
return state;
}
const a = normalize(action);
const key = JSON.stringify(a);
if (!legalActions(input, seat).some(x => JSON.stringify(x) === key)) throw new Error(`Illegal action ${JSON.stringify(action)}`);
const state = cloneState(input);
state.version += 1;
state.players[seat].timeouts = 0;
switch (a.type) {
case 'keep': keep(state, seat); break;
case 'mulligan': mulligan(state, seat); break;
case 'play': play(state, seat, a.uid, a.targets ?? []); break;
case 'endPhase': state.phase = 'attack'; break;
case 'toggleAttacker': state.combat.attackers.push(a.uid); break;
case 'confirmAttack': confirmAttack(state); break;
case 'block': state.combat.blocks[a.blocker] = a.attacker; break;
case 'confirmBlocks': resolveCombat(state); break;
}
return state;
}
function keep(state: DuelState, seat: Seat): void {
const p = state.players[seat];
for (let i = 0; i < p.mulligansTaken && p.hand.length; i++) p.library.push(p.hand.pop()!);
p.ready = true;
log(state, { kind: 'keep', seat, handSize: p.hand.length });
if (state.players[0].ready && state.players[1].ready) startTurn(state, state.firstSeat);
}
function mulligan(state: DuelState, seat: Seat): void {
const p = state.players[seat];
const rng = new Rng(state.rng);
p.library = rng.shuffle([...p.library, ...p.hand]);
state.rng = rng.state;
p.hand = p.library.splice(0, state.rules.openingHand);
p.mulligansTaken += 1;
log(state, { kind: 'mulligan', seat });
}
// ---------------------------------------------------------------------------
// Views, log, replay, serialisation
// ---------------------------------------------------------------------------
function side(state: DuelState, seat: Seat): SideView {
const p = state.players[seat];
return {
seat, life: p.life, citations: p.citations, maxCitations: maxCitations(state, seat), handSize: p.hand.length,
librarySize: p.library.length, graveyard: structuredClone(p.graveyard), bankSeconds: p.bankSeconds, ready: p.ready, mulligansTaken: p.mulligansTaken,
};
}
export function viewFor(state: DuelState, seat: Seat): PlayerView {
const battlefield: PermanentView[] = state.battlefield.map(perm => {
const { power, toughness } = statsOfPermanent(state, perm);
const c = connectionOf(state, perm);
return {
uid: perm.uid, owner: perm.owner, controller: perm.controller, card: structuredClone(perm.card), tapped: perm.tapped, sick: perm.sick,
damage: perm.damage, counters: perm.counters, ...(perm.attachedTo ? { attachedTo: perm.attachedTo } : {}), power, toughness,
keywords: keywordsOf(state, perm), ...(c ? { connected: { with: c.with.uid, tier: c.tier, via: c.via, bonus: c.bonus } } : {}),
};
});
return {
engine: 'duel', seat, turn: state.turn, active: state.active, phase: state.phase, toAct: toAct(state),
you: { ...side(state, seat), hand: structuredClone(state.players[seat].hand) },
opponent: side(state, other(seat)),
battlefield, combat: structuredClone(state.combat), result: state.result, version: state.version, rules: structuredClone(state.rules),
};
}
export function logFor(state: DuelState, seat: Seat): LogEvent[] {
return state.log.map(e => {
if (e.kind === 'draw' && e.seat !== seat) return { seq: e.seq, turn: e.turn, kind: 'draw', seat: e.seat } as LogEvent;
return structuredClone(e);
});
}
export function replay(rules: DuelRuleset, decks: [DuelCard[], DuelCard[]], seed: string, actions: { seat: Seat; action: DuelAction }[]): DuelState {
let state = createDuel(rules, decks, seed);
for (const { seat, action } of actions) state = applyAction(state, seat, action);
return state;
}
export const serialize = (state: DuelState): string => JSON.stringify(state);
export function deserialize(text: string): DuelState {
const value = JSON.parse(text) as DuelState;
if (!value || value.engine !== 'duel') throw new TypeError('Not a duel state');
return value;
}
// ---------------------------------------------------------------------------
// Host binding: structurally an EnginePort<DuelRuleset, DuelCard, DuelState, DuelAction>
// (server/game/engine-port.ts). shared/ must not import server/, so host-pvp types it there.
// ---------------------------------------------------------------------------
export const duelEnginePort = {
defaultRuleset: DEFAULT_DUEL_RULESET,
parseRuleset: (value: unknown) => parseDuelRuleset(value),
deckSize: (rules: DuelRuleset) => rules.deckSize,
starterDeck(_rules?: DuelRuleset, _seed?: string): DuelCard[] { throw new Error('Duel has no starter decks: every card must be owned (BRIEF decision 2)'); },
previewPool(_rules?: DuelRuleset, _seed?: string, _size?: number): DuelCard[] { throw new Error('Duel draft pools come from both players’ collections, not previews'); },
validateDeck,
cardPower: (card: DuelCard) => pw(card),
withPower: (card: DuelCard, power: number): DuelCard => ({ ...card, power: Math.max(0, Math.round(power)) }),
cardPageId: (card: DuelCard) => card.pageId,
cardSummary: (card: DuelCard) => ({
cardId: card.cardId, pageId: card.pageId, title: card.title, type: card.type, portal: card.portal, cost: card.cost,
power: card.power, toughness: card.toughness, keywords: card.keywords, rulesText: card.rulesText,
}),
createMatch: (rules: DuelRuleset, decks: [DuelCard[], DuelCard[]], seed: string) => createDuel(rules, decks, seed),
legalActions,
applyAction,
concedeAction: (_seat: Seat): DuelAction => ({ type: 'concede' }),
timeoutAction: (_seat: Seat): DuelAction => ({ type: 'timeout' }),
turnSeconds: (rules: DuelRuleset) => rules.turnSeconds,
turnOf,
/** Trending mode (DUEL_DESIGN §4): a frozen live ▲ ≥ +25% grants Trending (haste, +trendingPower/+0 in play). */
applyLive(_rules: DuelRuleset, card: DuelCard, live: { trendPercent: number | null }): DuelCard {
if (live.trendPercent === null || live.trendPercent < 25 || card.type !== 'Figure' || card.keywords.includes('Trending')) return card;
return { ...card, keywords: [...card.keywords, 'Trending'] };
},
isOver,
result: (state: DuelState) => state.result ?? { winner: null, reason: 'in progress' },
viewFor,
logFor,
};