diff --git a/docs/game/DESIGN.md b/docs/game/DESIGN.md index 96ddf9d..d6eb699 100644 --- a/docs/game/DESIGN.md +++ b/docs/game/DESIGN.md @@ -240,7 +240,8 @@ The engine takes a `RulesConfig` object. Peer-hosted modes override it (§11). D "topicPool": "default", "costThresholds": [15, 35, 55, 75, 90], "powerByCost": [0, 1, 2, 4, 5, 7, 9], - "onTopicBonus": 2, + "onTopicBonus": 2, "vanillaBonus": 1, + "keywordsEnabled": ["Buzz","Anchor","Echo","Orbit","Grow","Rally","Research","Legacy","Remix"], "ownedCards": true, "trendUp": 25, "trendDown": -25, "factionSynergyCap": 3, "verifyStats": true, @@ -261,19 +262,184 @@ 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. | +3 (lane cap 4) | +| **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 | +2 power on the last turn. | +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. +- **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. + +### 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 | On the last turn, 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 (no bonus if tied). | +| 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: "lastTurnCardBonus", 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). + +--- ## 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], "revealSchedule": [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 | +| `revealSchedule` | 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`, `vanillaBonus` | 0–5 | +| `trendUp` / `trendDown` | 0–200 / −200–0 | +| `factionSynergyCap` | 0–6 | +| `keywordsEnabled` (new, default: all 9) | any subset of the 9 v1 keywords; a disabled keyword makes those cards vanilla, *without* `vanillaBonus` | +| `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]`, `revealSchedule [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`, `revealSchedule [1,2,3,4,5]`, `laneCapacity 3` | win 3 of 5 | +| **No Keywords** | `keywordsEnabled []`, `onTopicBonus 3` | Top Trumps–style tutorial mode | + +--- ## 12. Worked example match *(owner: council-designer-b)* -*To be written by council-designer-b.* +Default rules. The derived cards are given directly (§1 output). "base" = `powerByCost[cost]`, with +1 for cost-1 vanilla cards. +Topics after the seeded draw: **T1 Archive (depth)**, **T2 Main Page (attention)**, **T3 Translations (reach)**. +Ana (p0) has initiative on turn 1. Neither player has a trend arrow. + +Cards played: +| Player | Card | Faction / rarity | Cost | Base | Home | Keyword | +|---|---|---|---|---|---|---| +| Ana | Octopus | Nature / Common | 1 | 2 | depth | – (vanilla) | +| Ana | Moon | Space / Common | 2 | 2 | reach | Echo | +| Ana | Periodic table | Science / Rare | 3 | 4 | depth | Research | +| Ana | Albert Einstein | People / Epic | 4 | 5 | attention | Rally | +| Ana | Ancient Rome | History / Rare | 5 | 7 | depth | Legacy | +| Ana | Library of Alexandria | History / Common | 4 | 5 | depth | Anchor | +| Ana | Coral reef | Nature / Common | 2 | 2 | depth | Anchor | +| Bo | Haiku | Culture / Common | 1 | 2 | attention | – (vanilla) | +| Bo | Jazz | Culture / Rare | 2 | 2 | attention | Remix | +| Bo | Fern | Nature / Rare | 3 | 4 | depth | Grow | +| Bo | Pop music | Culture / Common | 4 | 5 | attention | Buzz | +| Bo | Jupiter | Space / Epic | 5 | 7 | reach | Orbit | +| Bo | Saturn | Space / Legendary | 6 | 9 | reach | Orbit | + +Topic power is written as **Ana–Bo**. "Lead" is the number of Topics each player leads after the turn. + +| Turn | Revealed | Ana plays (reveals first when she has initiative) | Bo plays | T1 | T2 | T3 | Lead | Initiative next | +|---|---|---|---|---|---|---|---|---| +| 1 | T1 Archive | Octopus → T1: 2, +2 on-topic = **4** | Haiku → T1: **2** (attention ≠ depth) | 4–2 | 0–0 | 0–0 | 1–0 | Ana (leads more) | +| 2 | T2 Main Page | Moon → T3 (face-down, no bonus yet): 2. Echo: Octopus +1 → 5 | Jazz → T2: 2+2 = 4. Remix: Ana has 0 here, so not losing, no bonus | 5–2 | 0–4 | 2–0 | 2–1 | Ana | +| 3 | T3 Translations: Moon is now on-topic, 4 | Periodic table → T1: 4+2 = 6. Research: Ana leads T1 (11–2) and T3 (4–0) → +2 = **8** | Fern → T1: 4+2 = 6. End of turn, Grow: 7 | 13–9 | 0–4 | 4–0 | 2–1 | Ana | +| 4 | – | Einstein → T2: 5+2 = 7. Rally: no other People cards, so nothing | Pop music → T2: 5+2 = 7. Buzz: Jazz +1 → 5. Grow: Fern 8 | 13–10 | 7–12 | 4–0 | 2–1 | Ana | +| 5 | – | Ancient Rome → T3: 7 (depth ≠ reach) | Jupiter → T3: 7+2 = 9. Orbit: Bo's T2 +1 → 13. Grow: Fern 9 (the +3 cap is reached) | 13–11 | 7–13 | 11–9 | 2–1 | Ana | +| 6 (last) | Main Page: +1 per card. Legacy: Rome 9 | Library of Alexandria → T3: 5. Anchor: not the only card, so no bonus. Coral reef → T1: 2+2 = 4 (Anchor: no) | Saturn → T3: 9+2 = 11. Orbit: Bo's T2 +1 | **17–11** | **8–16** | **18–20** | 1–2 | – | + +The turn-6 numbers: +- **T1:** Ana has Octopus 5 + Periodic table 8 + Coral reef 4 = 17. Bo has Haiku 2 + Fern 9 = 11. +- **T2:** Ana has Einstein 7 + 1 (Main Page) = 8. Bo has Jazz 5+1 and Pop music 7+1, plus Orbit ×2, = 16. +- **T3:** Ana has Moon 4 + Rome 9 + Library 5 = 18. Bo has Jupiter 9 + Saturn 11 = 20. + +**Bo wins 2–1.** Bo trailed 1–2 from turn 2 to turn 5. Ana guessed Bo would contest T3 and spent 4 of her 6 energy there. Saturn on-topic (11) still beat her by 2, and its Orbit also tipped T2. The underdog check never fired, because Bo always led one Topic. +Energy check: Ana spent 1/2/3/4/5/6 and Bo spent 1/2/3/4/5/6. + +**Golden test for engine-b:** with these card inputs, this Topic order and these commit lists, the final Topic powers must be +`T1 17–11, T2 8–16, T3 18–20`, and the result must be a Bo win (2 Topics to 1). Only the seed's Topic draw and the decks' order +vary. The test should inject the Topic order and the hands directly.