From 01b83f9c9f4e2bdf15996ba506e5a2e771a1df56 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 22:48:43 -0500 Subject: [PATCH] docs(game): DESIGN.md v1 draft rules sections (council-designer-a) Co-Authored-By: Claude Opus 5.5 --- docs/game/DESIGN.md | 272 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 272 insertions(+) create mode 100644 docs/game/DESIGN.md diff --git a/docs/game/DESIGN.md b/docs/game/DESIGN.md new file mode 100644 index 0000000..ea5b510 --- /dev/null +++ b/docs/game/DESIGN.md @@ -0,0 +1,272 @@ +# 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). There are 6 turns, both players play at the same time, and energy ramps from 1 to 6. +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 revealed over time | lanes, 6 turns, ramp 1→6, simultaneous reveal, staggered lane reveal, small deck | cube betting ("snap") is left to modes; it needs ranked stakes | +| 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.`. 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`** power (default +**+2**). + +### 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), 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 **as if its snapshot were its live values**, and the match log marks it. +The engine itself does no I/O: it receives already-checked `CardInput`s. + +--- + +## 2. Decks + +- **Deck size:** exactly `deckSize` cards (default **12**). +- **Copies:** at most `maxCopiesPerPage` cards with the same `pageId` (default **2**). 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 + (`shared/game/loaners.json`). They are drawn from `shared/catalog.ts` and council-data's sample. + 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 **4**). +- **Topic draw:** at match start, `topicCount` (3) Topics are drawn without replacement from + `topicPool`. The default pool has 9 Topics: each stat 3 times, one plain and two with Portals. + If `distinctStats` is true (the default), the draw is redone until the 3 Topics have 3 different + stats. In practice the engine draws one Topic per stat and then shuffles the lane order. +- **Staggered reveal:** Topic *i* is face-down until the start of turn *i* (`revealSchedule`, default + `[1, 2, 3]`). Cards can be played into a face-down Topic: that is the risky, on-topic gamble. + +--- + +## 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 turn 1 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`). + +--- + +## 5. Turn structure + +The match lasts `turns` turns (default **6**, hard cap). Each turn has these phases: + +1. **Start** + - Reveal Topic *t* if it is scheduled (resolve its Portal "on reveal"). + - Each player gets `energy = t + bonusEnergy` (energy does not carry over). + - 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** + - The player with **initiative** reveals all their queued cards in queue order, then the other + player reveals theirs. + - Each card enters its Topic and its "on reveal" effect resolves at once. + - 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. + - Set initiative for the next turn: the player who leads in more Topics. If they lead in the same + number, the player who did *not* have initiative this turn. So reveal order alternates when the + game is even, and the leader reveals first (and gives away information) when it isn't. + +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` 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. 0–0 and + other ties have no leader. +- Face-down Topics have no stat yet, so on-topic bonuses there count as 0 until the Topic is revealed. + +--- + +## 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, so it gives up 2 Topics early. Power per energy is flat across the curve (`powerByCost` is tuned for this in sim). | +| 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 | Turns are simultaneous. Initiative alternates when the game is even and goes to the leader otherwise. 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: + +```json +{ + "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], "bonusEnergy": 0, "underdog": true, + "topicCount": 3, "distinctStats": true, "revealSchedule": [1, 2, 3], "laneCapacity": 4, + "topicPool": "default", + "costThresholds": [15, 35, 55, 75, 90], + "powerByCost": [0, 1, 2, 4, 5, 7, 9], + "onTopicBonus": 2, + "trendUp": 25, "trendDown": -25, + "factionSynergyCap": 3, + "verifyStats": true, + "percentiles": "card-sample-2026-11-16", + "starterDecks": "default" +} +``` + +(`energyByTurn[t-1]` replaces "energy = t" in §5 so that modes can change the ramp.) + +--- + +## 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.*