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>
399 lines
17 KiB
TypeScript
399 lines
17 KiB
TypeScript
/**
|
||
* WikiDeck Duel: the Magic-style 40-card engine (off-chain). Contract types.
|
||
* Spec: docs/game/DUEL_API.md (rules: docs/game/DUEL_DESIGN.md). Owner: duel-core (claude/wikideck#55).
|
||
*
|
||
* Everything here is plain JSON data: DuelState round-trips through
|
||
* JSON.stringify/parse with no loss (no Maps, classes or functions).
|
||
* shared/game/ (Edit War) is a separate engine and is not affected.
|
||
*/
|
||
import type { RngState } from '../game/rng.ts';
|
||
|
||
export type Seat = 0 | 1;
|
||
export const SEATS: readonly Seat[] = [0, 1];
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// Cards (derived by duel-cards in shared/duel/derive.ts; the engine never re-derives)
|
||
// ---------------------------------------------------------------------------
|
||
|
||
export type CardType = 'Figure' | 'Location' | 'Event' | 'Institution' | 'Doctrine';
|
||
export const CARD_TYPES: readonly CardType[] = ['Figure', 'Location', 'Event', 'Institution', 'Doctrine'];
|
||
|
||
export type Portal = 'Arts' | 'Earth' | 'History' | 'Science' | 'Society' | 'Neutral';
|
||
export const PORTALS: readonly Portal[] = ['Arts', 'Earth', 'History', 'Science', 'Society', 'Neutral'];
|
||
|
||
/** Card keywords (DUEL_DESIGN §4), ≤ ruleset.maxKeywords per card. 'Trending' is granted by Trending mode only. */
|
||
export type Keyword = 'Protected' | 'Featured' | 'Legacy' | 'Multilingual' | 'Translated' | 'Well-sourced' | 'Stub' | 'Local' | 'Trending';
|
||
export const KEYWORDS: readonly Keyword[] = ['Protected', 'Featured', 'Legacy', 'Multilingual', 'Translated', 'Well-sourced', 'Stub', 'Local', 'Trending'];
|
||
|
||
/** Connected tiers (DUEL_DESIGN §6). The engine computes them from `connect`. */
|
||
export type ConnectedTier = 'Linked' | 'Compatriot' | 'Contemporary' | 'Kin';
|
||
export const CONNECTED_TIERS: readonly ConnectedTier[] = ['Linked', 'Compatriot', 'Contemporary', 'Kin'];
|
||
|
||
/** Frozen claims used for Connected (no I/O during a match). */
|
||
export interface ConnectKeys {
|
||
/** P17/P27 values (Q-ids or labels; compared as strings). */
|
||
countries: string[];
|
||
/** From P569/P570/P571/P580/P585, e.g. 19 for the 1800s. */
|
||
centuries: number[];
|
||
/** Outlink pageIds (cached), plus pageIds the card's claims cite. */
|
||
links: number[];
|
||
/** P31 Q-ids. Q5 (human) and Q16521 (taxon) never count for Kin. */
|
||
p31: string[];
|
||
/** The card's own Q-id, and the Q-ids its claims cite: Linked if either cites the other (DUEL_DESIGN §6). */
|
||
qid?: string;
|
||
cites?: string[];
|
||
}
|
||
|
||
/** When an effect runs. Sorcery speed only: there is no stack and no response window. */
|
||
export type EffectTrigger =
|
||
| 'onPlay' // an Event resolves (on a permanent: same as onEnter)
|
||
| 'onEnter' // this permanent enters the battlefield
|
||
| 'onAttack' // this Figure is declared as an attacker (resolves at confirmAttack)
|
||
| 'onDestroyed' // this permanent is destroyed (after all combat damage)
|
||
| 'startOfTurn' // its controller's refresh step, in entry order
|
||
| 'onCombatDamageToPlayer' // this Figure (or the Figure this Doctrine is attached to) deals combat damage to a player
|
||
| 'static'; // continuous while on the battlefield
|
||
|
||
/** Effect ops the interpreter knows. duel-cards builds the 12 templates (DUEL_DESIGN §5) from these. */
|
||
export type EffectOp =
|
||
| 'damage' // `amount` to each target (Figure, Location or player)
|
||
| 'damageEach' // `amount` to every Figure and Location (target narrows: 'ownFigures' / 'opponentFigures')
|
||
| 'createToken' // `amount` (default 1) copies of `token` under the controller; condition.maxTokens limits
|
||
| 'pump' // +power/+toughness (negative allowed); duration 'turn' | 'permanent'; as static: while the source is in play
|
||
| 'fight' // the previous chosen target (else this permanent) and this target deal damage equal to their power to each other
|
||
| 'draw' // controller draws `amount`
|
||
| 'attach' // Doctrine: attach to the target Figure (defines the Doctrine's target)
|
||
| 'gainLife' // controller gains `amount` Notability
|
||
| 'drain' // opponent loses `amount`, controller gains `amount`
|
||
| 'destroy' // destroy target permanent
|
||
| 'bounce' // return target permanent to its owner's hand
|
||
| 'tap'; // tap target permanent
|
||
|
||
export type TargetSpec =
|
||
// chosen (each consumes one entry of play.targets, in effect order)
|
||
| 'figure' // any Figure
|
||
| 'figureOrLocation' // any Figure or Location
|
||
| 'ownFigure' // a Figure you control
|
||
| 'opponentFigure' // a Figure you don't control
|
||
| 'anyTarget' // any Figure, Location or player
|
||
// automatic
|
||
| 'each' // every Figure and Location
|
||
| 'self' // this permanent
|
||
| 'attached' // the Figure this Doctrine is attached to
|
||
| 'ownFigures' // every Figure you control
|
||
| 'opponentFigures' // every Figure you don't control
|
||
| 'opponent' // the opposing player
|
||
| 'controller'; // you
|
||
|
||
export interface TokenSpec { name: string; power: number; toughness: number; portal: Portal }
|
||
|
||
export interface EffectSpec {
|
||
trigger: EffectTrigger;
|
||
op: EffectOp;
|
||
/** Default per op: damage → 'anyTarget'; pump → 'self'; draw/gainLife/createToken → 'controller'; drain → 'opponent'. */
|
||
target?: TargetSpec;
|
||
amount?: number;
|
||
/** pump: +power/+toughness (default: amount/amount). */
|
||
power?: number;
|
||
toughness?: number;
|
||
/** pump/grant outside static: 'turn' (default) or 'permanent'. */
|
||
duration?: 'turn' | 'permanent';
|
||
token?: TokenSpec;
|
||
condition?: {
|
||
/** Only affects Figures with printed power ≤ maxPower. */
|
||
maxPower?: number;
|
||
/** Only Figures of the source's Portal (for a Doctrine: the attached Figure's Portal), excluding that card itself. */
|
||
samePortal?: boolean;
|
||
/** Only Figures Connected to the source. */
|
||
connected?: boolean;
|
||
/** createToken: only if the controller controls fewer than this many tokens. */
|
||
maxTokens?: number;
|
||
};
|
||
/** Keywords granted to the affected Figures (static: while in play; otherwise for `duration`). */
|
||
grant?: Keyword[];
|
||
/** Template id (T1–T12) for rules text and log wording. */
|
||
template?: string;
|
||
}
|
||
|
||
/**
|
||
* A card as the engine sees it, frozen at match start. The host builds these
|
||
* from the chain via duel-cards' derive(); the engine trusts them.
|
||
*/
|
||
export interface DuelCard {
|
||
/** Unique within one deck: the NFT tokenId (or a sample id in sims; `token:` ids for tokens). */
|
||
cardId: string;
|
||
pageId: number | null;
|
||
revisionId?: number;
|
||
title: string;
|
||
/** Wikidata description ("American actor (1909–1994)"), for log first mentions. */
|
||
description?: string;
|
||
type: CardType;
|
||
/** e.g. 'conflict', 'election', 'organisation', 'pathology'. */
|
||
subtype?: string | null;
|
||
portal: Portal;
|
||
cost: number;
|
||
/** Figures: the body. Locations: power 0, toughness = Garrison (0 = can't block). Others: null or 0. */
|
||
power: number | null;
|
||
toughness: number | null;
|
||
keywords: Keyword[];
|
||
/** Locations: +N max Citations while controlled (all sources together ≤ territoryCap). */
|
||
territory?: number;
|
||
effects: EffectSpec[];
|
||
/** Deterministic rules text (shared/duel/text.ts). Display only. */
|
||
rulesText: string;
|
||
/** First sentence of article.extract (else description). Display only. */
|
||
flavor: string;
|
||
connect?: ConnectKeys;
|
||
rarity?: 'Common' | 'Rare' | 'Epic' | 'Legendary';
|
||
deriveVersion?: string;
|
||
/** Tokens are created in play and never in decks. */
|
||
token?: boolean;
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// Ruleset (all numbers are data; parseDuelRuleset in ruleset.ts validates)
|
||
// ---------------------------------------------------------------------------
|
||
|
||
export type LibraryEmpty = 'lose' | 'reshuffle' | 'fatigue';
|
||
|
||
export interface DuelRuleset {
|
||
engine: 'duel';
|
||
version: string;
|
||
deckSize: number; // 40
|
||
maxCopiesPerPage: number; // 4
|
||
startingLife: number; // 20 Notability
|
||
openingHand: number; // 7
|
||
handSize: number; // 7: hand limit at end of turn (DUEL_DESIGN `handLimit`); excess discarded highest cost first
|
||
mulligans: number; // 1: shuffle, draw openingHand, bottom one per mulligan taken
|
||
firstPlayerDraws: boolean; // false
|
||
secondPlayerCitations: number; // 1 (balance v1): extra Citations on the second player's first turn (designer's "Second Opinion" lever)
|
||
maxCitations: number; // 10
|
||
citationsPerTurn: number; // 1
|
||
territoryCap: number; // 2
|
||
locationsPerTurn: number; // 1
|
||
libraryEmpty: LibraryEmpty; // 'lose'
|
||
maxKeywords: number; // 2
|
||
stubMax: number; // 2: max Stub counters
|
||
trendingPower: number; // 1: Trending gets +N/+0
|
||
connectedTiers: ConnectedTier[]; // all four; cut tiers by removing them
|
||
connectedBonus: number; // 1
|
||
linkedBonus: number; // 2
|
||
turnSeconds: number; // 60
|
||
bankSeconds: number; // 300
|
||
timeoutsToConcede: number; // 3 consecutive timeouts lose
|
||
/** 40 (balance v1); null = none. After this many turns in total, higher Notability wins, then higher power in play, then the second player. */
|
||
turnCap: number | null;
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// State
|
||
// ---------------------------------------------------------------------------
|
||
|
||
/** 'mulligan' → 'main' → 'attack' → ('block' if attackers can be blocked) → next turn. Refresh, draw, damage and end are automatic. */
|
||
export type Phase = 'mulligan' | 'main' | 'attack' | 'block' | 'over';
|
||
|
||
/** One physical card in a match. `uid` is unique per match ("0:12" = seat 0, deck index 12; "t:3" = token); actions use uids. */
|
||
export interface CardInstance {
|
||
uid: string;
|
||
owner: Seat;
|
||
card: DuelCard;
|
||
}
|
||
|
||
export interface Permanent extends CardInstance {
|
||
controller: Seat;
|
||
tapped: boolean;
|
||
/** "Pending review": entered this turn, can't attack. */
|
||
sick: boolean;
|
||
damage: number;
|
||
/** Stub +1/+1 counters. */
|
||
counters: number;
|
||
/** Permanent pump modifiers. */
|
||
permPower: number;
|
||
permToughness: number;
|
||
/** Until-end-of-turn modifiers. */
|
||
tempPower: number;
|
||
tempToughness: number;
|
||
/** Keywords granted until end of turn / permanently by non-static effects. */
|
||
tempKeywords: Keyword[];
|
||
permKeywords: Keyword[];
|
||
/** Doctrines: uid of the Figure they're attached to. */
|
||
attachedTo?: string;
|
||
/** Well-sourced: prevention already used this turn. */
|
||
shielded: boolean;
|
||
/** Entry order (trigger order). */
|
||
entered: number;
|
||
/** Connected bonus already logged. */
|
||
connectedLogged: boolean;
|
||
}
|
||
|
||
export interface PlayerState {
|
||
life: number;
|
||
/** Citations available this turn. */
|
||
citations: number;
|
||
/** Base max (rises by citationsPerTurn to maxCitations). */
|
||
baseCitations: number;
|
||
library: CardInstance[]; // top = index 0. Hidden.
|
||
hand: CardInstance[]; // hidden from the opponent
|
||
graveyard: CardInstance[]; // "Deleted", public
|
||
mulligansTaken: number;
|
||
ready: boolean;
|
||
locationsThisTurn: number;
|
||
/** Remaining time bank in seconds (the host decrements it). */
|
||
bankSeconds: number;
|
||
/** Consecutive timeouts. */
|
||
timeouts: number;
|
||
/** libraryEmpty 'fatigue': damage of the last empty draw. */
|
||
fatigue: number;
|
||
}
|
||
|
||
export interface CombatState {
|
||
attackers: string[];
|
||
/** blocker uid → attacker uid. */
|
||
blocks: Record<string, string>;
|
||
}
|
||
|
||
export type EndReason = 'life' | 'library' | 'concede' | 'timeout' | 'turnCap';
|
||
|
||
export interface DuelResult {
|
||
winner: Seat | null; // null = draw
|
||
reason: EndReason;
|
||
}
|
||
|
||
export interface DuelState {
|
||
engine: 'duel';
|
||
rules: DuelRuleset;
|
||
seed: string;
|
||
rng: RngState;
|
||
/** 1-based, counts both players' turns. 0 during mulligans. */
|
||
turn: number;
|
||
active: Seat;
|
||
firstSeat: Seat;
|
||
phase: Phase;
|
||
players: [PlayerState, PlayerState];
|
||
battlefield: Permanent[];
|
||
combat: CombatState;
|
||
log: LogEvent[];
|
||
result: DuelResult | null;
|
||
/** Increments on every applied action (host polling: unchanged → 204). */
|
||
version: number;
|
||
/** Counters for token uids and entry order. */
|
||
nextToken: number;
|
||
nextEntry: number;
|
||
}
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// Actions (atomic; legalActions enumerates them; [] for the seat not to act)
|
||
// ---------------------------------------------------------------------------
|
||
|
||
export type TargetRef = { kind: 'card'; uid: string } | { kind: 'player'; seat: Seat };
|
||
|
||
export type DuelAction =
|
||
| { type: 'keep' }
|
||
| { type: 'mulligan' }
|
||
/** targets: one per chosen-target effect, in effect order (Doctrine: its 'attach' target). Omitted when none. */
|
||
| { type: 'play'; uid: string; targets?: TargetRef[] }
|
||
| { type: 'endPhase' } // main → attack
|
||
| { type: 'toggleAttacker'; uid: string } // declare one more attacker (monotonic)
|
||
| { type: 'confirmAttack' } // no attackers → end turn
|
||
| { type: 'block'; blocker: string; attacker: string } // defender, monotonic
|
||
| { type: 'confirmBlocks' } // damage, then end of turn
|
||
| { type: 'concede' } // any time, either seat (not listed)
|
||
| { type: 'timeout' }; // host-only, for the seat that must act (not listed)
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// Log (encyclopedic; clients get logFor(state, seat); state.log is omniscient)
|
||
// ---------------------------------------------------------------------------
|
||
|
||
/** A card in the log. power/toughness: current values right after the event (Figures and Garrisons on the battlefield). */
|
||
export interface CardRef { uid: string; cardId: string; title: string; pageId: number | null; type: CardType; power?: number; toughness?: number }
|
||
|
||
export type LogEvent = { seq: number; turn: number } & (
|
||
| { kind: 'start'; firstSeat: Seat }
|
||
| { kind: 'mulligan'; seat: Seat }
|
||
| { kind: 'keep'; seat: Seat; handSize: number }
|
||
| { kind: 'turnStart'; seat: Seat; citations: number; life: [number, number] }
|
||
/** card is omitted in the opponent's logFor (hidden draw). */
|
||
| { kind: 'draw'; seat: Seat; card?: CardRef }
|
||
/** A Figure, Location or Institution entered. */
|
||
| { kind: 'deploy'; seat: Seat; card: CardRef }
|
||
/** An Event resolved. */
|
||
| { kind: 'cast'; seat: Seat; card: CardRef; targets: TargetRef[] }
|
||
/** A Doctrine was attached. */
|
||
| { kind: 'adopt'; seat: Seat; card: CardRef; to: CardRef }
|
||
| { kind: 'tokenCreated'; seat: Seat; card: CardRef; source: CardRef }
|
||
| { kind: 'connected'; seat: Seat; card: CardRef; with: CardRef; tier: ConnectedTier; via: string; bonus: number }
|
||
/** Rivalry (log only): two opposing permanents are Connected. */
|
||
| { kind: 'rivalry'; card: CardRef; with: CardRef; tier: ConnectedTier; via: string }
|
||
/** Any resolved effect (wording key: template). Damage and life changes follow as their own events. */
|
||
| { kind: 'effect'; seat: Seat; source: CardRef; op: EffectOp; template?: string; targets: TargetRef[] }
|
||
| { kind: 'attack'; seat: Seat; attackers: CardRef[] }
|
||
| { kind: 'block'; seat: Seat; blocks: { blocker: CardRef; attacker: CardRef }[] }
|
||
/** Damage to a permanent from an effect / from combat. */
|
||
| { kind: 'effectDamage'; source: CardRef; target: CardRef; amount: number }
|
||
| { kind: 'combatDamage'; source: CardRef; target: CardRef; amount: number }
|
||
/** Damage or life loss to a player. source null = fatigue. */
|
||
| { kind: 'playerDamage'; source: CardRef | null; seat: Seat; amount: number; life: number; combat: boolean }
|
||
| { kind: 'lifeGain'; source: CardRef; seat: Seat; amount: number; life: number }
|
||
| { kind: 'destroyed'; card: CardRef; owner: Seat }
|
||
| { kind: 'bounced'; card: CardRef; owner: Seat }
|
||
| { kind: 'discard'; seat: Seat; card: CardRef }
|
||
| { kind: 'fatigue'; seat: Seat; amount: number }
|
||
| { kind: 'concede'; seat: Seat }
|
||
| { kind: 'timeout'; seat: Seat }
|
||
| { kind: 'gameOver'; winner: Seat | null; reason: EndReason; life: [number, number] }
|
||
);
|
||
|
||
export type LogKind = LogEvent['kind'];
|
||
|
||
// ---------------------------------------------------------------------------
|
||
// Views (what one seat may see; bots and UI get only this)
|
||
// ---------------------------------------------------------------------------
|
||
|
||
export interface PermanentView {
|
||
uid: string;
|
||
owner: Seat;
|
||
controller: Seat;
|
||
card: DuelCard;
|
||
tapped: boolean;
|
||
sick: boolean;
|
||
damage: number;
|
||
counters: number;
|
||
attachedTo?: string;
|
||
/** Current values after counters, pumps, statics, Connected and Trending. */
|
||
power: number;
|
||
toughness: number;
|
||
keywords: Keyword[];
|
||
/** Active Connected bonus, if any (for the card face). */
|
||
connected?: { with: string; tier: ConnectedTier; via: string; bonus: number };
|
||
}
|
||
|
||
export interface SideView {
|
||
seat: Seat;
|
||
life: number;
|
||
citations: number;
|
||
maxCitations: number;
|
||
handSize: number;
|
||
librarySize: number;
|
||
graveyard: CardInstance[];
|
||
bankSeconds: number;
|
||
ready: boolean;
|
||
mulligansTaken: number;
|
||
}
|
||
|
||
export interface PlayerView {
|
||
engine: 'duel';
|
||
seat: Seat;
|
||
turn: number;
|
||
active: Seat;
|
||
phase: Phase;
|
||
/** Seat that must act now (null when over). */
|
||
toAct: Seat | null;
|
||
you: SideView & { hand: CardInstance[] };
|
||
opponent: SideView;
|
||
battlefield: PermanentView[];
|
||
combat: CombatState;
|
||
result: DuelResult | null;
|
||
version: number;
|
||
rules: DuelRuleset;
|
||
}
|