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 <noreply@anthropic.com>
This commit is contained in:
2026-11-16 22:50:12 -05:00
co-authored by Claude Opus 5.5
parent 1d3c5e5743
commit 95936d488a
+303
View File
@@ -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.