forked from WikiDeck/wikideck
docs(game): DESIGN.md v1 review fixes and deliberate divergences
- Exact Topic draw algorithm (one RNG order) - onTopicBonus scales with cost (about 2 power per energy on-topic at every cost) - Host swaps in live snapshot before building CardInput; verifyStats caching and fail-open - Commit-reveal seed for hosted PvP; copies count owned and loaners together - Diverge from Snap: lane capacity 3, energy carry-over 1, interleaved alternating reveals, stats visible from turn 1 with hidden Portals, consensus lane tie-break Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
+62
-35
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user