From ac462985943e686ccf75d8c5a5fe5b3d6bf2063c Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 16 Nov 2026 22:54:08 -0500 Subject: [PATCH] docs(game): critic M1-M4, S1-S5 Co-Authored-By: Claude Opus 5.5 --- docs/game/DESIGN.md | 50 ++++++++++++++++++++++++++++++--------------- 1 file changed, 34 insertions(+), 16 deletions(-) diff --git a/docs/game/DESIGN.md b/docs/game/DESIGN.md index 7666545..d1b8056 100644 --- a/docs/game/DESIGN.md +++ b/docs/game/DESIGN.md @@ -29,6 +29,14 @@ not upgrades. | 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) | — | +**What is ours, not borrowed:** +- (a) each Topic is judged on one Wikipedia stat (the Top Trumps twist) +- (b) cost comes from an article's fame instead of being printed +- (c) a trend arrow driven by live pageviews +- (d) a total-power and consensus tie-break instead of stakes betting +- smaller choices: 3 slots per lane, 1 carried-over energy, interleaved reveals, and stats visible + from turn 1 with hidden Portals + 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. @@ -43,7 +51,8 @@ The engine never reads raw 0–100 stats as power. Every game card is derived ** ``` CardInput = { cardId, pageId, title, category, rarity, snapshot: MintStatsSnapshot, // at mint, immutable - live: { trendPercent: number | null } } // frozen at match start + live: { trendPercent: number | null, dailyAverage: number | null }, // frozen at match start + check: 'verified' | 'unverified' | 'unchecked' | 'loaner' } // set by the host (§1.10) ``` ### 1.1 Percentiles (rank-normalisation) @@ -61,7 +70,8 @@ The defaults aim at a pool cost spread of about 15/20/20/20/15/10 %. They are re sample's fame distribution. ### 1.3 Power -`power` = `powerByCost[cost]`, default `[_, 1, 2, 4, 5, 7, 9]` (cost 1 → 1 … cost 6 → 9). +`power` = `powerByCost[cost]`, default `[_, 1, 2, 4, 6, 8, 10]` (cost 1 → 1 … cost 6 → 10). The +critic's sim showed that heavy decks were too weak with `[…5,7,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. @@ -82,7 +92,8 @@ mono-faction deck gains no consistency edge (see §10, and `factionSynergyCap` i ### 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 +otherwise 0. A `null` value gives 0. Trend also needs `live.dailyAverage ≥ trendMinDaily` (default +**20**), because percentages on tiny articles are noise; otherwise trend is 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 @@ -109,9 +120,12 @@ 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. +- **Card can't be verified** (the pageId or revision doesn't exist, or the title or category doesn't + match): the card is **rejected at deck validation**, and the player is asked to swap in a loaner. +- **API failure:** if Wikipedia can't be reached and nothing is cached, the card plays from its snapshot + with `check: 'unchecked'`. The engine then caps its cost at `uncheckedCostCap` (default **4**), and + power follows the capped cost. Matches are never blocked. +- The engine's only use of `check` is that cost cap. Loaner cards are `check: 'loaner'`. --- @@ -120,6 +134,8 @@ The engine does no I/O and only ever sees one version of each card. - **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. +- **Deck validation** (engine): the size is right, the copy limit holds, every card's `check` is + valid, and there are no more loaners than `maxLoaners`. An invalid deck can't start a match. - **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 @@ -187,8 +203,9 @@ The match lasts `turns` turns (default **6**, hard cap). Each turn has these pha 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. +2. **Underdog check** (mode option, `underdog: false` by default, because it can be sandbagged). When + it's on, 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. @@ -205,8 +222,9 @@ The match lasts `turns` turns (default **6**, hard cap). Each turn has these pha 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. + - Initiative strictly **alternates** each turn (set by the coin in §4). + - Plans are locked before anything reveals, so initiative gives away no information. It only + decides the order of on-reveal effects. §10 includes keywords where that order matters. 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. @@ -240,15 +258,15 @@ At the end of the last turn: | 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-famous (all max-stat) deck | It becomes an all-cost-5/6 deck with dead early turns. Cheap cards are more efficient **per energy**, expensive cards **per card**. Only 9 cards are seen per match (3 + 6 draws), so both matter. The 1-energy carry-over lets a heavy deck bank energy for a turn-5 six-drop. **sim-balance target: heavy vs curve ≥ 40%.** | +| All-cheap flood (cost 1–2) | It runs out of cards (only 9 seen), and its on-topic bonus is only +1. The critic's sim had swarm vs curve at 42%. **sim-balance: test all cost-1/2 decks.** | | 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. | +| Inflated live pageviews | Worth at most +1, frozen at match start, and only counts for articles with ≥ 20 views a day. | | 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). | --- @@ -263,13 +281,13 @@ The engine takes a `RulesConfig` object. Peer-hosted modes override it (§11). D "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, + "energyByTurn": [1, 2, 3, 4, 5, 6], "energyCarryMax": 1, "bonusEnergy": 0, "underdog": false, "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], + "powerByCost": [0, 1, 2, 4, 6, 8, 10], "onTopicBonus": [0, 1, 1, 2, 2, 3, 3], - "trendUp": 25, "trendDown": -25, + "trendUp": 25, "trendDown": -25, "trendMinDaily": 20, "uncheckedCostCap": 4, "factionSynergyCap": 3, "verifyStats": true, "percentiles": "card-sample-2026-11-16",