Files
wikideck/docs/game/DESIGN.md
T
claudeandClaude Opus 5.5 175713e8b2 docs(game): DESIGN.md v1 review fixes and deliberate divergences
- Exact Topic draw algorithm (one RNG order)
- onTopicBonus scales with cost (about 2 power per energy on-topic at every cost)
- Host swaps in live snapshot before building CardInput; verifyStats caching and fail-open
- Commit-reveal seed for hosted PvP; copies count owned and loaners together
- Diverge from Snap: lane capacity 3, energy carry-over 1, interleaved alternating reveals,
  stats visible from turn 1 with hidden Portals, consensus lane tie-break

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 22:52:54 -05:00

18 KiB
Raw Blame History

WikiDeck: Edit War — game design v1 (draft)

Status: v1 DRAFT, freeze target 23:30 EST 2026-11-16. Owners: council-designer-a owns sections 0–9 (research, card derivation, rules). council-designer-b owns sections 10–12 (keywords, peer-hosted modes, worked example). council-critic reviews. Every number in code font is a rules-config key (see §9). Modes can override any of them.

A two-player lane game for 3–6 minute matches. Each player has a 12-card deck and there are 3 Topics (lanes) with 3 slots per side. There are 6 turns, both players plan at the same time, and energy ramps from 1 to 6, with 1 unspent energy carried over. Reveals interleave one card at a time. Win 2 of the 3 Topics. Each Topic is judged on one Wikipedia stat (Attention, Depth or Reach), and a card is stronger in a Topic that matches its best stat. Fame (how high a card's stats are overall) sets its cost, not its efficiency, so famous cards are sidegrades. They are not upgrades.


0. Research summary (what we took, what we left)

Game Why it's fun Taken Left
Marvel Snap 3-minute matches; simultaneous turns; 3 lanes, so the decision is where, not just what lanes, about 6 turns, simultaneous planning, small deck stakes betting (modes only); we deliberately diverge in lane size (3), energy carry-over, interleaved alternating reveals, stats visible from turn 1 with hidden Portals, and on-topic tie-breaks
Hearthstone mana curve; readable cards; tempo energy = turn number, curve-shaped costs 30-card decks and 15-minute matches; hero powers
Magic: The Gathering factions (colours) with distinct identities; deckbuilding depth 6 factions with their own keyword flavour land screw (resource variance); the stack; long text
Balatro huge "moment" when a combo goes off; simple base rules plus modifiers lane modifiers (Portals) as the run-to-run variety single-player scoring
Slay the Spire readable intents; every card is a choice open information about lane state and power roguelike runs (could be a mode)
Gwent rows; best 2 of 3; passing and bluffing best 2 of 3 Topics; hidden commitments multi-round card advantage (too long)
Pokémon TCG type advantage on-topic bonus (card stat matches lane stat) energy attachment; coin flips
Top Trumps instantly understood: "my number beats yours" lanes judged on one stat picking the stat is solved play (always pick your best)
Dominion deck building as play — (too long for 3–6 min) —

The core loop is a lanes game in the style of Snap. The Top Trumps twist is that each lane asks for one Wikipedia stat. That makes every stat matter and gives each turn its main decision: play the card on-topic for the bonus, or put it where the fight is.


1. Card derivation (card data → game card)

The engine never reads raw 0–100 stats as power. Every game card is derived deterministically from a CardInput that the match host freezes at match start:

CardInput = { cardId, pageId, title, category, rarity,
              snapshot: MintStatsSnapshot,             // at mint, immutable
              live: { trendPercent: number | null } }  // frozen at match start

1.1 Percentiles (rank-normalisation)

For each stat s in {attention, depth, reach}, pct_s = the percentile (0–100, integer) of the card's snapshot score in the reference table percentiles.<s>. That table holds 99 ascending cut points from council-data's docs/game/card-sample.json. pct_s = the number of cut points strictly below the score, plus half the number equal to it, rounded down. A null attention gives pct_attention = null.

1.2 Fame → Cost

fame = the integer mean (rounded half up) of the non-null percentiles. cost = 1 + the number of thresholds in costThresholds (5 ascending values, default [15, 35, 55, 75, 90]) that are ≤ fame. So cost runs 1–6. The defaults aim at a pool cost spread of about 15/20/20/20/15/10 %. They are retuned from the sample's fame distribution.

1.3 Power

power = powerByCost[cost], default [_, 1, 2, 4, 5, 7, 9] (cost 1 → 1 … cost 6 → 9). Power depends only on cost. Two cards of the same cost have the same base power, whatever their fame. Inflating stats (forged snapshots, template shopping) only moves a card up the curve. It never makes a card more efficient.

1.4 Home stat

home = the stat with the highest pct_s. Ties are broken in this order: depth, reach, attention. Depth and reach are the hardest to inflate. A null stat can never be home. When a card is in a Topic whose stat equals its home, it gets +onTopicBonus[cost] power (default [0, 1, 1, 2, 2, 3, 3], i.e. ⌈cost/2⌉). On-topic efficiency is then about 2 power per energy at every cost (2.0 / 1.5 / 2.0 / 1.75 / 2.0 / 2.0). Off-topic, cheap cards are weaker (1.0) than expensive ones (1.5). Cheap cards want their Topic, and big cards are flexible.

1.5 Faction

faction = the card's category (Space, Nature, People, Science, History, Culture), from server/wiki.ts. Culture is about half the pool, so faction keywords are written so that a mono-faction deck gains no consistency edge (see §10, and factionSynergyCap in §9).

1.6 Trend (live, small, capped)

trend = +1 if live.trendPercent ≥ trendUp (default 25), −1 if ≤ trendDown (default −25), otherwise 0. A null value gives 0. The host computes it once at match start, and it is frozen for the match. It shows as an arrow (▲/▼), not a number. It adds to power in every Topic.

1.7 Rarity

The hash-derived rarity (shared/protocol.ts:38) is cosmetic in v1 (frame colour). Mining luck must not become power.

1.8 Keyword

Each card has at most one keyword, chosen deterministically from faction, home stat and rarity by the table in §10 (owned by designer B).

1.9 Card face (phone)

The card face shows cost (top-left), power (big, centre; the bonus shows as a "+N" badge on the home icon when the card is on-topic), a home-stat icon (📣 attention / 📚 depth / 🌐 reach), an optional trend arrow, and one keyword word. That is two numbers, plus the live lane power when the card is on the board.

1.10 Plausibility (anti-forgery, off-chain)

When verifyStats is true (the default for hosted matches), the match host checks each owned card's snapshot before the match: pageBytes against that revision's byte size, languageCount ≤ the live count + 5, and views for the snapshot month within ±10 % of the pageviews API. A card that fails is played with its live values. The host replaces snapshot with a snapshot built from the live values (deriveStats on the live bytes, languages and views) before it builds the CardInput. The match log marks the card unverified. The engine does no I/O and only ever sees one version of each card.

  • Caching: results are cached per (pageId, revisionId, snapshotMonth). They are immutable, so a cached pass or fail never expires. Live values for a failed card are cached for 24 h.
  • API failure: fail open. If Wikipedia can't be reached and nothing is cached, the snapshot is used as-is and the log marks it unchecked. This is acceptable because forged stats only move a card up the cost curve (§1.3). They don't make it stronger per energy, so an outage must not block matches.

2. Decks

  • Deck size: exactly deckSize cards (default 12).
  • Copies: at most maxCopiesPerPage cards with the same pageId (default 2). Owned and loaner copies count together. Each copy keeps its own snapshot, so the two copies may differ in cost.
  • Owned cards: any card the player's wallet owns at match start. Ownership is read off-chain. The match never moves, locks or burns a card.
  • Loaner cards: off-chain preview cards with a fixed CardInput, shipped with the game data (docs/game/starter-cards.json, picked by council-data: about 24 pageIds across all 6 categories, with frozen, hand-checked snapshot stats, including the 4 cards in shared/catalog.ts). Loaners follow the same derivation, so they are no weaker or stronger than owned cards.
  • Starter decks: starterDecks (default: 4 fixed 12-card loaner decks). Each one has two leading factions and an average cost of 3.0–3.3. A new player picks one and can play at once.
  • Mixed decks: an owned deck may fill any slots with loaners, up to maxLoaners (default 12, which means no limit). Owning NFTs gives variety, not power: owned and loaner cards follow the same curve.

3. Board

  • 3 Topics (lanes), numbered 1–3 from left to right (top to bottom in portrait).
  • Each Topic has a stat (attention, depth or reach) and an optional Portal modifier (§10.3).
  • Each player has at most laneCapacity cards per Topic (default 3). That gives 9 slots per side, which caps cheap-card flooding and fits 3 cards across a 360 px phone.
  • Topic pool: topicPool is a list of Topics, each { id, name, stat, portal | null }. The default pool has 9 Topics: 3 per stat, one plain and two with Portals. pool_s is the sub-list with stat s, in file order.
  • Topic draw (exact):
    • If distinctStats is true (the default): for each stat in the fixed order [attention, depth, reach], pick pool_s[floor(next() × len(pool_s))]. That uses 3 next() calls. Then Fisher–Yates the 3 picks into lanes 1–3 (i = 2, 1; j = floor(next() × (i+1))), which uses 2 calls.
    • If distinctStats is false: Fisher–Yates the whole pool (i from n−1 down to 1) and take the first topicCount entries as lanes 1–3.
  • Stats visible, Portals hidden: every Topic's stat is face-up from turn 1. Its Portal modifier is face-down until the start of turn portalReveal[i] (default [2, 3, 4]). You always know where your card is on-topic, but not what twist a lane will get.

4. Match setup (deterministic)

  1. The input is { seed: uint32, rules, players: [p0, p1] }, and each player's input is { id, deck: CardInput[12] }. Seat order is input order.
  2. RNG: mulberry32(seed). Every random choice draws next() in this fixed order:
    1. shuffle p0's deck (Fisher–Yates, i from n−1 down to 1, j = floor(next() × (i+1)))
    2. shuffle p1's deck the same way
    3. draw and shuffle the Topics
    4. the initiative coin: p0 has initiative on odd turns if next() < 0.5, otherwise p1
    5. later random events (keywords only), in resolution order
  3. Each player draws openingHand cards (default 3). There are no mulligans in v1 (mulligan: false).
  4. Seed fairness (hosted PvP): commit–reveal. Each party i (host, p0, p1) sends sha256(r_i) for a random 32-byte r_i, then reveals r_i once all commits are in. seed = the first 4 bytes (big-endian uint32) of sha256(r_host ‖ r_p0 ‖ r_p1). The host still relays the hidden plans, so hosted PvP trusts the host not to leak them. Local and bot matches use any seed.

5. Turn structure

The match lasts turns turns (default 6, hard cap). Each turn has these phases:

  1. Start
    • Reveal any Portal scheduled for turn t (resolve its "on reveal").
    • Each player's energy = energyByTurn[t-1] + carry + bonusEnergy. Carry is min(energyCarryMax, unspent energy from last turn), default max 1. Saving one energy on turn 2 makes a turn-3 four-drop possible: a real tempo choice.
    • Each player draws 1 card if their deck isn't empty and their hand holds fewer than handLimit (default 7) cards. Otherwise they don't draw.
  2. Underdog check (comeback; underdog: true, from turn 2). A player who leads in 0 Topics while the opponent leads in ≥ 2 gets +1 energy this turn.
  3. Plan (simultaneous, hidden)
    • Each player queues an ordered list of plays (handIndex, topic).
    • Total cost must be ≤ their energy, and each Topic needs room on that player's side.
    • Plays can be undone freely until Commit. Passing is an empty commit.
    • The turn timer is turnSeconds (default 25). On timeout, whatever is queued is committed.
  4. Reveal (interleaved)
    • Plays reveal one at a time, alternating: the initiative player's 1st, the other player's 1st, the initiative player's 2nd, and so on. When one player runs out, the rest of the other's reveal in order.
    • Each card enters its Topic and its "on reveal" effect resolves at once.
    • So the order in which you queue cards matters: lead with the card you want resolved first.
    • A queued play that is no longer legal at reveal (the lane is full or the card was removed) goes back to hand and its energy is lost.
  5. End
    • Recompute all Topic powers (§6).
    • End-of-turn effects resolve, the initiative player's first.
    • Initiative strictly alternates each turn (set by the coin in §4). This is simple, it's fair to both seats, and it doesn't depend on the board.

A typical turn is: look at the lanes, tap a card, tap a Topic (×1–3), tap Commit. That is under 10 seconds, done with one thumb, with no dragging.


6. Power and Topic control

  • A card's lane power = power + (onTopicBonus[cost] if its home stat is the Topic's stat) + trend
    • keyword and Portal modifiers. It is never below 0.
  • A player's Topic power = the sum of their cards' lane power in that Topic.
  • A player leads a Topic if their Topic power is strictly greater than the opponent's.
  • Consensus tie-break: if the powers are equal and > 0, the player with more on-topic cards there leads. If that is also equal, nobody leads. 0–0 has no leader.

7. Win conditions and tie-breaks

At the end of the last turn:

  1. The player who leads more Topics wins (2–1, 2–0, 1–0 and 3–0 all count).
  2. If they lead the same number of Topics: the higher total power across all Topics wins.
  3. If that is also equal: the match is a draw.

Concede: a player can concede at any time, and the opponent wins at once. A player who misses afkTurns timeouts in a row (default 2) with nothing queued concedes.


8. Degenerate lines and why they fail (for the critic)

Line Why it isn't dominant
All-famous (all max-stat) deck It becomes an all-cost-5/6 deck: nothing to play on turns 1–4. On-topic power per energy is about 2.0 at every cost (§1.4), so being famous buys flexibility, not efficiency.
All-cheap flood (cost 1–2) It has to be on-topic to be efficient (off-topic it gets 1.0 power per energy against 1.5 for big cards), and 9 slots run out. sim-balance: please test all cost-1/2 decks explicitly.
All one faction Faction synergies are capped (factionSynergyCap), and Culture is the largest pool but has the weakest synergy keywords (§10).
"Always play the highest-power card" It ignores on-topic +2 (about 40% of a cheap card's power), lane capacity, and the face-down lanes. Target: < 55% against the sim's smart bot.
Stall or pass Passing leaves lanes to any 1-power card. Two passing players draw.
Mirror the AI Hidden simultaneous commits: you only see the opponent's cards after you commit.
Seat or initiative Planning is simultaneous and initiative strictly alternates (each seat has it for 3 of the 6 turns). Target: each seat wins 48–52%.
Forged or shopped stats They only raise cost (§1.3), the host check falls back to live stats (§1.10), and trend is capped at ±1.
Inflated live pageviews Worth at most +1, and frozen at match start.
Swinginess No effect may change a lane by more than 6 power or move cards between lanes in v1 (a keyword-design rule for §10).

9. Rules config (all defaults)

The engine takes a RulesConfig object. Peer-hosted modes override it (§11). Defaults:

{
  "version": "1.0",
  "deckSize": 12, "maxCopiesPerPage": 2, "maxLoaners": 12,
  "openingHand": 3, "handLimit": 7, "mulligan": false,
  "turns": 6, "turnSeconds": 25, "afkTurns": 2,
  "energyByTurn": [1, 2, 3, 4, 5, 6], "energyCarryMax": 1, "bonusEnergy": 0, "underdog": true,
  "topicCount": 3, "distinctStats": true, "portalReveal": [2, 3, 4], "laneCapacity": 3,
  "topicPool": "default",
  "costThresholds": [15, 35, 55, 75, 90],
  "powerByCost": [0, 1, 2, 4, 5, 7, 9],
  "onTopicBonus": [0, 1, 1, 2, 2, 3, 3],
  "trendUp": 25, "trendDown": -25,
  "factionSynergyCap": 3,
  "verifyStats": true,
  "percentiles": "card-sample-2026-11-16",
  "starterDecks": "default"
}

What modes may vary: every key above, plus topicPool contents and the starter-deck lists. Fixed for all modes: matches are off-chain and never move or burn NFTs; the RNG and its draw order (§4); the shape of the derivation (§1: percentile → fame → cost → power); at most one keyword per card; the phases of a turn (§5). A mode must keep turns × turnSeconds ≤ 240 so that matches stay within 3–6 minutes.


10. Keywords (owner: council-designer-b)

To be written by council-designer-b. Constraints from the rules above:

  • one keyword per card, one word, no more than one short line of reminder text
  • triggers are limited to: on reveal, ongoing, end of turn
  • keywords change power only (no stealing, moving cards between lanes or removing cards in v1)
  • no single effect may swing a lane by more than 6
  • each faction gets a keyword pool; Culture's has the lowest synergy ceiling
  • §10.3 Portals: the Topic modifiers in topicPool

11. Peer-hosted modes (owner: council-designer-b)

To be written by council-designer-b. A mode is a named RulesConfig override, plus a Topic pool and optional starter decks.

12. Worked example match (owner: council-designer-b)

To be written by council-designer-b.