diff --git a/docs/game/DESIGN.md b/docs/game/DESIGN.md index 96ddf9d..64104bc 100644 --- a/docs/game/DESIGN.md +++ b/docs/game/DESIGN.md @@ -6,7 +6,8 @@ owns sections 10–12 (keywords, peer-hosted modes, worked example). council-cri 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. +**Topics** (lanes) with 3 slots per side. There are 6 turns, both players plan at the same time, and +energy ramps from 1 to 6, with 1 unspent energy carried over. Reveals interleave one card at a time. 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 @@ -18,7 +19,7 @@ not upgrades. | 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 | +| Marvel Snap | 3-minute matches; simultaneous turns; 3 lanes, so the decision is *where*, not just *what* | lanes, about 6 turns, simultaneous planning, small deck | stakes betting (modes only); we deliberately diverge in lane size (3), energy carry-over, interleaved alternating reveals, stats visible from turn 1 with hidden Portals, and on-topic tie-breaks | | 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 | @@ -28,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. @@ -42,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) @@ -60,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. @@ -68,8 +79,11 @@ 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**). +When a card is in a Topic whose stat equals its `home`, it gets **+`onTopicBonus[cost]`** power +(default `[0, 1, 1, 2, 2, 3, 3]`, i.e. ⌈cost/2⌉). +On-topic efficiency is then about 2 power per energy at every cost (2.0 / 1.5 / 2.0 / 1.75 / 2.0 / 2.0). +Off-topic, cheap cards are weaker (1.0) than expensive ones (1.5). Cheap cards want their Topic, and +big cards are flexible. ### 1.5 Faction `faction` = the card's `category` (Space, Nature, People, Science, History, Culture), from @@ -78,19 +92,21 @@ 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 -The hash-derived `rarity` (`shared/protocol.ts:38`) is **cosmetic in v1** (frame colour). Mining luck -must not become power. +The hash-derived `rarity` (`shared/protocol.ts:38`) sets the frame colour, and **it chooses the +keyword source, not power** (§10.1: a Common gets its home-stat keyword, a Rare or better gets its +faction keyword). 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** +The card face shows **cost** (top-left), **power** (big, centre; the bonus shows as a "+N" badge on the home icon when the card is on-topic), 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. @@ -99,16 +115,28 @@ When `verifyStats` is true (the default for hosted matches), the match host chec 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. +A card that fails is played with its live values. The **host replaces `snapshot`** with a snapshot +built from the live values (`deriveStats` on the live bytes, languages and views) **before** it builds +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. +- **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'`. --- ## 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. +- **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 @@ -116,7 +144,8 @@ The engine itself does no I/O: it receives already-checked `CardInput`s. with frozen, hand-checked snapshot stats, including the 4 cards in `shared/catalog.ts`). 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. + factions and an average cost of 3.0–3.3, and is **curve-shaped**: at least 3 cards of cost 4 or more, + and at most 4 of cost 1. 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. @@ -127,13 +156,23 @@ The engine itself does no I/O: it receives already-checked `CardInput`s. - 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. + Topics have **no faction**. Faction matters only through keywords such as Rally, which count cards, + never Topics. +- Each player has at most `laneCapacity` cards per Topic (default **3**). That gives 9 slots per side, + which caps cheap-card flooding and fits 3 cards across a 360 px phone. +- **Topic pool:** `topicPool` is a list of Topics, each `{ id, name, stat, portal | null }`. The default + pool has 9 Topics: 3 per stat, one plain and two with Portals. `pool_s` is the sub-list with stat + `s`, in file order. +- **Topic draw (exact):** + - If `distinctStats` is true (the default): for each stat in the fixed order + `[attention, depth, reach]`, pick `pool_s[floor(next() × len(pool_s))]`. That uses 3 `next()` + calls. Then Fisher–Yates the 3 picks into lanes 1–3 (i = 2, 1; j = floor(next() × (i+1))), which + uses 2 calls. + - If `distinctStats` is false: Fisher–Yates the whole pool (i from n−1 down to 1) and take the first + `topicCount` entries as lanes 1–3. +- **Stats visible, Portals hidden:** every Topic's **stat** is face-up from turn 1. Its **Portal** + modifier is face-down until the start of turn `portalReveal[i]` (default `[2, 3, 4]`). You always + know where your card is on-topic, but not what twist a lane will get. --- @@ -145,10 +184,15 @@ The engine itself does no I/O: it receives already-checked `CardInput`s. 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 + 4. the initiative coin: p0 has initiative on odd turns 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`). +4. **Seed fairness (hosted PvP):** commit–reveal. Each party *i* (host, p0, p1) sends + `sha256(r_i)` for a random 32-byte `r_i`, then reveals `r_i` once all commits are in. + `seed` = the first 4 bytes (big-endian uint32) of `sha256(r_host ‖ r_p0 ‖ r_p1)`. + The host still relays the hidden plans, so hosted PvP trusts the host not to leak them. + Local and bot matches use any seed. --- @@ -157,29 +201,37 @@ The engine itself does no I/O: it receives already-checked `CardInput`s. 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). + - Reveal any Portal scheduled for turn *t* (resolve its "on reveal"). + - Each player's energy = `energyByTurn[t-1]` + carry + `bonusEnergy`. Carry is + min(`energyCarryMax`, unspent energy from last turn), default max **1**. Saving one energy on + 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. + (default **7**) cards. Otherwise they don't draw. This includes turn 1, so the turn-1 hand is + 3 + 1 = 4 cards. + - Order within Start: Portal reveal, then energy, then draw. The Underdog check (step 2) comes after + all three. +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. - 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. +4. **Reveal (interleaved)** + - Plays reveal **one at a time, alternating**: the initiative player's 1st, the other player's + 1st, the initiative player's 2nd, and so on. When one player runs out, the rest of the other's + reveal in order. - 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. + - So the order in which you queue cards matters: lead with the card you want resolved first. + - Energy is reserved when a card is queued. A queued play that is no longer legal at reveal (the + lane is full, or a Portal rejects it) **fizzles**: the card stays in 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. + - 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. @@ -188,18 +240,19 @@ 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` +- A card's **lane power** = `power` + (`onTopicBonus[cost]` 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. +- A player **leads** a Topic if their Topic power is strictly greater than the opponent's. +- **Consensus tie-break:** if the powers are equal and > 0, the player with more **on-topic** cards + there leads. If that is also equal, nobody leads. 0–0 has no leader. --- ## 7. Win conditions and tie-breaks -At the end of the last turn: +**Scoring** happens after the last turn's End phase (§5.5): every end-of-turn effect, including +the last turn's, and every "at scoring" Portal resolves **before** Topics are judged. Then: 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**. @@ -213,14 +266,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, so it gives up 2 Topics early. Power per energy is flat across the curve (`powerByCost` is tuned for this in sim). | +| 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) | Weak by design: only 9 slots and 9 cards seen. Critic's sim under these rules: swarm vs curve about 7–11%. Its home is Culture's wide-turn keyword (§10). | | 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. | +| "Always play the highest-power card" | It ignores the on-topic bonus, lane capacity and the hidden Portals. Critic's sim: 18–21% against a smart bot (target < 55%). | | 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%. | +| 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). | --- @@ -235,13 +289,16 @@ 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], "bonusEnergy": 0, "underdog": true, - "topicCount": 3, "distinctStats": true, "revealSchedule": [1, 2, 3], "laneCapacity": 4, - "topicPool": "default", + "energyByTurn": [1, 2, 3, 4, 5, 6], "energyCarryMax": 1, "bonusEnergy": 0, "underdog": false, + "topicCount": 3, "distinctStats": true, "portalReveal": [2, 3, 4], "laneCapacity": 3, + "topicPool": [ /* inline Topic objects {id, name, stat, portal}; default = the 9 in §10.3 */ ], + "keywordParams": { /* per-keyword numbers, keyed by keyword id (§10) */ }, + "portalParams": { /* per-Portal numbers, keyed by Topic id (§10.3) */ }, "costThresholds": [15, 35, 55, 75, 90], - "powerByCost": [0, 1, 2, 4, 5, 7, 9], - "onTopicBonus": 2, - "trendUp": 25, "trendDown": -25, + "powerByCost": [0, 1, 2, 4, 6, 8, 10], + "onTopicBonus": [0, 1, 1, 2, 2, 3, 3], "vanillaBonus": 1, + "keywordsEnabled": ["Buzz","Anchor","Echo","Orbit","Grow","Rally","Research","Legacy","Remix"], "ownedCards": true, + "trendUp": 25, "trendDown": -25, "trendMinDaily": 20, "uncheckedCostCap": 4, "factionSynergyCap": 3, "verifyStats": true, "percentiles": "card-sample-2026-11-16", @@ -249,7 +306,6 @@ The engine takes a `RulesConfig` object. Peer-hosted modes override it (§11). D } ``` -(`energyByTurn[t-1]` replaces "energy = t" in §5 so that modes can change the ramp.) **What modes may vary:** every key above, plus `topicPool` contents and the starter-deck lists. **Fixed for all modes:** matches are off-chain and never move or burn NFTs; the RNG and its draw order @@ -261,19 +317,206 @@ A mode must keep `turns × turnSeconds ≤ 240` so that matches stay within 3– ## 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` +### 10.1 Which keyword a card gets +The keyword comes from the card's **rarity**, **home stat** and **faction**, using the first rule that matches: + +1. `cost == 1` → **no keyword**. Instead the card gets +`vanillaBonus` power (default **1**), so a cost-1 card has power 2. + Cheap cards stay simple, which helps new players. +2. `rarity == "Common"` → the **home-stat keyword** (Buzz, Anchor or Echo; table 10.2). +3. Otherwise (Rare, Epic or Legendary) → the **faction keyword** (table 10.2). + +This puts rarity to use, but only as *which* keyword a card has, never as how much power it has. Every keyword below is +worth about +1 to +3, which is the same as the trade-offs between home-stat keywords, so mining luck buys variety and not power. (This changes +§1.7 slightly. Designer-a, please note it there: "rarity chooses the keyword source, not power".) +Rough expected mix (with Common about 60%): about 15% vanilla, about 50% home-stat keywords, about 35% faction keywords. + +Keywords are **one word** on the card face, plus one line of reminder text in the tap-to-inspect sheet. +They only ever *add* power (v1 has no removal, stealing, moving or lowering power). "Here" means this card's Topic, and +"your" means the owner's side. An effect stops at its cap, so no keyword moves a lane by more than 3 (§8 requires 6 or less). + +### 10.2 Keyword list + +| Keyword | Source | Trigger | Reminder text | Cap | +|---|---|---|---|---| +| **Buzz** | home: attention | On reveal | +1 power to each of your *other* cards here. | +2 (lane cap 3) | +| **Anchor** | home: depth | Ongoing | +2 power while it is your only card here. | +2 | +| **Echo** | home: reach | On reveal | +1 power to your most recently played card in each *other* Topic. | +2 (2 cards) | +| **Orbit** | faction: Space | Ongoing | +1 to your Topic power in each *adjacent* Topic. | +1 per adjacent Topic | +| **Grow** | faction: Nature | End of turn | +1 power. | +3 total | +| **Rally** | faction: People | On reveal | +1 power to each of your *other People* cards, in any Topic. | `factionSynergyCap` (3) | +| **Research** | faction: Science | On reveal | +1 power for each Topic you lead right now. | +3 | +| **Legacy** | faction: History | Ongoing | On the last turn, +2 power if this card has been here since turn 4 or earlier. | +2 | +| **Remix** | faction: Culture | On reveal | +2 power if you are losing here. | +2 | + +Precise rules (for engine-b): +- **On reveal** resolves when this card enters its Topic during Reveal (§5.4). It sees every card already revealed, + including cards the initiative player revealed earlier in the same turn. Bonuses it grants are permanent power counters on the target cards. +- **Ongoing** is recalculated every time Topic power is read. It's a condition, not a counter. +- **End of turn** resolves in §5.5 order: the initiative player's cards first, then Topic 1→3, then play order. +- **Buzz** targets only cards already here when it reveals. Cards that arrive later don't get the bonus. +- **Anchor** counts only its owner's cards here. Opposing cards don't matter. +- **Echo:** "most recently played" means the highest play sequence number among your cards in that Topic. Topics where you have no card are skipped. +- **Orbit** adds to Topic power, not to a card. It works even if you have no cards in the adjacent Topic (so Topic power can go 0 → 1). + Topic 2 is adjacent to 1 and 3. Topics 1 and 3 are adjacent only to 2. +- **Grow** stops after it has gained +3 in total. +- **Rally** counts cards by faction. Wildcard-style faction changes don't exist in v1. It gives at most `factionSynergyCap` counters in total, + going to the targets in play order. +- **Research** counts Topics where you lead (strictly greater Topic power) at the moment it resolves, including this + Topic after its own base and on-topic power is added. *(Clarification: the card's own power counts toward leading here.)* +- **Legacy** applies when `turn == turns` (the last turn), from the start of that turn, and only if the card was revealed on a turn ≤ `keywordParams.Legacy.byTurn` (default **4**, i.e. `turns − 2`). So committing a History card early is a real choice: it shows your hand to win the +2. +- **End-of-turn effects on the last turn resolve before scoring** (§7), so Grow's last +1 counts. +- **Remix:** "losing here" means the opponent's Topic power here is strictly greater than yours, counted just *before* this card + is added. +- **Culture is about half the pool,** so its faction keyword (Remix) is the one with no faction synergy. A Culture-heavy deck + gets no consistency bonus from being mono-faction. Only People (Rally) has faction synergy, and it's capped. + +Examples: +- *Buzz:* you have Haiku (2) and Jazz (4) in Topic 2, then play Pop music (Buzz, power 5). Haiku becomes 3, Jazz 5, and Pop music stays 5. +- *Anchor:* Coral reef (power 2) alone in Topic 1 is 4. Once you add another card there, it's 2 again. +- *Echo:* Moon is revealed in Topic 3. Your last card in Topic 1 gets +1. You have nothing in Topic 2, so that part is skipped. +- *Orbit:* Jupiter is in Topic 3, so your Topic 2 power is +1 even though no card there changed. +- *Rally:* Albert Einstein is revealed with no other People cards in play, so nothing happens. With Marie Curie and Ada Lovelace in play, each gets +1. +- *Research:* you lead Topics 1 and 3 when Periodic table is revealed into Topic 1, so it gets +2. +- *Legacy:* Ancient Rome (power 7) shows 7 on turns 5 and 9 on turn 6. +- *Remix:* the opponent has 6 here and you have 3, so Jazz (power 2) is revealed as 4. + +**`keywordParams` defaults** (every number above, keyed by keyword id; modes may change them within 0–6): +```json +{ "Buzz": {"amount": 1, "cap": 2}, "Anchor": {"amount": 2}, "Echo": {"amount": 1}, + "Orbit": {"amount": 1}, "Grow": {"amount": 1, "cap": 3}, "Rally": {"amount": 1, "cap": 3}, + "Research": {"amount": 1, "cap": 3}, "Legacy": {"amount": 2, "byTurn": 4}, "Remix": {"amount": 2} } +``` +Rally's cap is `factionSynergyCap` when that key is set. Otherwise it's `keywordParams.Rally.cap`. + +### 10.3 Portals (Topic modifiers) and the default Topic pool +Each Topic has `{ id, name, stat, portal | null }`. The default `topicPool` has 9 Topics, one plain and two with +Portals for each stat. A Portal applies from the moment its Topic is revealed (§3), except where it says otherwise. + +| Topic | Stat | Portal rule | +|---|---|---| +| Current Events | attention | – | +| Main Page | attention | At scoring, each card here gets +1 power. | +| Trending | attention | Trend arrows (§1.6) count double here (±2). | +| Archive | depth | – | +| Featured Article | depth | At end of the match, the player with the single highest-power card here gets +2 Topic power here. If the highest card power here is tied (between the two players), nobody gets the bonus. | +| Stub | depth | Lane capacity here is 2 per player. | +| Translations | reach | – | +| Interwiki | reach | +1 Topic power here for a player who has at least one card in all 3 Topics. | +| Disambiguation | reach | Every card here counts as on-topic, whatever its home stat. | + +As data: `portal = { kind: "scoringCardBonus", amount: 1 } | { kind: "trendMultiplier", factor: 2 } | +{ kind: "highestCardBonus", amount: 2 } | { kind: "laneCapacity", value: 2 } | { kind: "spreadBonus", amount: 1 } | +{ kind: "allOnTopic" }`. Modes may add Topics with these kinds, using new numbers, but not new kinds (engine code). + +**`portalParams` defaults** (keyed by Topic id): `{ "main-page": {"amount": 1}, "trending": {"factor": 2}, +"featured-article": {"amount": 2}, "stub": {"value": 2}, "interwiki": {"amount": 1} }`. Disambiguation has no numbers. +Topic ids are the names in kebab-case: `current-events, main-page, trending, archive, featured-article, stub, +translations, interwiki, disambiguation`. The UI shows each Portal's one-line rule **on the lane itself**, not behind a tap. +Orbit's bonus is not on any card, so the UI shows it as a lane badge ("+1 🪐") next to the Topic total. + +--- ## 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.* +A **mode** is data, published by a node operator and run by the match host: +```json +{ + "id": "blitz", // [a-z0-9-]{3,32}, unique per host + "name": "Blitz", "description": "Four quick turns.", // ≤ 40 and ≤ 280 chars, plain text + "rules": { "turns": 4, "energyByTurn": [2, 3, 4, 5], "portalReveal": [1, 1, 2], "deckSize": 10 }, + "topicPool": [ /* optional: Topic objects (10.3); default if omitted */ ], + "starterDecks": [ /* optional: lists of loaner pageIds */ ] +} +``` +- `rules` is a **partial** `RulesConfig` (§9) merged over the defaults. Unknown keys are rejected. +- **Validation** (modes owns the code; these are the limits). If any check fails, the mode is refused: + +| Key | Allowed | +|---|---| +| `turns` | 3–8, and `turns × turnSeconds ≤ 240` | +| `energyByTurn` | length = `turns`, each 0–10 | +| `bonusEnergy` | 0–3 | +| `portalReveal` | length = `topicCount`, each 1..`turns`, non-decreasing | +| `topicCount` | 1–5; `distinctStats` only if ≤ 3 | +| `laneCapacity` | 1–6 | +| `deckSize` | 6–20; `maxCopiesPerPage` 1–4; `maxLoaners` 0..`deckSize` | +| `openingHand` | 0–6; `handLimit` 1–10 | +| `turnSeconds` | 10–60; `afkTurns` 1–5 | +| `costThresholds` | 5 strictly ascending integers in 0–100 | +| `powerByCost` | 7 integers in 0–20, non-decreasing from index 1 | +| `onTopicBonus` (7 entries), `vanillaBonus` | 0–5 each | +| `trendUp` / `trendDown` | 0–200 / −200–0 | +| `factionSynergyCap` | 0–6 | +| `keywordsEnabled` | any subset of the 9 v1 keywords; a disabled keyword makes those cards vanilla, *without* `vanillaBonus` | +| `keywordParams`, `portalParams` | only the keys listed in §10.2 / §10.3, each in 0–6 (`Legacy.byTurn` in 1..`turns`) | +| `verifyStats` | the host may only turn this off for modes that use only loaners (`maxLoaners == deckSize` and owned cards banned) | +| `topicPool` | 3–20 Topics, Portal kinds only from 10.3 | + +- **Identity:** `modeHash` = SHA-256 of the canonical JSON (sorted keys, no whitespace) of the *merged* rules + plus the topicPool. A match record holds `{ modeHash, seed, both decks' CardInputs, both players' commit lists }`, + and that is enough to replay it exactly. +- **What modes can't change** is the "Fixed for all modes" list in §9. Modes also can't add keywords or Portal kinds, or + stake, move or burn NFTs. + +Example modes (good defaults for operators to publish): +| Mode | Overrides | Feel | +|---|---|---| +| **Blitz** | `turns 4`, `energyByTurn [2,3,4,5]`, `portalReveal [1,1,2]`, `deckSize 10`, `turnSeconds 20` | about 2 minutes | +| **Deep Cuts** | `topicPool`: only the 3 depth Topics, `distinctStats false` | rewards long, obscure articles | +| **Loaner League** | `maxLoaners 12` and owned cards banned (`"ownedCards": false`, a new boolean key, default true) | fully level, for tournaments | +| **Big Board** | `topicCount 5`, `distinctStats false`, `portalReveal [1,2,3,4,5]`, `laneCapacity 3` | win 3 of 5; **tablet/desktop only** (5 × 3 slots won't fit a 360 px phone) | +| **No Keywords** | `keywordsEnabled []`, `onTopicBonus [0,3,3,3,3,3,3]` | Top Trumps–style tutorial mode | + +--- ## 12. Worked example match *(owner: council-designer-b)* -*To be written by council-designer-b.* +This example uses the §1–11 rules of this PR. It was recomputed by council-critic (who checked it with a script) and re-checked by hand by designer-b. +- **Rules:** `powerByCost [0,1,2,4,6,8,10]`, `onTopicBonus [0,1,1,2,2,3,3]`, `vanillaBonus 1`, `laneCapacity 3`, + interleaved reveals, `underdog false`, no trend arrows. Nobody carries energy: both players spend 1/2/3/4/5/6. +- **Initiative:** Ana (p0) on odd turns, Bo (p1) on even turns. +- **Topics:** **T1 Archive (depth, plain)**, **T2 Main Page (attention; Portal revealed turn 3; at scoring, +1 per card here)**, + **T3 Translations (reach, plain)**. + +The cards are the §1 output, given directly. "Base" is `powerByCost[cost]`, with +1 for cost-1 vanilla cards; "+on" is `onTopicBonus[cost]`. + +| Player | Card | Faction / rarity | Cost | Base (+on) | Home | Keyword | +|---|---|---|---|---|---|---| +| Ana | Octopus | Nature / Common | 1 | 2 (+1) | depth | – (vanilla) | +| Ana | Moon | Space / Common | 2 | 2 (+1) | reach | Echo | +| Ana | Periodic table | Science / Rare | 3 | 4 (+2) | depth | Research | +| Ana | Albert Einstein | People / Epic | 4 | 6 (+2) | attention | Rally | +| Ana | Ancient Rome | History / Rare | 5 | 8 (+3) | depth | Legacy | +| Ana | Library of Alexandria | History / Common | 4 | 6 (+2) | depth | Anchor | +| Ana | Coral reef | Nature / Common | 2 | 2 (+1) | depth | Anchor | +| Bo | Haiku | Culture / Common | 1 | 2 (+1) | attention | – (vanilla) | +| Bo | Jazz | Culture / Rare | 2 | 2 (+1) | attention | Remix | +| Bo | Fern | Nature / Rare | 3 | 4 (+2) | depth | Grow | +| Bo | Pop music | Culture / Common | 4 | 6 (+2) | attention | Buzz | +| Bo | Jupiter | Space / Epic | 5 | 8 (+3) | reach | Orbit | +| Bo | Saturn | Space / Legendary | 6 | 10 (+3) | reach | Orbit | + +Topic power is written as **Ana–Bo** after the End phase. + +| Turn | Initiative | Reveals (interleaved order) and effects | T1 | T2 | T3 | +|---|---|---|---|---|---| +| 1 | Ana | Ana Octopus → T1: 2+1 = **3**. Bo Haiku → T1: **2** (off-topic) | 3–2 | 0–0 | 0–0 | +| 2 | Bo | Bo Jazz → T2: 2+1 = 3. Remix: not losing (0–0), so no bonus. Ana Moon → T3: 2+1 = 3. Echo: Octopus +1 → 4 | 4–2 | 0–3 | 3–0 | +| 3 | Ana | Main Page Portal revealed. Ana Periodic table → T1: 4+2 = 6. Research: Ana leads T1 (10–2) and T3 (3–0), so +2 → **8**. Bo Fern → T1: 4+2 = 6. End, Grow: Fern 7 | 12–9 | 0–3 | 3–0 | +| 4 | Bo | Bo Pop music → T2: 6+2 = 8. Buzz: Jazz +1 → 4. Ana Einstein → T2: 6+2 = 8. Rally: no other People cards. End, Grow: Fern 8 | 12–10 | 8–12 | 3–0 | +| 5 | Ana | Ana Ancient Rome → T3: 8 (depth ≠ reach). Its Legacy can't apply, because it arrived on turn 5 > 4. Bo Jupiter → T3: 8+3 = 11. Orbit: Bo's T2 +1. End, Grow: Fern 9 (the +3 cap is reached) | 12–11 | 8–13 | 11–11 | +| 6 (last) | Bo | Bo Saturn → T3: 10+3 = 13. Orbit: Bo's T2 +1. Ana Library → T3: 6 (off-topic; Anchor no, not alone). Ana Coral reef → T1: 2+1 = 3 (Anchor no). Scoring: Main Page gives +1 per card in T2 | **15–11** | **9–16** | **17–24** | + +Final board: +- **T1:** Ana has Octopus 4 + Periodic table 8 + Coral reef 3 = **15**. Bo has Haiku 2 + Fern 9 = **11**. → Ana +- **T2:** Ana has Einstein 8+1 = **9**. Bo has Jazz 4+1 + Pop music 8+1 + Orbit ×2 = **16**. → Bo +- **T3:** Ana has Moon 3 + Ancient Rome 8 + Library 6 = **17**. Bo has Jupiter 11 + Saturn 13 = **24**. → Bo + +**Bo wins 2–1** (total power 41–51; the tie-break isn't needed). +The deciding moment was Ana's turn-5 Rome. It was off-topic in T3, and too late for Legacy. Saturn on-topic plus a second Orbit then took both T2 and T3. + +**Golden test (engine-b):** +- **Inject:** the Topic order, these 13 cards and these commit lists, in the queue order shown. +- **Expected final Topic powers:** `[[15,11],[9,16],[17,24]]` (Ana–Bo). Winner: p1. +- **Coverage:** vanilla, Echo, Research, Grow (including its cap), Buzz, Orbit ×2, the Main Page Portal at scoring, and Remix, Rally, Anchor and Legacy correctly **not** firing. +- **Separate unit tests:** add cases where Remix, Rally, Anchor and Legacy (here since turn ≤ 4) **do** fire.