From 95936d488a6ce46af7be96b3787f20d124d2342d Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 22:50:12 -0500 Subject: [PATCH] docs/game/DESIGN.md: v1 draft (council-designer-b) Full draft so the engine has a concrete target: 3-lane 6-round 'Topics' game. designer-b sections complete: card->game mapping, 9 keywords with examples, Ruleset mode parameters, 3 loaner starter decks, worked example match. Core rules (s2-5) are a proposal for designer-a to revise. Status: Gitea MCP down on imac, so I can't comment or open a PR. Refs #1. Co-Authored-By: Claude Opus 5.5 --- docs/game/DESIGN.md | 303 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 303 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..5d539bf --- /dev/null +++ b/docs/game/DESIGN.md @@ -0,0 +1,303 @@ +# WikiDeck: game design (v1 draft) + +Status: **v1 draft by council-designer-b**, for council-designer-a and council-critic to revise before the +23:30 freeze. Ownership inside this file (issue #1): + +- **designer-a:** research summary, core rules (§2 to §5). The core rules below are designer-b's proposal so the + engine has something concrete. Designer-a may replace them. +- **designer-b:** card mapping and keywords (§6, §7), mode parameters (§8), starter decks (§9), worked example (§10). +- **critic:** §11 (open risks). + +Numbers marked **[tune]** are defaults to recalibrate from `docs/game/CARD_DATA.md` and `docs/game/BALANCE.md`. + +--- + +## 1. Pitch + +**Topics** is a 3-lane, 6-round card battle. Each article is a unit you commit to one of three *Topics*. After +round 6 you win by holding **2 of 3 Topics**. Both players plan their plays at the same time, and plays are revealed +in a fixed order. A match runs about 3–5 minutes, and every turn is "tap a card, tap a lane, End Turn", so it works +one-handed on a phone. + +Mechanics borrowed by genre, and why: +- Lanes, a fixed round count and simultaneous planning (as in many lane battlers) give short matches, low downtime, and comebacks in the last round. +- A mana curve where energy equals the round number (as in many TCGs) means nobody needs land or resource cards. +- Top Trumps–style stats that come straight from data: the card *is* its Wikipedia numbers. +- Small fixed decks (12 cards) keep deckbuilding quick, and a full draw by round 6 keeps variance moderate. + +## 2. Components + +- **Card**, as the game sees it. Derived deterministically from card data, see §6: + `{ id, pageId, title, faction, cost (1–6), power (1–12), keyword | null, keywordValue? }` +- **Topic** (lane): `{ id, name, faction | null, rule | null }`. 3 per match. +- **Deck:** exactly `deckSize` (12) cards, at most `maxCopies` (2) with the same `pageId`. +- **Seed:** a 32-bit unsigned integer. All randomness (shuffles, topic draw, random targets) comes from one + seeded PRNG (engine's choice, e.g. mulberry32 or sfc32), consumed in the order this document specifies. + +## 3. Setup + +1. Pick the 3 Topics: shuffle the mode's topic pool with the PRNG and take the first `topicsPerMatch`. +2. Shuffle each deck with the PRNG: player 1's deck first, then player 2's. +3. Each player draws `startingHand` (3) cards. +4. Initiative for round 1 goes to the player chosen by `prng() < 0.5 ? P1 : P2`. + +## 4. Round structure (rounds 1 to `rounds`, default 6) + +1. **Draw:** each player draws 1 card (skip it if the deck is empty; hand size is capped at `maxHand` (7), and an over-cap draw is discarded). +2. **Energy:** each player's energy = `energyByRound[round-1]` (default `[1,2,3,4,5,6]`). Unspent energy is lost. +3. **Plan:** both players pick plays in secret, as an ordered list of `(cardId, topicId)` pairs. A play is legal if its + card is in hand, the running cost total is ≤ energy, and the player's side of that Topic holds fewer than `laneCap` (4) cards, counting earlier plays this round. +4. **Reveal:** the initiative player's plays resolve first, in order, then the other player's. + Each played card enters its Topic face up, and its *On Reveal* effect (if any) resolves at once. +5. **End of round:** *End of Round* effects resolve (initiative player first, then lanes left to right, then cards in the order they were played). +6. **Initiative** for the next round goes to the player currently winning more Topics. If tied, it stays with the player who has it. + Plans are secret, so initiative gives no information. It only sets resolution order: the trailing player resolves + **second**, so their conditional On Reveal effects (e.g. Nostalgic) see the leader's new cards. That's a soft comeback mechanic. + +## 5. Winning + +After the last round's End of Round step: +1. A Topic is won by the side whose cards there have the higher **total power** (power never drops below 0). +2. Winning more Topics wins the match. +3. Tie-break 1: the higher total power across all Topics. +4. Tie-break 2: a **draw**. There's no random tie-break, so a draw stays a draw for both players. + +Concession is allowed at any time and counts as a loss. Matches have no stakes: nothing moves on-chain. + +--- + +## 6. From card data to game card (designer-b) + +All inputs come from the card's **at-mint snapshot** (`MintStatsSnapshot`), which is immutable, so a card plays the +same forever and two copies of one article minted at different times can differ, which gives each copy its identity. Live values +are used only by the *Trending* keyword (§7), and they're captured into the match setup so replays stay +deterministic. Preview and loaner cards (§9) carry fixed stats. + +Let `A = stats.attention ?? 0`, `D = stats.depth`, `R = stats.reach`, `T = pageviews.trendPercent` (it may be null). + +### 6.1 Power and cost +``` +raw = 0.5*D + 0.3*A + 0.2*R // 0..100 [tune weights] +power = clamp(1, 12, round((raw - 20) / 6)) // [tune offset/scale] +cost = clamp(1, 6, ceil(power / 2)) // about 2 power per energy +``` +After the keyword is assigned (6.3), apply its **budget**: `power = max(1, power + keywordPowerDelta)`. +Cost is never changed, so cost stays readable as "how big the article is". + +Why these weights: `depth` (log page size) has a narrow spread on real articles, about 55–85, so it alone would +make every card the same. `attention` and `reach` spread widely, so they add variance. The calibration goal for +`CARD_DATA.md`: across a random sample, cost should be roughly 1:15%, 2:25%, 3:25%, 4:20%, 5:10%, 6:5%. +Tune `offset/scale` until it is. + +### 6.2 Faction (from categories) +Match the card's `categories[]` (lower-cased) against each faction's substring list. The faction with the most +matching categories wins. Ties go to the earlier faction in the table, and zero matches gives **Miscellany**. + +| Faction | Substrings [tune with council-data's top categories] | +|---|---| +| People | `births`, `deaths`, `living people`, `people from`, `alumni`, `politicians`, `musicians`, `actors`, `writers` | +| Places | `populated places`, `villages`, `cities`, `towns`, `rivers`, `mountains`, `islands`, `geography of`, `buildings and structures`, `municipalities` | +| History | `history of`, `wars`, `battles`, `conflicts`, `century in`, `establishments`, `disestablishments`, `dynasties`, `empires` | +| Science | `species`, `genera`, `taxa`, `biology`, `physics`, `chemistry`, `mathematics`, `astronomy`, `medicine`, `diseases`, `minerals` | +| Culture | `films`, `albums`, `songs`, `novels`, `television`, `video games`, `paintings`, `music`, `books`, `artworks` | +| Sport | `football`, `olympic`, `sports`, `players`, `cricket`, `basketball`, `baseball`, `athletes`, `seasons`, `clubs` | +| Society | `companies`, `organizations`, `political parties`, `religion`, `law`, `schools`, `universities`, `government`, `economy` | + +Note: `establishments` (e.g. "1901 establishments in Norway") is very common across all kinds of articles. If council-data shows it dominating, drop it. +Wikidata `instance of` (P31) would be a cleaner signal, but the node doesn't fetch it today (only `wikidataId`). +That's a v2 option: a P31 class to faction table, with categories as the fallback. + +### 6.3 Keyword assignment +Each card gets **at most one** keyword. That's deliberate: a phone card fits one line of rules text. Rules are checked top to +bottom, and the first match wins. Thresholds are **[tune]**: they aim for each keyword to be on about 5–12% of cards, and +about 40% of cards to be vanilla (high power for their cost). + +| # | Condition (snapshot unless stated) | Keyword | Power delta | +|---|---|---|---| +| 1 | Two or more copies of the same `pageId` in the deck (checked at deck build) | **Edition** | −1 | +| 2 | `R ≥ 70` (about 150+ language editions) | **Translated** | −2 | +| 3 | `A ≥ 80` (about 2.5M+ views a month) | **Viral** | −2 | +| 4 | `T ≥ +40` | **Rising** | −2 | +| 5 | `T ≤ −40` | **Nostalgic** | −1 | +| 6 | `D ≥ 85` (about 130 KB+) | **Encyclopedic** | −1 | +| 7 | `A ≤ 25` (about 30 or fewer views a month), or attention null | **Obscure** | 0 | +| 8 | `R ≤ 10` (one language edition only) | **Local** | 0 | +| 9 | faction is Miscellany and none of the above | **Wildcard** | −1 | +| 10 | otherwise | none (vanilla) | 0 | + +**Trending (live overlay, optional, `liveTrending: true` by default):** when a match is created, the host reads each +deck card's *live* `trendPercent` and stores it in the match setup. A card whose live trend is ≥ +50 **and** whose live +attention is greater than its mint attention gets **+1 power** for this match, shown as a flame badge. This is the only +place live values matter. It rewards owning an article that's become popular since it was minted, but it's small enough +that it never decides a match by itself. + +## 7. Keywords (designer-b) + +Timing words: **On Reveal** (once, when the card enters play during Reveal), **Ongoing** (always on while it's in play), +**End of Round** (in step 4.5). "Here" means the card's Topic. "Allies" are your other cards. All targeting that +says "random" uses the match PRNG at the moment it resolves. + +| Keyword | Rules text (exactly as shown on the card) | Example | +|---|---|---| +| **Edition** | *Ongoing:* +2 power for each other copy of this article on your side (any Topic). | Two *Eiffel Tower* cards (power 5 after the −1) are in play: each is 7. | +| **Translated** | *On Reveal:* give +1 power to your first-played card in each *other* Topic (where you have one). | *Water* (power 4) is revealed in the left Topic, so your first cards in the middle and right Topics get +1 each. | +| **Viral** | *On Reveal:* add a 1-power *Mention* token (no keyword, no faction) to a random other Topic with space on your side. | *Taylor Swift* is revealed. The PRNG picks the right Topic, and a 1-power Mention appears there. If no Topic has space, nothing happens. | +| **Rising** | *End of Round:* +1 power (up to +3 total). | Played in round 2, a power-3 Rising card is 4, 5 and 6 at the ends of rounds 2, 3 and 4, then stays at 6. | +| **Nostalgic** | *On Reveal:* if you're losing here, +3 power. | The opponent has 8 here and you have 2. Your power-3 Nostalgic card checks first (2 < 8, so you're losing) and becomes 6. Your total is 8, which ties. | +| **Encyclopedic** | *Ongoing:* can't have its power reduced. Also *On Reveal:* if this is your only card here, +2 power. | A power-7 Encyclopedic card opens an empty Topic and becomes 9. | +| **Obscure** | *Ongoing:* the opponent sees this card face down (as "?") until the end of the match. | *Pond snail of Lake X* shows as "?" on the opponent's screen. The final count reveals it. | +| **Local** | *Ongoing:* +2 power while it's in a Topic that matches its faction. | A Places card with power 2, Local, in the "Places" Topic is 4. | +| **Wildcard** | *On Reveal:* this card's faction becomes the faction of the Topic it's in (if the Topic has one). | It's revealed in the "Science" Topic and becomes Science: it gets that Topic's affinity and counts for Local and Cluster effects. | + +**Topic affinity (not a keyword, but always on):** a card whose faction matches its Topic's faction gets +1 power. + +Obscure and hidden information: the engine keeps full state. The *view* for each player replaces opponent Obscure cards +with `{ hidden: true }` and leaves their power out of the visible lane totals. The UI shows the lane total as "≥ N". + +Engine notes: +- Power is `basePower + Σ modifiers`, clamped at 0 when it's read. Keep modifiers as a list, so Encyclopedic can + ignore negative ones and the UI can explain the numbers. +- v1 has no negative effects, so Encyclopedic's first clause only matters for modes and future keywords. Implement it anyway. +- Resolution order is fully specified in §4, so effects never need a stack. + +## 8. Configurable by peer-hosted modes (designer-b) + +A mode is a JSON `Ruleset` (engine-a owns the TypeScript type in `shared/game/`). Everything below is data, and a mode +may override any field. Unknown fields are rejected, and every value is range-checked so a hostile mode can't hang a client. + +| Field | Type | Default | Allowed range | +|---|---|---|---| +| `name`, `description` | string | "Standard" | ≤ 40 / ≤ 280 chars | +| `rounds` | int | 6 | 3–10 | +| `energyByRound` | int[] | `[1,2,3,4,5,6]` | length = `rounds`, each 0–10 | +| `topicsPerMatch` | int | 3 | 1–5 (odd is recommended) | +| `topicPool` | Topic[] | the 7 faction Topics | 1–20 entries, at least `topicsPerMatch` | +| `laneCap` | int | 4 | 1–8 | +| `deckSize` | int | 12 | 6–30 | +| `maxCopies` | int | 2 | 1–4 | +| `startingHand` | int | 3 | 0–7 | +| `maxHand` | int | 7 | 1–10 | +| `statWeights` | `{attention, depth, reach}` | `{0.3,0.5,0.2}` | each 0–1 | +| `powerFormula` | `{offset, scale, min, max}` | `{20, 6, 1, 12}` | scale > 0 | +| `costCurve` | `{divisor, min, max}` | `{2, 1, 6}` | | +| `keywordRules` | ordered list `{keyword, condition, powerDelta}` | table in §6.3 | keyword ∈ the v1 set; conditions are a tiny `{stat, op, value}` form | +| `keywordsEnabled` | string[] | all | subset of the v1 set | +| `factions` | `{name, substrings[]}`[] | table in §6.2 | 1–12 | +| `affinityBonus` | int | 1 | 0–5 | +| `liveTrending` | bool | true | | +| `allowedCards` | `"any" \| "starters" \| {factions?: string[], maxCost?: int}` | `"any"` | | +| `winCondition` | `"majority"` or `"totalPower"` | `"majority"` | | + +`Topic.rule` (optional, used in modes only; the Standard pool has none): +`{ kind: "powerBonus", amount, when?: "lastRound" }`, `{ kind: "laneCap", value }`, +`{ kind: "costMod", amount }` (cards here cost ±N, min 0). + +Mode ideas the node operators get for free: +- **Blitz:** `rounds 4`, `energyByRound [2,3,4,5]`, `deckSize 8`. About 2 minutes. +- **Deep Cuts:** `statWeights {attention:0, depth:0.8, reach:0.2}`, so obscure long articles shine. +- **Faction Draft:** `allowedCards {factions:["Science","Places"]}`, `topicPool` with only those factions. +- **Main Page:** a Topic with `{kind:"powerBonus", amount:3, when:"lastRound"}`. + +A mode is validated, then hashed (canonical JSON, SHA-256), and the hash goes into the match record with the seed, so a +match is reproducible from `(rulesetHash, seed, deck lists, live-trend snapshot, both players' plan lists)`. + +## 9. Starter decks: new players play right away (designer-b) + +New players own no cards. They pick one of **three loaner starter decks**. Loaner cards are plain data in `shared/game/` +(engine-b), with **fixed game stats** (not derived), marked `loaner: true`, and with no chain identity. They never touch the +chain, can't be traded, and are shown with a "Preview" ribbon. A player who owns cards can mix up to +`deckSize` of them into a starter list (owned cards replace loaners one for one in the deck builder). Mode `allowedCards: "starters"` gives +a level field. + +Each deck has 12 cards, 2 copies at most, and a curve of 1:2, 2:3, 3:3, 4:2, 5:1, 6:1, about 50 power in total. That's a little under +a typical owned deck (vanilla power is about 2 × cost), so owned cards feel like an upgrade without being required. Editions in starters are +flagged as pairs, and the Edition rule applies to them as normal. + +**Deck A: "Wonders" (Places and History, go-wide)** + +| Title | Faction | Cost | Power | Keyword | +|---|---|---|---|---| +| Stonehenge | History | 1 | 2 | – | +| Mount Fuji | Places | 1 | 1 | Local | +| Great Wall of China | Places | 2 | 2 | – | +| Petra | Places | 2 | 2 | Local | +| Roman Empire | History | 2 | 2 | Translated | +| Machu Picchu ×2 | Places | 3 | 4 | Edition | +| Battle of Hastings | History | 3 | 4 | Nostalgic | +| Venice | Places | 4 | 5 | Translated | +| Ancient Egypt | History | 4 | 6 | – | +| Amazon River | Places | 5 | 8 | – | +| World War II | History | 6 | 10 | Encyclopedic | + +**Deck B: "Lab" (Science, tall and growing)** + +| Title | Faction | Cost | Power | Keyword | +|---|---|---|---|---| +| Tardigrade | Science | 1 | 1 | Rising | +| Axolotl | Science | 1 | 2 | – | +| Photosynthesis | Science | 2 | 2 | Local | +| Black hole | Science | 2 | 2 | Viral | +| Periodic table | Science | 2 | 3 | – | +| DNA | Science | 3 | 3 | Translated | +| Theory of relativity | Science | 3 | 4 | Rising | +| Penicillin | Science | 3 | 5 | – | +| Mars ×2 | Science | 4 | 6 | Edition | +| Evolution | Science | 5 | 7 | Encyclopedic | +| Universe | Science | 6 | 9 | Translated | + +(Mars ×2 counts as 2 of the 12 cards. The curve is 1:2, 2:3, 3:3, 4:2, 5:1, 6:1.) + +**Deck C: "Headliners" (Culture, People and Sport, tempo and hype)** + +| Title | Faction | Cost | Power | Keyword | +|---|---|---|---|---| +| Chess | Sport | 1 | 2 | – | +| Mona Lisa | Culture | 1 | 1 | Viral | +| The Beatles | Culture | 2 | 2 | Viral | +| Marie Curie | People | 2 | 3 | – | +| FIFA World Cup | Sport | 2 | 2 | Rising | +| Hamlet | Culture | 3 | 4 | Nostalgic | +| Olympic Games ×2 | Sport | 3 | 4 | Edition | +| Leonardo da Vinci | People | 4 | 5 | Translated | +| Star Wars | Culture | 4 | 6 | – | +| Wolfgang Amadeus Mozart | People | 5 | 8 | – | +| William Shakespeare | People | 6 | 9 | Encyclopedic | + +Counts: deck A lists 11 rows, with Machu Picchu as 2 cards, so 12 cards. Deck C does the same with Olympic Games. +Stats are hand-tuned for loaners, not derived from live data, so they're fixed, readable and balance-testable. sim-balance should +run A vs B vs C round robin first. The target is each pairing at 45–55%. + +**Tutorial (ui-a):** the first match is Deck A vs an easy bot playing Deck B, with seed fixed at 1 so the tutorial script +is the same every time. + +## 10. Worked example (designer-b) + +Standard ruleset. Seed fixed. P1 plays Deck A (Wonders) and P2 plays Deck B (Lab). +Topics drawn: **left: Places**, **middle: Science**, **right: History**. Each gives +1 to matching-faction cards. +The power shown includes all bonuses. Initiative in round 1 goes to P1. + +| Round | Energy | P1 plays (resolves first if initiative) | P2 plays | Lanes after round (P1 – P2) | Initiative next | +|---|---|---|---|---|---| +| 1 | 1 | Mount Fuji → left. Local +2 and affinity +1: **4** | Tardigrade → middle. Affinity +1: 2. End of Round, Rising: **3** | L 4–0, M 0–3, R 0–0 | tied 1–1, stays P1 | +| 2 | 2 | Roman Empire → right. Affinity: 3. Translated: +1 to P1's first card in each other lane with one, so Fuji **5**. (P1 has nothing in middle) | Black hole → middle. Affinity: 3. Viral: a Mention (1) goes to a random other Topic with space, and the PRNG picks left. Rising Tardigrade: **4** | L 5–1, M 0–7, R 3–0 | P1 leads 2–1, so P1 | +| 3 | 3 | Battle of Hastings → middle. P1 is losing middle 0 vs 7, so Nostalgic +3: **7** | Penicillin → right. 5 (no affinity). End of Round, Rising: Tardigrade **5** (the +3 cap is now reached) | L 5–1, M 7–8, R 3–5 | P2 leads 2–1, so P2 | +| 4 | 4 | Venice → left. Affinity: 6. Translated: middle Hastings 8, right Roman Empire 4 | Mars → middle. Affinity: 7 (Edition +0, the other copy isn't in play). Tardigrade stays 5 (capped) | L 11–1, M 8–15, R 4–5 | P2 still leads (M, R), so P2 | +| 5 | 5 | Amazon River → right. 8 (no affinity) | Mars → right. 6, and Edition now gives +2 to each Mars: middle Mars 9, right Mars 8 | L 11–1, M 8–17, R 12–13 | P2 | +| 6 | 6 | (resolves second) World War II → right. Affinity 11. Encyclopedic: not the only card here, so no bonus | (resolves first, has initiative) Universe → left. 9 (no affinity). Translated: +1 to P2's first card in middle (Tardigrade 6) and right (Penicillin 6) | **L 11–10, M 8–18, R 23–14** | – | + +Result: P1 wins left and right, so **P1 wins 2–1**. The key moment was round 6. Both players planned blind: P2 guessed P1 would +contest the left lane and spent Universe there, falling 1 short. P1 guessed right and put World War II in the right lane. +Mid-game, P2 looked like the winner (2–1 from round 3 on). The last-round double commit is where most matches are decided, +which keeps them tense to the end. +The engine's golden test for this example: with the same seed and the same plan lists, the final lane totals are exactly +`[11,10] [8,18] [23,14]`. + +(Engine team: the Viral target in round 2 depends on the PRNG. In the test, fix it by asserting the +Mention's lane is the one the PRNG chose, and recompute the totals from there. The table assumes left.) + +## 11. Open risks (for council-critic) + +- Edition rewards duplicate mints. Is that good (owning two Eiffel Towers is fun) or pay-to-win? The cap is `maxCopies 2`. +- Obscure: hidden info on lots of low-traffic cards could feel random. If it's on more than 15% of cards, raise the threshold. +- The simultaneous plan step needs both players to commit before reveal in PvP (modes, server). Against a bot it's trivial. +- Card data has no P31 type yet, so factions are a category heuristic. Expect around 20% Miscellany.