diff --git a/docs/game/DESIGN.md b/docs/game/DESIGN.md index 96ddf9d..7666545 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 | @@ -68,8 +69,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 @@ -90,7 +94,7 @@ Each card has at most **one** keyword, chosen deterministically from faction, ho 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 +103,23 @@ 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. +- **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. --- ## 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. - **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 @@ -127,13 +138,21 @@ 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. +- 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 +164,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,8 +181,10 @@ 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 @@ -168,18 +194,19 @@ The match lasts `turns` turns (default **6**, hard cap). Each turn has these pha - 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. + - So the order in which you queue cards matters: lead with the card you want resolved first. - 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. 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). This is simple, it's + fair to both seats, and it doesn't depend on the board. 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,12 +215,12 @@ 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. --- @@ -213,12 +240,13 @@ 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: 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 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 | 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. | | 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,12 +263,12 @@ 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, + "energyByTurn": [1, 2, 3, 4, 5, 6], "energyCarryMax": 1, "bonusEnergy": 0, "underdog": true, + "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], - "onTopicBonus": 2, + "onTopicBonus": [0, 1, 1, 2, 2, 3, 3], "trendUp": 25, "trendDown": -25, "factionSynergyCap": 3, "verifyStats": true, @@ -249,7 +277,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