Files
wikideck/docs/game/DUEL_API.md
T

8.4 KiB
Raw Blame History

WikiDeck Duel: engine API (v1, Night 2)

Owner: duel-core (claude/wikideck#55). Types: shared/duel/types.ts. Ruleset: shared/duel/ruleset.ts. Function surface: DuelEngineApi in shared/duel/index.ts (implemented by shared/duel/engine.ts in the engine-alpha PR). shared/game/ (Edit War) is untouched. Change requests: comment on #55 with [from <agent>].

Principles

  • Pure and deterministic. (rules, decks, seed, actions) → identical state and log. RNG is shared/game/rng.ts (mulberry32), its uint32 state stored 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; it throws on an illegal action.
  • Atomic actions. legalActions(state, seat) is small and is [] for the seat that is not to act. The host checks an action by deep-equal against that list (concede excepted).
  • Off-chain. Matches never move or burn cards. Cards arrive fully derived and frozen (type, stats, keywords, effects, Connected links); the engine never fetches anything.

Cards (DuelCard)

Built by duel-cards (shared/duel/derive.ts) and frozen by the host at match start.

Field Notes
cardId unique in a deck (NFT hash; sample id in sims)
pageId, title, description? pageId is used to match Connected pairs
type Figure (creature) · Location (Territory/Garrison permanent) · Event (sorcery) · Institution (artifact) · Doctrine (Aura on a Figure)
portal faction id; no deckbuilding restriction
cost 1–6, power, toughness non-Figures use 0/0
keywords ≤ rules.maxKeywords (2) of Protected, Featured, Translated, Legacy, Stub, Well-sourced, Multilingual, Local
territory? Location: +1 max Citations (all sources together ≤ territoryCap)
garrison? Location may block with {power, toughness}
effects EffectSpec[] (below)
text, flavour display only (rules text from text.ts; flavour = first sentence of article.extract)
connections? {pageId, tier, via}[], frozen claims
revisionId?, source for the recap; `'owned'

Engine-side keyword meanings (designer §3.4; duel-design owns the wording):

  • Protected: can't be targeted by the opponent's Events or other chosen-target effects.
  • Featured (flying): can be blocked only by Featured or Translated Figures.
  • Translated (reach): can block Featured Figures.
  • Legacy: when destroyed, its controller draws a card.
  • Stub: at the start of its controller's turn, gets a +1/+1 counter (at most 2 from Stub).
  • Well-sourced: prevent the first 1 damage dealt to it each turn.
  • Trending (haste, Trending mode only): no summoning sickness.
  • Multilingual, Local: no engine rule; duel-cards expresses them as effects if DUEL_DESIGN gives them one.

Effects (EffectSpec)

{ trigger, op, target, amount?, amount2?, maxPower?, maxCost?, template? }

  • Triggers: onPlay (Event resolves / permanent enters), onAttack, onDeath, startOfTurn, static.
  • Ops (12): damage, heal, drain, draw, buff (until end of turn; as static, while the source is in play), counter (+n/+n permanent), destroy, bounce, tap, citations, ramp, mill.
  • Targets: chosen: anyFigure, ownFigure, enemyFigure, enemyPermanent, anyTarget; automatic: none, self, attached, controller, opponent, allFigures, ownFigures, enemyFigures. Optional filters maxPower, maxCost.
  • One chosen target per card: the first onPlay effect with a chosen target defines play.target; other chosen-target effects on the same card reuse it. A card whose required target has no legal choice can't be played (Events) or enters with that effect fizzling (permanents).
  • Doctrine: play.target is the Figure it attaches to (any Figure you control, unless its effects say enemyFigure); its static effects with target: 'attached' apply to that Figure. If the Figure leaves, the Doctrine goes to the graveyard.
  • Triggers resolve immediately in a fixed order: active player's first, then battlefield order (oldest first).

Rules (defaults from DEFAULT_DUEL_RULESET)

  • 40-card decks, ≤ 4 copies per pageId. 20 Notability; 0 loses. Drawing from an empty library loses (libraryEmpty: 'lose'; reshuffle/fatigue exist as data).
  • Opening hand 7. Up to mulligans (1): shuffle hand in, draw 7, put mulligansTaken cards on the bottom (the last ones in hand order, automatically). Both players choose keep/mulligan; seat 0 then seat 1.
  • First player (from the seed) skips the first draw.
  • Turn: refresh (base max Citations +1 to maxCitations 10, plus bonus ≤ territoryCap 2; refill; untap; startOfTurn triggers) → draw → main → attack → block (only if attackers) → damage → end (temp buffs and damage clear; discard down to handSize 7, newest cards first).
  • Figures have summoning sickness ("Pending review") unless Trending. Attack the opponent only. Each blocker blocks one attacker, at most one blocker per attacker; untapped Figures and Garrison Locations can block. Damage is simultaneous; unblocked attackers hit Notability. No trample, first strike, stack or instants.
  • Connected: a Figure gets +connectedBonus/+connectedBonus (1) while its controller controls another permanent whose pageId appears in its connections, or +linkedBonus (2) if that link's tier is Linked. Only the best link counts. Logged once when it first applies.
  • turnCap (optional, null by default): after that many total turns, higher Notability wins; equal = draw.

Phases and actions

phase: mulligan → main → attack → block → (next turn's main) … over.

Phase Who acts Actions
mulligan each seat not yet ready (seat 0 first) keep, mulligan
main active play {uid, target?} (cost ≤ Citations; Events and permanents), endPhase
attack active toggleAttacker {uid} (declare an untapped, non-sick Figure not yet declared), confirmAttack
block defender block {blocker, attacker} (unassigned blocker, unblocked attacker), confirmBlocks
any either seat concede (not listed; always accepted)
any host only timeout for the seat that must act: in main/attack ends the turn without attacking, in block confirms the current blocks, in mulligan keeps. It does not lose the game; the host decides when a bank is exhausted and may then send concede.

Declarations are monotonic (no un-declare action), 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, combat damage resolves at confirmAttack without a block phase. confirmAttack with no attackers ends the turn. Attacking taps the attackers. onAttack triggers resolve at confirmAttack.

Views and log

  • viewFor(state, seat): PlayerView: your hand, sizes of the opponent's hand and library, both graveyards, the battlefield with current power/toughness and Connected badge, combat, toAct, version, result.
  • state.log is the full, omniscient event list (for the server and recap after the match). Clients get logFor(state, seat): the opponent's draw events lose card, and nothing else from a hidden zone is revealed until it becomes public (play, discard, mill). Every event carries seq and turn.
  • Event kinds: start, mulligan, keep, turn, draw, play, attach, connected, effect, attack, block, damage, life, destroyed, bounced, discard, mill, fatigue, concede, timeout, end. destroyed events are the recap's casualties. Text templates for these live with duel-design / ui-pvp (shared/duel/recap.ts), not in the engine.

Host binding

shared/duel/engine.ts will also export duelEnginePort: EnginePort<DuelRuleset, DuelCard, DuelState, DuelAction> (shape of server/game/engine-port.ts): concedeAction, timeoutAction, turnSeconds, turnOf included; starterDeck/previewPool throw (no starters, BRIEF decision 2) except where draft supplies the pool. host-pvp wires it into server/game/.

Stability

Types in this file are the contract for duel-cards, host-pvp, ui-duel, ui-pvp and sim-balance. Additive changes (new optional fields, new log kinds) can land with the engine; breaking ones get a [duel-core] contract change comment on #55 first.