diff --git a/docs/game/DUEL_API.md b/docs/game/DUEL_API.md new file mode 100644 index 0000000..511c5eb --- /dev/null +++ b/docs/game/DUEL_API.md @@ -0,0 +1,89 @@ +# WikiDeck Duel: engine API (v1, Night 2) + +Owner: **duel-core** (claude/wikideck#55). Rules: `docs/game/DUEL_DESIGN.md` (duel-design). This file: how code talks to the engine. +- Types: `shared/duel/types.ts`. Ruleset: `shared/duel/ruleset.ts`. Function surface: `DuelEngineApi` in `shared/duel/index.ts`, implemented by `shared/duel/engine.ts` (engine-alpha PR). +- `shared/game/` (Edit War) is untouched. Change requests: comment on #55 with `[from ]`. + +## Principles +- **Pure and deterministic.** `(rules, decks, seed, actions)` → identical state and log. RNG: `shared/game/rng.ts` (mulberry32); its uint32 state lives in `DuelState.rng`. +- **Plain JSON.** `DuelState` round-trips through `JSON.stringify`/`parse`; `serialize`/`deserialize` are thin wrappers. +- **Clone-on-apply.** `applyAction` never mutates its input and throws on an illegal action. +- **Atomic actions.** `legalActions(state, seat)` is small, and `[]` for the seat that is not to act. The host checks an action by deep-equal against that list (`concede` and `timeout` excepted). +- **Off-chain.** Matches never move or burn cards. Cards arrive derived and frozen; the engine does no I/O. + +## Cards (`DuelCard`) +Built by duel-cards (`derive()`), frozen by the host at match start. Shape agreed with duel-cards on #55. + +| Field | Notes | +|---|---| +| `cardId` | unique in a deck (NFT tokenId; sample id in sims; `token:` for tokens) | +| `pageId`, `revisionId?`, `title`, `description?` | `pageId` matches Linked pairs; `revisionId` for recap references | +| `type`, `subtype?` | `Figure` · `Location` · `Event` · `Institution` · `Doctrine` | +| `portal` | `Arts, Earth, History, Science, Society, Neutral`; no deckbuilding restriction | +| `cost` | 1–6 (Locations 1–3) | +| `power`, `toughness` | Figures: body. Locations: 0 / Garrison (0 = can't block). Others: `null` or 0 | +| `keywords` | ≤ `maxKeywords` (2). Figures only | +| `territory?` | Location: +N max Citations while controlled (total from all sources ≤ `territoryCap`) | +| `effects` | `EffectSpec[]` (below), ≤ 4 | +| `rulesText`, `flavor` | display only | +| `connect?` | `{countries, centuries, links, p31}` frozen claims; the engine computes Connected | +| `rarity?`, `deriveVersion?`, `token?` | | + +### Keywords (DUEL_DESIGN §4), as the engine applies them +- **Protected**: can't be the target of Events or Doctrines an opponent controls (abilities of other permanents and combat still apply). +- **Featured**: can be blocked only by Featured, Translated or Multilingual Figures. +- **Multilingual**: can block Featured; can't be blocked by Local Figures. +- **Translated**: can block Featured. +- **Legacy**: when destroyed, its controller draws a card. +- **Well-sourced**: prevent the first 1 damage dealt to it each turn. +- **Stub**: at the start of your turn, a +1/+1 counter, up to `stubMax` (2). +- **Local**: +1/+1 while you control a Location sharing a `connect.countries` value. +- **Trending** (Trending mode, set by the host via `applyLive`): no Pending review, +`trendingPower`/+0. + +### Effects (`EffectSpec`) +`{ trigger, op, target?, amount?, power?, toughness?, duration?, token?, condition?, grant?, template? }` +- **Triggers:** `onPlay` (Event resolves; on a permanent same as `onEnter`), `onEnter`, `onAttack`, `onDestroyed`, `startOfTurn`, `onCombatDamageToPlayer` (on a Figure, or on a Doctrine for its attached Figure), `static`. +- **Ops:** `damage`, `damageEach`, `createToken`, `pump`, `fight`, `draw`, `attach`, `gainLife`, `drain`, `destroy`, `bounce`, `tap`. +- **Targets:** chosen: `figure`, `figureOrLocation`, `ownFigure`, `opponentFigure`, `anyTarget`; automatic: `each`, `self`, `attached`, `ownFigures`, `opponentFigures`, `opponent`, `controller`. Defaults: damage → `anyTarget`, pump → `self`, draw/gainLife/createToken → `controller`, drain → `opponent`. +- **Chosen targets:** each `onPlay`/`onEnter` effect with a chosen target consumes the next entry of `play.targets`, in effect order; `legalActions` enumerates the combinations. An Event or Doctrine with no legal target can't be played; a Figure/Location/Institution enters and its targeted effect fizzles (`targets` omitted). +- **fight:** the previous chosen target in the same card (else the source permanent) and this target deal damage equal to their power to each other. T6 = `[{op:'pump', target:'ownFigure', power:k, toughness:0}, {op:'fight', target:'opponentFigure'}]`. +- **Doctrine:** its `attach` effect's target is the Figure it attaches to (`ownFigure` for T11, `figure` for T12). Its `static` effects with `target: 'attached'` apply to that Figure; `condition.samePortal` on a Doctrine means "other Figures you control of the attached Figure's Portal". When the Figure leaves, the Doctrine is Deleted. +- **static pump** applies while the source is in play; conditions use **printed** power (no feedback loops). `condition.connected` = the affected Figure is Connected to the source (T9). +- **createToken:** `amount` tokens of `token` (a fresh `DuelCard` with `token: true`, uid `t:`); `condition.maxTokens` = only if you control fewer tokens than that. Tokens leaving play cease to exist. +- Triggers resolve immediately: the active player's first, then in entry order. + +## Rules (defaults: `DEFAULT_DUEL_RULESET`; details in DUEL_DESIGN §2) +- 40-card decks (`deckSize`), ≤ 4 per `pageId`, unique `cardId`s, no tokens. 20 Notability. Drawing from an empty library loses (`libraryEmpty: 'lose'`; `'reshuffle'` and `'fatigue'` exist as data). +- Opening hand 7. Up to `mulligans` (1): shuffle in, draw 7, then on `keep` put one card per mulligan on the bottom (the last in hand order). Seat 0 decides first, then seat 1. +- First player (from the seed) skips their first draw. +- **Turn:** refresh (base max +1 to 10, plus Territory ≤ 2; refill; untap; Pending review ends; Stub and `startOfTurn` triggers) → draw → **main** → **attack** → **block** → damage → end (damage and "until end of turn" clear; discard down to `handSize` 7, **highest cost first**, automatically). +- Locations: `locationsPerTurn` (1), can't attack. Garrison Locations (toughness > 0) block as 0-power. +- Combat: attack the opponent only; each blocker blocks one attacker, at most one blocker per attacker; simultaneous damage; destroy triggers after all combat damage. No trample, first strike, stack or instants. +- **Connected** (engine, from `connect`, tiers in `connectedTiers`): Linked (either `links` contains the other's `pageId`, or either `cites` contains the other's `qid`), Compatriot (shared country), Contemporary (shared century, different types), Kin (shared P31, not Q5/Q16521). A Figure gets the single best bonus among other permanents its controller controls: `+linkedBonus` (2) if Linked, else `+connectedBonus` (1). Logged once (`connected`). Opposing Connected pairs are logged once as `rivalry`. +- **Timeouts:** `timeout` passes (mulligan: keep; main/attack: end the turn without attacking; block: confirm current blocks). `timeoutsToConcede` (3) consecutive timeouts by one seat lose (`reason: 'timeout'`). +- `turnCap` (null by default): after that many total turns, higher Notability wins, then higher total power in play, then the second player. + +## Phases and actions +| Phase | Who acts | Listed actions | +|---|---|---| +| `mulligan` | seat 0 until ready, then seat 1 | `keep`, `mulligan` | +| `main` | active | `play {uid, targets?}`, `endPhase` | +| `attack` | active | `toggleAttacker {uid}` (untapped, not Pending review, not yet declared), `confirmAttack` | +| `block` | defender | `block {blocker, attacker}` (unassigned blocker, unblocked attacker, evasion allowing), `confirmBlocks` | +| any | either seat | `concede` (not listed) | +| any | host, for the seat to act | `timeout` (not listed) | + +Declarations are **monotonic** (no un-declare), so every turn has a bounded number of actions; UIs stage choices locally and send them on confirm. If the defender has no legal block, damage resolves at `confirmAttack` with no block phase. `confirmAttack` with no attackers ends the turn. + +## Views and log +- `viewFor(state, seat): PlayerView`: your hand; the opponent's hand and library **sizes** only; both graveyards; the battlefield with current power/toughness, keywords and Connected badge; combat; `toAct`; `version`; `result`. Never the RNG or library order. +- **The seed is secret until the match ends.** `seed` plus the deck lists reproduce every shuffle, so the host never sends `seed` or `rng` (or the raw `DuelState`) to clients before `gameOver`. Live log rendering picks template variants from a derived `storySeed = sha256(seed + ':story')`. +- `state.log` is omniscient (server, and the recap after the match). Clients get **`logFor(state, seat)`**: the opponent's `draw` events have no `card`. Every other event is public information. +- Every event has `seq` and `turn`. `CardRef` carries `uid, cardId, title, pageId, type` plus `power`/`toughness` right after the event. +- Kinds (DUEL_DESIGN §10 names): `start, mulligan, keep, turnStart, draw, deploy, cast, adopt, tokenCreated, connected, rivalry, effect, attack, block, effectDamage, combatDamage, playerDamage, lifeGain, destroyed, bounced, discard, fatigue, concede, timeout, gameOver`. `destroyed` = the recap's casualties. Prose templates live with duel-design / ui-pvp, not in the engine. + +## Host binding +`duelEnginePort` (engine.ts) is structurally an `EnginePort` (`server/game/engine-port.ts`; `shared/` doesn't import `server/`, so host-pvp types it there). `concedeAction`, `timeoutAction`, `turnSeconds`, `turnOf`, `applyLive` included. `starterDeck` and `previewPool` throw: there are no starters (BRIEF decision 2); draft pools come from both players' collections. + +## Stability +These types are the contract for duel-cards, host-pvp, ui-duel, ui-pvp and sim-balance. Additive changes (optional fields, new log kinds) can land with the engine; breaking ones get a `[duel-core] contract change` comment on #55 first. diff --git a/shared/duel/index.ts b/shared/duel/index.ts new file mode 100644 index 0000000..af9f705 --- /dev/null +++ b/shared/duel/index.ts @@ -0,0 +1,35 @@ +/** + * WikiDeck Duel public API. Spec: docs/game/DUEL_API.md. + * Contracts PR: types and ruleset only. engine.ts (createDuel, legalActions, + * applyAction, viewFor, logFor, replay, ...) lands in the engine alpha PR and + * implements DuelEngineApi below; build against that interface until then. + */ +export * from './types.ts'; +export * from './ruleset.ts'; + +import type { DuelAction, DuelCard, DuelResult, DuelRuleset, DuelState, LogEvent, PlayerView, Seat } from './types.ts'; + +/** The engine's function surface (implemented by shared/duel/engine.ts). All pure; inputs are never mutated. */ +export interface DuelEngineApi { + /** Throws if the deck is illegal: size ≠ deckSize, duplicate cardId, > maxCopiesPerPage of one pageId, bad stats, > maxKeywords. */ + validateDeck(rules: DuelRuleset, cards: DuelCard[]): void; + /** Shuffle both decks from `seed`, deal opening hands, phase 'mulligan'. */ + createDuel(rules: DuelRuleset, decks: [DuelCard[], DuelCard[]], seed: string): DuelState; + /** Atomic legal actions for `seat`; [] if `seat` is not the one to act (concede is always accepted by applyAction but not listed). */ + legalActions(state: DuelState, seat: Seat): DuelAction[]; + /** Returns a new state. Throws on an illegal action. */ + applyAction(state: DuelState, seat: Seat, action: DuelAction): DuelState; + /** Seat that must act now, or null when over. Mulligan: the lowest seat not yet ready. */ + toAct(state: DuelState): Seat | null; + isOver(state: DuelState): boolean; + result(state: DuelState): DuelResult | null; + viewFor(state: DuelState, seat: Seat): PlayerView; + /** Per-seat log: the opponent's draws (and other hidden-zone cards) are masked. */ + logFor(state: DuelState, seat: Seat): LogEvent[]; + /** Deterministic: same inputs → identical state (and log). */ + replay(rules: DuelRuleset, decks: [DuelCard[], DuelCard[]], seed: string, actions: { seat: Seat; action: DuelAction }[]): DuelState; + serialize(state: DuelState): string; + deserialize(text: string): DuelState; + /** Current power/toughness of a permanent after counters, buffs, statics and Connected. */ + statsOf(state: DuelState, uid: string): { power: number; toughness: number }; +} diff --git a/shared/duel/ruleset.ts b/shared/duel/ruleset.ts new file mode 100644 index 0000000..8c7e2a3 --- /dev/null +++ b/shared/duel/ruleset.ts @@ -0,0 +1,76 @@ +/** + * Duel ruleset: every rule number as data (BRIEF "Game rules core"). + * parseDuelRuleset() is the only way untrusted JSON (mode files, peer hosts) + * becomes a DuelRuleset. Night 1 Edit War rulesets are rejected cleanly. + */ +import { z } from 'zod'; +import type { DuelRuleset } from './types.ts'; + +const int = (min: number, max: number) => z.number().int().min(min).max(max); + +export const DuelRulesetSchema = z.object({ + engine: z.literal('duel'), + version: z.string().min(1).max(16), + deckSize: int(1, 60), + maxCopiesPerPage: int(1, 60), + startingLife: int(1, 100), + openingHand: int(0, 10), + handSize: int(1, 15), + mulligans: int(0, 3), + firstPlayerDraws: z.boolean(), + maxCitations: int(1, 20), + citationsPerTurn: int(1, 5), + territoryCap: int(0, 10), + locationsPerTurn: int(0, 10), + libraryEmpty: z.enum(['lose', 'reshuffle', 'fatigue']), + maxKeywords: int(0, 4), + stubMax: int(0, 10), + trendingPower: int(0, 5), + connectedTiers: z.array(z.enum(['Linked', 'Compatriot', 'Contemporary', 'Kin'])).max(4) + .refine(v => new Set(v).size === v.length, 'Duplicate tier'), + connectedBonus: int(0, 5), + linkedBonus: int(0, 5), + turnSeconds: int(5, 600), + bankSeconds: int(0, 3600), + timeoutsToConcede: int(1, 20), + turnCap: int(2, 200).nullable(), +}).strict(); + +export const DEFAULT_DUEL_RULESET: DuelRuleset = Object.freeze({ + engine: 'duel', + version: 'duel-1', + deckSize: 40, + maxCopiesPerPage: 4, + startingLife: 20, + openingHand: 7, + handSize: 7, + mulligans: 1, + firstPlayerDraws: false, + maxCitations: 10, + citationsPerTurn: 1, + territoryCap: 2, + locationsPerTurn: 1, + libraryEmpty: 'lose', + maxKeywords: 2, + stubMax: 2, + trendingPower: 1, + connectedTiers: ['Linked', 'Compatriot', 'Contemporary', 'Kin'], + connectedBonus: 1, + linkedBonus: 2, + turnSeconds: 60, + bankSeconds: 300, + timeoutsToConcede: 3, + turnCap: null, +}) as DuelRuleset; + +/** Validate a full ruleset. Throws (ZodError) on anything invalid or unknown. */ +export function parseDuelRuleset(value: unknown): DuelRuleset { + return DuelRulesetSchema.parse(value) as DuelRuleset; +} + +/** Merge a partial override (a mode file's `rules`) onto the defaults, then validate. */ +export function mergeDuelRuleset(overrides: unknown, base: DuelRuleset = DEFAULT_DUEL_RULESET): DuelRuleset { + if (overrides === undefined || overrides === null) return parseDuelRuleset(structuredClone(base)); + if (typeof overrides !== 'object' || Array.isArray(overrides)) throw new TypeError('Ruleset overrides must be an object'); + return parseDuelRuleset({ ...structuredClone(base), ...(overrides as Record) }); +} diff --git a/shared/duel/types.ts b/shared/duel/types.ts new file mode 100644 index 0000000..96e4742 --- /dev/null +++ b/shared/duel/types.ts @@ -0,0 +1,397 @@ +/** + * 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 + 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 + /** Optional: 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; +} + +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; +} diff --git a/tests/duel-core-ruleset.test.ts b/tests/duel-core-ruleset.test.ts new file mode 100644 index 0000000..5121474 --- /dev/null +++ b/tests/duel-core-ruleset.test.ts @@ -0,0 +1,40 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { DEFAULT_DUEL_RULESET, mergeDuelRuleset, parseDuelRuleset, CARD_TYPES, KEYWORDS } from '../shared/duel/index.ts'; +import { DEFAULT_RULESET } from '../shared/game/index.ts'; + +test('duel default ruleset matches the BRIEF', () => { + const rules = parseDuelRuleset({ ...DEFAULT_DUEL_RULESET }); + assert.equal(rules.deckSize, 40); + assert.equal(rules.startingLife, 20); + assert.equal(rules.maxCitations, 10); + assert.equal(rules.handSize, 7); + assert.equal(rules.openingHand, 7); + assert.equal(rules.mulligans, 1); + assert.equal(rules.libraryEmpty, 'lose'); + assert.equal(rules.firstPlayerDraws, false); + assert.equal(rules.turnSeconds, 60); + assert.equal(rules.bankSeconds, 300); + assert.equal(rules.turnCap, null); + assert.equal(rules.territoryCap, 2); +}); + +test('duel ruleset merges overrides and rejects unknown keys', () => { + assert.equal(mergeDuelRuleset({ deckSize: 20 }).deckSize, 20); + assert.equal(mergeDuelRuleset({ turnCap: 30 }).turnCap, 30); + assert.throws(() => mergeDuelRuleset({ topicCount: 3 })); + assert.throws(() => mergeDuelRuleset({ libraryEmpty: 'shrug' })); + assert.throws(() => mergeDuelRuleset({ deckSize: 0 })); + assert.throws(() => mergeDuelRuleset([1])); +}); + +test('Night 1 Edit War rulesets are rejected cleanly', () => { + assert.throws(() => parseDuelRuleset(DEFAULT_RULESET)); +}); + +test('card types and keywords are the BRIEF set', () => { + assert.deepEqual([...CARD_TYPES], ['Figure', 'Location', 'Event', 'Institution', 'Doctrine']); + for (const k of ['Protected', 'Featured', 'Translated', 'Legacy', 'Stub', 'Well-sourced', 'Multilingual', 'Local']) { + assert.ok((KEYWORDS as readonly string[]).includes(k), k); + } +});