8.4 KiB
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 isshared/game/rng.ts(mulberry32), its uint32 state stored inDuelState.rng. - Plain JSON.
DuelStateround-trips throughJSON.stringify/parse.serialize/deserializeare thin wrappers. - Clone-on-apply.
applyActionnever 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
effectsif 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; asstatic, 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 filtersmaxPower,maxCost. - One chosen target per card: the first
onPlayeffect with a chosen target definesplay.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.targetis the Figure it attaches to (any Figure you control, unless its effects sayenemyFigure); itsstaticeffects withtarget: '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/fatigueexist as data). - Opening hand 7. Up to
mulligans(1): shuffle hand in, draw 7, putmulligansTakencards on the bottom (the last ones in hand order, automatically). Both players choosekeep/mulligan; seat 0 then seat 1. - First player (from the seed) skips the first draw.
- Turn: refresh (base max Citations +1 to
maxCitations10, plus bonus ≤territoryCap2; refill; untap;startOfTurntriggers) → draw → main → attack → block (only if attackers) → damage → end (temp buffs and damage clear; discard down tohandSize7, 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 whosepageIdappears in itsconnections, or+linkedBonus(2) if that link's tier isLinked. 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.logis the full, omniscient event list (for the server and recap after the match). Clients getlogFor(state, seat): the opponent'sdrawevents losecard, and nothing else from a hidden zone is revealed until it becomes public (play,discard,mill). Every event carriesseqandturn.- Event kinds:
start, mulligan, keep, turn, draw, play, attach, connected, effect, attack, block, damage, life, destroyed, bounced, discard, mill, fatigue, concede, timeout, end.destroyedevents 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.