docs/game/DESIGN.md: keywords, portals, modes, worked example (council-designer-b)

Fills sections 10-12 on top of designer-a's draft: 9 power-only keywords
chosen by rarity/home stat/faction, 9-Topic default pool with 6 Portal kinds,
mode schema with validation ranges and example modes, and a fully computed
6-turn worked example with a golden test (T1 17-11, T2 8-16, T3 18-20).
Adds rules keys vanillaBonus, keywordsEnabled, ownedCards to section 9.

Refs #1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-16 22:53:56 -05:00
co-authored by Claude Opus 5.5
parent f808f963c6
commit a9ab940f4b
+177 -11
View File
@@ -240,7 +240,8 @@ The engine takes a `RulesConfig` object. Peer-hosted modes override it (§11). D
"topicPool": "default", "topicPool": "default",
"costThresholds": [15, 35, 55, 75, 90], "costThresholds": [15, 35, 55, 75, 90],
"powerByCost": [0, 1, 2, 4, 5, 7, 9], "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, "trendUp": 25, "trendDown": -25,
"factionSynergyCap": 3, "factionSynergyCap": 3,
"verifyStats": true, "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)* ## 10. Keywords *(owner: council-designer-b)*
*To be written by council-designer-b. Constraints from the rules above:* ### 10.1 Which keyword a card gets
- one keyword per card, one word, no more than one short line of reminder text The keyword comes from the card's **rarity**, **home stat** and **faction**, using the first rule that matches:
- 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) 1. `cost == 1` → **no keyword**. Instead the card gets +`vanillaBonus` power (default **1**), so a cost-1 card has power 2.
- no single effect may swing a lane by more than 6 Cheap cards stay simple, which helps new players.
- each faction gets a keyword pool; Culture's has the lowest synergy ceiling 2. `rarity == "Common"` → the **home-stat keyword** (Buzz, Anchor or Echo; table 10.2).
- §10.3 Portals: the Topic modifiers in `topicPool` 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)* ## 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 A **mode** is data, published by a node operator and run by the match host:
optional starter decks.* ```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)* ## 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.