diff --git a/docs/game/DESIGN.md b/docs/game/DESIGN.md index eaf6e3c..906968d 100644 --- a/docs/game/DESIGN.md +++ b/docs/game/DESIGN.md @@ -97,13 +97,11 @@ otherwise 0. A `null` value gives 0. Trend also needs `live.dailyAverage ≥ tre 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`) 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. +The hash-derived `rarity` (`shared/protocol.ts:38`) is **cosmetic in v1** (frame colour only). Mining luck must not +become power or keyword choice. ### 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). +Each card has at most **one** keyword: cost-1 cards are vanilla, and the others get their faction's keyword (§10.1). ### 1.9 Card face (phone) 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** @@ -288,7 +286,7 @@ The engine takes a `RulesConfig` object. Peer-hosted modes override it (§11). D "costThresholds": [15, 35, 55, 75, 90], "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, + "keywordsEnabled": ["viral","rising","local","encyclopedic","nostalgic","translated"], "ownedCards": true, "trendUp": 25, "trendDown": -25, "trendMinDaily": 20, "uncheckedCostCap": 4, "factionSynergyCap": 3, "verifyStats": true, @@ -308,67 +306,55 @@ A mode must keep `turns × turnSeconds ≤ 240` so that matches stay within 3– ## 10. Keywords *(owner: council-designer-b)* +**The v1 keyword set is these six, one per faction.** The ids are the ones engine-b already uses on `night/engine/keywords`. +Topics carry only a **stat**, never a faction. Every keyword below that mentions a Topic keys off stats or board state. + ### 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: +First rule that matches: +1. `cost == 1` → **no keyword** (vanilla). The card gets +`vanillaBonus` power (default **1**), so a cost-1 card is 2. +2. `"edition"` is in `keywordsEnabled` (off by default) and the deck holds another card with the same `pageId` → **edition**. +3. Otherwise → the card's **faction keyword** from 10.2, if it's in `keywordsEnabled`. If not, the card is vanilla, *without* `vanillaBonus`. -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). +Rarity plays no part here (it's cosmetic, §1.7). Keywords don't lower power, and v1 has no per-keyword power deltas. +If sim shows that a keyword is worth more than about 1 power on average, sim-balance can add `keywordPowerDelta.` (a mode key, default 0, range −3 to 0). -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. +### 10.2 Keyword list (v1) -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). +| Faction | id (card word) | Trigger | Reminder text | Cap | Order-sensitive? | +|---|---|---|---|---|---| +| Culture | **viral** | On reveal | +1 power for each other card you revealed earlier this turn. | +2 | yes: your queue order | +| Nature | **rising** | End of turn | +1 power. | +2 total | no | +| People | **local** | Ongoing | +1 power while on-topic (the Topic's stat is its home stat). | +1 | no | +| Science | **encyclopedic** | On reveal | +2 power if there are no other cards here (either side). | +2 | **yes: interleaving** | +| History | **nostalgic** | On reveal | +2 power if you are losing here. | +2 | **yes: interleaving** | +| Space | **translated** | On reveal | +1 power to your most recently revealed card in each *other* Topic. | +2 | yes | -### 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 | +Why this set: every keyword is one line and one trigger, and only adds power. The largest swing is +2 on one card, +so no lane moves by more than 2 from a keyword. Nothing scales with faction count, so a mono-Culture deck gets no +consistency edge (`factionSynergyCap` is unused in v1). Viral is Culture's weakest keyword, and it rewards wide turns. +Three keywords (encyclopedic, nostalgic, translated) react to the interleaved reveal (§5.4), so initiative and queue order matter. 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. +- **On reveal** resolves the moment the card enters its Topic, and sees every card revealed before it (both players, + including earlier reveals this turn). The bonuses it grants are permanent counters. +- **Ongoing** is a condition, recalculated whenever power is read. +- **End of turn** resolves in §5.5 order: the initiative player's cards first, then Topic 1→3, then reveal order. +- **viral:** counts the owner's cards revealed earlier in *this* turn's Reveal phase, in any Topic. Cards that went back to hand don't count. +- **rising:** stops after it has gained +2 in total. +- **local:** "on-topic" is exactly the §1.4/§6 condition. It's simply an extra +1 on top of `onTopicBonus`. +- **encyclopedic:** "no other cards here" means both sides of this Topic are empty, apart from this card, when it reveals. +- **nostalgic:** "losing here" means the opponent's Topic power here is strictly greater than yours, counted just *before* this card is added. + The consensus tie-break doesn't count: a tie is not losing. +- **translated:** "most recently revealed" means the highest global reveal sequence number among your cards in that Topic. Topics where you have no card are skipped. +- No v1 keyword uses the RNG. §4's "later random events" slot stays empty in v1. -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. +**Already in code, disabled by default (`keywordsEnabled` excludes them; for modes only):** +- **edition:** +2 for each other copy of this `pageId` on your side. +- **obscure:** the opponent sees it face down until the end of the match. +- **wildcard:** its home stat becomes the Topic's stat on reveal. + +These are engine-b's existing implementations. The faction-based versions of `local` and `wildcard`, and the token version of `viral`, are +**replaced** by the definitions above. ### 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 @@ -421,9 +407,10 @@ A **mode** is data, published by a node operator and run by the match host: | `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 | +| `energyCarryMax` | 0–3 | | `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` | +| `keywordsEnabled` | any subset of the 9 implemented ids (6 v1 defaults + edition, obscure, wildcard); a card whose keyword is disabled is 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 | @@ -440,59 +427,70 @@ Example modes (good defaults for operators to publish): | **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 | -| **No Keywords** | `keywordsEnabled []`, `onTopicBonus 3` | Top Trumps–style tutorial mode | +| **No Keywords** | `keywordsEnabled []`, `onTopicBonus [0,2,2,3,3,4,4]` | Top Trumps–style tutorial mode | --- ## 12. Worked example match *(owner: council-designer-b)* -> **⚠ Out of date (merge note from designer-a):** this example was written against the #12 draft: -> flat +2 on-topic, `powerByCost [..5,7,9]`, laneCapacity 4, and Topics revealed one per turn. -> §1–9 now use `onTopicBonus [0,1,1,2,2,3,3]`, `powerByCost [0,1,2,4,6,8,10]`, laneCapacity 3, -> 1 carried-over energy, interleaved reveals, alternating initiative, stats visible from turn 1, and -> Portals revealed on turns 2–4. designer-b is recomputing it. **engine-b: don't use the golden -> numbers below until this note is gone.** +These are the §1–9 rules as of this PR: +- `powerByCost [0,1,2,4,6,8,10]`, `onTopicBonus [0,1,1,2,2,3,3]`, `vanillaBonus 1` +- `laneCapacity 3`, `energyCarryMax 1`, interleaved reveals, alternating initiative, `portalReveal [2,3,4]` +- `underdog false`, no trend arrows -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. +The derived cards are given directly (the §1 output), so the test needs no percentile table. +Topics: **T1 Archive (depth, plain)**, **T2 Main Page (attention; Portal: on the last turn each card here gets +1; revealed turn 3)**, +**T3 Translations (reach, plain; revealed turn 4)**. Ana (p0) has initiative on odd turns and Bo (p1) on even turns. -Cards played: -| Player | Card | Faction / rarity | Cost | Base | Home | Keyword | +| Player | Card | Faction | 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 | +| Ana | Octopus | Nature | 1 | 2 | depth | – (vanilla) | +| Ana | Moon | Space | 2 | 2 | reach | translated | +| Ana | Coral reef | Nature | 2 | 2 | depth | rising | +| Ana | Albert Einstein | People | 4 | 6 | attention | local | +| Ana | Ancient Rome | History | 5 | 8 | depth | nostalgic | +| Ana | Library of Alexandria | History | 4 | 6 | depth | nostalgic | +| Ana | Periodic table | Science | 3 | 4 | depth | encyclopedic | +| Bo | Haiku | Culture | 1 | 2 | attention | – (vanilla) | +| Bo | Mars | Space | 2 | 2 | reach | translated | +| Bo | Jazz | Culture | 2 | 2 | attention | viral | +| Bo | Pop music | Culture | 4 | 6 | attention | viral | +| Bo | Jupiter | Space | 5 | 8 | reach | translated | +| Bo | Fern | Nature | 3 | 4 | depth | rising | +| Bo | Mona Lisa | Culture | 3 | 4 | attention | viral | -Topic power is written as **Ana–Bo**. "Lead" is the number of Topics each player leads after the turn. +Topic power is written as **Ana–Bo** after End of turn. Energy is "available / spent". -| 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 | – | +| Turn | Init | Energy Ana / Bo | Reveals, in interleaved order | T1 | T2 | T3 | +|---|---|---|---|---|---|---| +| 1 | Ana | 1/1, 1/1 | Ana Octopus → T1: 2 +1 on-topic = **3**. Bo Haiku → T2: 2+1 = **3** | 3–0 | 0–3 | 0–0 | +| 2 | Bo | 2/2, 2/0 | Bo passes (to carry 1). Ana Moon → T3: 2+1 = 3. translated: Octopus +1 → 4 | 4–0 | 0–3 | 3–0 | +| 3 | Ana | 3/2, **4**/4 | Main Page Portal revealed. Ana Coral reef → T1: 2+1 = 3. Bo Mars → T3: 2+1 = 3, translated: Haiku +1 → 4. Bo Jazz → T2: 2+1 = 3, viral (Mars earlier) +1 → 4. End: rising Coral reef → 4 | 8–0 | 0–8 | 3–3 (tie; on-topic 1–1, so no leader) | +| 4 | Bo | **5**/4, 4/4 | Bo Pop music → T3: 6 (off-topic), viral +0. Ana Einstein → T2: 6+2 on-topic, local +1 = **9**. End: rising Coral reef → 5 (cap reached) | 9–0 | 9–8 | 3–9 | +| 5 | Ana | **6**/5, 5/5 | Ana Ancient Rome → T3: 8 (off-topic). nostalgic: losing 3–9, so +2 → **10**. Bo Jupiter → T1: 8 (off-topic). translated: Jazz → 5 (T2), Pop music → 7 (T3) | 9–8 | 9–9: **Bo leads** (consensus: on-topic 1 vs 2) | 13–10 | +| 6 (last) | Bo | **7**/7, 6/6 | Main Page active (+1 per card in T2). Bo Fern → T1: 4+2 = 6. Ana Library → T1: 6+2 = 8. nostalgic: losing 9–14, so +2 → **10**. Bo Mona Lisa → T2: 4+2 = 6, viral (Fern earlier) +1 → 7. Ana Periodic table → T2: 4 (off-topic), encyclopedic: no (cards here). End: rising Fern → 7 | **19–15** | **15–19** | **13–10** | -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. +Final card values: +- **T1:** + - Ana: Octopus 4 + Coral reef 5 + Library 10 = 19. + - Bo: Jupiter 8 + Fern 7 = 15. +- **T2:** each card +1 from Main Page. + - Ana: Einstein 10 + Periodic table 5 = 15. + - Bo: Haiku 5 + Jazz 6 + Mona Lisa 8 = 19. +- **T3:** + - Ana: Moon 3 + Ancient Rome 10 = 13. + - Bo: Mars 3 + Pop music 7 = 10. -**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. +**Ana wins 2–1.** Three moments show the v1 mechanics: +- **Carry-over:** Bo passed on turn 2 to afford two plays on turn 3 (4 energy). +- **Consensus:** T2 at 9–9 after turn 5 went to Bo, who had two on-topic attention cards to Ana's one. +- **Interleaving decides the match:** on turn 6 Bo had initiative, so Fern revealed before Library. Ana was then losing T1 (9 vs 14) and nostalgic fired (+2). + If Ana had revealed first, she'd have been ahead 9–8, nostalgic would not have fired, and T1 would have been 17–15. Ana still wins that lane, but by 2 instead of 4. -**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. +**Golden test for engine-b:** +- **Inject:** the Topic order, the opening hands and the draw order directly, with each player's commit list per turn as in the table. The queue order within a turn is as listed. +- **Expected final Topic powers:** `T1 19–15, T2 15–19, T3 13–10`. Winner: p0, by 2 Topics to 1. +- **Also assert:** + - after turn 5, T2 is a 9–9 tie with Bo leading by consensus + - Ana's carried energy is 1 at the start of turns 4, 5 and 6 + - Bo's carried energy is 1 at the start of turn 3