Files
wikideck/docs/game/DESIGN.md
T
claudeandClaude Opus 5.5 95936d488a 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>
2026-11-16 22:50:12 -05:00

20 KiB
Raw Blame History

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.