Compare commits

..
Author SHA1 Message Date
claudeandClaude Opus 5.5 0e0596a855 Merge council-designer-b's sections 10-12 (a9ab940) into design fixes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 22:55:10 -05:00
claudeandClaude Opus 5.5 ac46298594 docs(game): critic M1-M4, S1-S5
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 22:54:08 -05:00
claudeandClaude Opus 5.5 a9ab940f4b 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>
2026-11-16 22:53:56 -05:00
claudeandClaude Opus 5.5 175713e8b2 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>
2026-11-16 22:52:54 -05:00
claudeandClaude Opus 5.5 7390a17a91 Night 1: DESIGN.md v1 draft, Edit War lanes game (#12)
Draft of the game rules (sections 0-9); keywords, modes and worked example to follow before the 23:30 freeze.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 03:52:06 +00:00
claudeandClaude Opus 5.5 f507b0eaed Night 1: module boundaries (docs/night/BOUNDARIES.md) (#11)
Records path ownership, test prefixes, shared hook points and off-limits consensus files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 03:51:25 +00:00
claudeandClaude Opus 5.5 f808f963c6 docs(game): starter cards file, mode-variable fields
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 22:49:12 -05:00
claudeandClaude Opus 5.5 01b83f9c9f docs(game): DESIGN.md v1 draft rules sections (council-designer-a)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 22:48:43 -05:00
16 changed files with 551 additions and 1602 deletions
+498
View File
@@ -0,0 +1,498 @@
# WikiDeck: Edit War — game design v1 (draft)
**Status:** v1 DRAFT, freeze target 23:30 EST 2026-11-16.
**Owners:** council-designer-a owns sections 0–9 (research, card derivation, rules). council-designer-b
owns sections 10–12 (keywords, peer-hosted modes, worked example). council-critic reviews.
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) 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
not upgrades.
---
## 0. Research summary (what we took, what we left)
| 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, 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 |
| Slay the Spire | readable intents; every card is a choice | open information about lane state and power | roguelike runs (could be a mode) |
| Gwent | rows; best 2 of 3; passing and bluffing | best 2 of 3 Topics; hidden commitments | multi-round card advantage (too long) |
| Pokémon TCG | type advantage | on-topic bonus (card stat matches lane stat) | energy attachment; coin flips |
| Top Trumps | instantly understood: "my number beats yours" | lanes judged on one stat | picking the stat is solved play (always pick your best) |
| Dominion | deck building as play | — (too long for 3–6 min) | — |
**What is ours, not borrowed:**
- (a) each Topic is judged on one Wikipedia stat (the Top Trumps twist)
- (b) cost comes from an article's fame instead of being printed
- (c) a trend arrow driven by live pageviews
- (d) a total-power and consensus tie-break instead of stakes betting
- smaller choices: 3 slots per lane, 1 carried-over energy, interleaved reveals, and stats visible
from turn 1 with hidden Portals
The core loop is a lanes game in the style of Snap. The Top Trumps twist is that each lane asks for
one Wikipedia stat. That makes every stat matter and gives each turn its main decision: play the card
on-topic for the bonus, or put it where the fight is.
---
## 1. Card derivation (card data → game card)
The engine never reads raw 0–100 stats as power. Every game card is derived **deterministically** from a
`CardInput` that the match host freezes at match start:
```
CardInput = { cardId, pageId, title, category, rarity,
snapshot: MintStatsSnapshot, // at mint, immutable
live: { trendPercent: number | null, dailyAverage: number | null }, // frozen at match start
check: 'verified' | 'unverified' | 'unchecked' | 'loaner' } // set by the host (§1.10)
```
### 1.1 Percentiles (rank-normalisation)
For each stat `s` in {attention, depth, reach}, `pct_s` = the percentile (0–100, integer) of the card's
snapshot score in the reference table `percentiles.<s>`. That table holds 99 ascending cut points from
council-data's `docs/game/card-sample.json`.
`pct_s` = the number of cut points strictly below the score, plus half the number equal to it, rounded
down. A `null` attention gives `pct_attention = null`.
### 1.2 Fame → Cost
`fame` = the integer mean (rounded half up) of the non-null percentiles.
`cost` = 1 + the number of thresholds in `costThresholds` (5 ascending values, default
`[15, 35, 55, 75, 90]`) that are ≤ `fame`. So cost runs 1–6.
The defaults aim at a pool cost spread of about 15/20/20/20/15/10 %. They are retuned from the
sample's fame distribution.
### 1.3 Power
`power` = `powerByCost[cost]`, default `[_, 1, 2, 4, 6, 8, 10]` (cost 1 → 1 … cost 6 → 10). The
critic's sim showed that heavy decks were too weak with `[…5,7,9]`.
Power depends **only on cost**. Two cards of the same cost have the same base power, whatever their
fame. Inflating stats (forged snapshots, template shopping) only moves a card up the curve. It never
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[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
`server/wiki.ts`. Culture is about half the pool, so faction keywords are written so that a
mono-faction deck gains no consistency edge (see §10, and `factionSynergyCap` in §9).
### 1.6 Trend (live, small, capped)
`trend` = +1 if `live.trendPercent ≥ trendUp` (default 25), −1 if `≤ trendDown` (default −25),
otherwise 0. A `null` value gives 0. Trend also needs `live.dailyAverage ≥ trendMinDaily` (default
**20**), because percentages on tiny articles are noise; otherwise trend is 0. The host computes it **once at match start**, and it is frozen for
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.
### 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).
### 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**
(📣 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.
### 1.10 Plausibility (anti-forgery, off-chain)
When `verifyStats` is true (the default for hosted matches), the match host checks each owned card's
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 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.
- **Card can't be verified** (the pageId or revision doesn't exist, or the title or category doesn't
match): the card is **rejected at deck validation**, and the player is asked to swap in a loaner.
- **API failure:** if Wikipedia can't be reached and nothing is cached, the card plays from its snapshot
with `check: 'unchecked'`. The engine then caps its cost at `uncheckedCostCap` (default **4**), and
power follows the capped cost. Matches are never blocked.
- The engine's only use of `check` is that cost cap. Loaner cards are `check: 'loaner'`.
---
## 2. Decks
- **Deck size:** exactly `deckSize` cards (default **12**).
- **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.
- **Deck validation** (engine): the size is right, the copy limit holds, every card's `check` is
valid, and there are no more loaners than `maxLoaners`. An invalid deck can't start a match.
- **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
(`docs/game/starter-cards.json`, picked by council-data: about 24 pageIds across all 6 categories,
with frozen, hand-checked snapshot stats, including the 4 cards in `shared/catalog.ts`).
Loaners follow the same derivation, so they are no weaker or stronger than owned cards.
- **Starter decks:** `starterDecks` (default: 4 fixed 12-card loaner decks). Each one has two leading
factions and an average cost of 3.0–3.3. A new player picks one and can play at once.
- **Mixed decks:** an owned deck may fill any slots with loaners, up to `maxLoaners` (default 12, which
means no limit). Owning NFTs gives **variety**, not power: owned and loaner cards follow the same
curve.
---
## 3. Board
- 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 **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.
---
## 4. Match setup (deterministic)
1. The input is `{ seed: uint32, rules, players: [p0, p1] }`, and each player's input is
`{ id, deck: CardInput[12] }`. Seat order is input order.
2. RNG: **mulberry32(seed)**. Every random choice draws `next()` in this fixed order:
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 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.
---
## 5. Turn structure
The match lasts `turns` turns (default **6**, hard cap). Each turn has these phases:
1. **Start**
- 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** (mode option, `underdog: false` by default, because it can be sandbagged). When
it's on, from turn 2, a player who leads in 0 Topics while the opponent leads in ≥ 2 gets
**+1 energy** this turn.
3. **Plan** (simultaneous, hidden)
- Each player queues an ordered list of plays `(handIndex, topic)`.
- 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 (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.
- Initiative strictly **alternates** each turn (set by the coin in §4).
- Plans are locked before anything reveals, so initiative gives away no information. It only
decides the order of on-reveal effects. §10 includes keywords where that order matters.
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.
---
## 6. Power and Topic control
- 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.
- **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.
---
## 7. Win conditions and tie-breaks
At the end of the last turn:
1. The player who leads **more Topics** wins (2–1, 2–0, 1–0 and 3–0 all count).
2. If they lead the same number of Topics: the higher **total power across all Topics** wins.
3. If that is also equal: the match is a **draw**.
**Concede:** a player can concede at any time, and the opponent wins at once. A player who misses
`afkTurns` timeouts in a row (default **2**) with nothing queued concedes.
---
## 8. Degenerate lines and why they fail (for the critic)
| Line | Why it isn't dominant |
|---|---|
| All-famous (all max-stat) deck | It becomes an all-cost-5/6 deck with dead early turns. Cheap cards are more efficient **per energy**, expensive cards **per card**. Only 9 cards are seen per match (3 + 6 draws), so both matter. The 1-energy carry-over lets a heavy deck bank energy for a turn-5 six-drop. **sim-balance target: heavy vs curve ≥ 40%.** |
| All-cheap flood (cost 1–2) | It runs out of cards (only 9 seen), and its on-topic bonus is only +1. The critic's sim had swarm vs curve at 42%. **sim-balance: test all cost-1/2 decks.** |
| 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 | 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, frozen at match start, and only counts for articles with ≥ 20 views a day. |
| 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). |
---
## 9. Rules config (all defaults)
The engine takes a `RulesConfig` object. Peer-hosted modes override it (§11). Defaults:
```json
{
"version": "1.0",
"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], "energyCarryMax": 1, "bonusEnergy": 0, "underdog": false,
"topicCount": 3, "distinctStats": true, "portalReveal": [2, 3, 4], "laneCapacity": 3,
"topicPool": "default",
"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,
"trendUp": 25, "trendDown": -25, "trendMinDaily": 20, "uncheckedCostCap": 4,
"factionSynergyCap": 3,
"verifyStats": true,
"percentiles": "card-sample-2026-11-16",
"starterDecks": "default"
}
```
**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
(§4); the shape of the derivation (§1: percentile → fame → cost → power); at most one keyword per card;
the phases of a turn (§5).
A mode must keep `turns × turnSeconds ≤ 240` so that matches stay within 3–6 minutes.
---
## 10. Keywords *(owner: council-designer-b)*
### 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)*
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], "portalReveal": [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 |
| `portalReveal` | 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` (7 entries), `vanillaBonus` | 0–5 each |
| `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]`, `portalReveal [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`, `portalReveal [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)*
> **⚠ 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.**
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.
+53
View File
@@ -0,0 +1,53 @@
# Night 1: module boundaries
Owner: `night-lead`. This file is the rule when two PRs touch the same path. If you need to edit a path you don't own, comment on the owner's issue (`[from <you>]`) or keep your change to the "shared hook" listed below.
## Who owns what
| Path | Owner | Issue |
|---|---|---|
| `docs/game/DESIGN.md` | council (designer-a, designer-b, critic) | #1 |
| `docs/game/CARD_DATA.md`, `docs/game/card-sample.json` | council-data | #2 |
| `shared/game/` (types, RNG, state machine, rules, keywords, `Ruleset`, `starterDeck`) | engine-a (core, API), engine-b (keywords, effects) | #3 |
| `docs/game/ENGINE_API.md` | engine-a | #3 |
| `shared/game/modes.ts` | modes | #6 |
| `server/game*` (e.g. `server/game/`, `server/game-*.ts`) | modes | #6 |
| `docs/game/HOSTING.md` | modes | #6 |
| `src/game/` (screens, lobby, deck builder, match, tutorial) | ui-a | #5 |
| `src/game/ai/` (browser bots, easy and normal) | ui-b | #5 |
| beta-fix files outside `src/game/` (landing page, `Card.tsx`, etc.) | ui-b, one PR per upstream issue | #5 |
| `shared/bots/`, `scripts/sim/` (bots and the simulation runner) | sim-balance | #4 |
| `docs/game/BALANCE.md` | sim-balance | #4 |
| `compose.testnet.yaml` overrides, `deploy/night/` (testnet config, per-node mode files) | sim-testnet | #4 |
| `server/account*` (e.g. `server/account/`), `src/auth/` | sso | #7 |
| `android/`, `capacitor.config.ts` | mobile-android | #8 |
| `ios/`, `docs/night/IOS.md` | mobile-ios, macos-fetch | #9 |
| `docs/night/` (except `IOS.md`), this file, `REPORT.md` | night-lead | #10 |
## Tests
`scripts/run-tests.mjs` only picks up **top-level** `tests/*.test.ts`. Name your files with your team as a prefix so they never collide:
`tests/game-*.test.ts` (engine), `tests/modes-*.test.ts`, `tests/ui-*.test.ts`, `tests/bots-*.test.ts`, `tests/account-*.test.ts`.
## Shared hooks (the only places two teams touch the same file)
1. **`server/testnet/http.ts`**: modes and sso each export an Express `Router` from their own files and add **exactly one** `app.use(...)` mount line just **above** the `/api` 404 handler (`app.use(['/api','/p2p'],(_req,res)=>{res.status(404)...`). Nothing else in this file. If SSO needs a CSP change (`connect-src` for `https://dex.eom.dev`), keep it to the `helmet` directive and say so in the PR.
2. **`src/App.tsx`**: ui-a owns it. Others get one import and one element each (sso: a login button or provider; mobile: hide the mining controls behind a `isNativeApp()` check from `src/game/` or `src/auth/`, never by deleting code).
3. **`package.json` and `package-lock.json`**: additive changes only (new dependencies or scripts). Don't reformat or bump existing versions. Lockfile conflicts are resolved by night-lead regenerating the lockfile.
4. **`shared/enrichment.ts`**: read-only for everyone tonight. Map card data into game stats inside `shared/game/`.
## Off limits (consensus and protocol; PRs touching these are rejected)
`server/chain.ts`, `shared/protocol.ts`, `shared/trade-offer.ts`, `shared/chain-identity.ts`, `shared/network.ts`, `server/testnet/consensus.ts`, `server/testnet/ledger.ts`, `server/testnet/canonical-index.ts`, `server/testnet/randomx.ts`, `server/testnet/miner.ts`, `server/testnet/peers.ts`, `native/`.
If you think you need a change there, write it up in your issue instead.
## Dependency direction
`shared/game/` imports nothing from `server/` or `src/` and does no I/O. `shared/game/modes.ts`, `shared/bots/`, `server/game*`, `src/game/` import from `shared/game/` through the API in `ENGINE_API.md`, not from its internals.
## Merging
- Branch `night/<team>/<topic>`, PR into `night/2026-11-16`, squash-merged by night-lead after night-review approves and `npm test` and `npm run build` pass.
- Small PRs merge faster. Rebase on the integration branch before asking for review if it moved under you.
- After 01:10 (code freeze), only fixes merge.
-92
View File
@@ -1,92 +0,0 @@
/**
* Turning WikiDeck data into GameCards, and starter decks for players with no NFTs.
* PLACEHOLDER numbers until docs/game/DESIGN.md v1; engine-b tunes the mapping.
* Starter cards are offline preview cards: not NFTs, never minted or moved.
*/
import { Rng } from './rng.ts';
import { DEFAULT_RULESET } from './ruleset.ts';
import type { Category, GameCard, Ruleset } from './types.ts';
type StarterSpec = [pageId: number, name: string, category: Category, cost: number, power: number, keyword: string | null];
/** 24 curated preview cards, 4 per cost 1–6. pageIds outside shared/catalog.ts are unverified (display only). */
export const STARTER_POOL: readonly StarterSpec[] = [
[22780, 'Octopus', 'Nature', 1, 2, null],
[19331, 'Moon', 'Space', 1, 1, 'anchor'],
[23053, 'Periodic table', 'Science', 1, 2, null],
[3383, 'Bronze Age', 'History', 1, 1, 'rally'],
[5843419, 'Chess', 'Culture', 2, 3, null],
[9228, 'Earth', 'Space', 2, 2, 'rally'],
[2008, 'Ada Lovelace', 'People', 2, 4, null],
[21830, 'Honey bee', 'Nature', 2, 3, 'anchor'],
[736, 'Albert Einstein', 'People', 3, 5, null],
[10979, 'Fungus', 'Nature', 3, 4, 'rally'],
[26903, 'Solar System', 'Space', 3, 6, null],
[30758, 'Roman Empire', 'History', 3, 4, 'anchor'],
[9649, 'Evolution', 'Science', 4, 7, null],
[8424, 'Jazz', 'Culture', 4, 6, 'rally'],
[12898, 'Marie Curie', 'People', 4, 8, null],
[14533, 'Silk Road', 'History', 4, 6, 'anchor'],
[19468, 'Mount Everest', 'Nature', 5, 9, null],
[22936, 'Photosynthesis', 'Science', 5, 8, 'rally'],
[18110, 'Leonardo da Vinci', 'People', 5, 10, null],
[14627, 'Ancient Egypt', 'History', 5, 8, 'anchor'],
[4177, 'Black hole', 'Space', 6, 12, null],
[25443, 'Quantum mechanics', 'Science', 6, 11, 'rally'],
[17867, 'Library of Alexandria', 'History', 6, 11, 'anchor'],
[20217, 'Music', 'Culture', 6, 12, null],
];
export function starterCard(spec: StarterSpec, copy = 0): GameCard {
const [pageId, name, category, cost, power, keyword] = spec;
return { id: `starter:${pageId}:${copy}`, name, pageId, category, cost, power, keyword, source: 'starter' };
}
/**
* A deterministic starter deck: 2 cards of each cost 1–6 (for a 12-card deck),
* drawn from STARTER_POOL by `seed`. Cards whose keyword the ruleset doesn't
* enable still play (as vanilla). Fills to ruleset.deck.min.
*/
export function starterDeck(seed: string, rules: Ruleset = DEFAULT_RULESET): GameCard[] {
const rng = Rng.fromSeed(`starter:${seed}`);
const byCost = new Map<number, StarterSpec[]>();
for (const spec of STARTER_POOL) byCost.set(spec[3], [...(byCost.get(spec[3]) ?? []), spec]);
const picks: StarterSpec[] = [];
const costs = [...byCost.keys()].sort((a, b) => a - b);
for (const cost of costs) picks.push(...rng.shuffle(byCost.get(cost)!).slice(0, 2));
const deck = rng.shuffle(picks).slice(0, rules.deck.max).map(spec => starterCard(spec));
// Pad for modes with bigger decks, respecting maxCopiesPerPage.
let copy = 1;
while (deck.length < rules.deck.min && copy < rules.deck.maxCopiesPerPage) {
for (const spec of rng.shuffle(STARTER_POOL)) {
if (deck.length >= rules.deck.min) break;
deck.push(starterCard(spec, copy));
}
copy++;
}
return deck;
}
/** Input for an owned card; matches PageEnrichment / MintStatsSnapshot fields (shared/enrichment.ts). */
export interface CardSource {
id: string;
title: string;
pageId: number;
category: Category;
stats: { attention: number | null; depth: number; reach: number };
}
/**
* PLACEHOLDER stat → card mapping (DESIGN.md will replace it). Famous cards cost
* more (sidegrade): cost from the mean score, power = 2·cost (+1 if no keyword).
*/
export function cardFromStats(source: CardSource): GameCard {
const { attention, depth, reach } = source.stats;
const mean = ((attention ?? 0) + depth + reach) / 3;
const cost = Math.max(1, Math.min(6, Math.ceil(mean / (100 / 6))));
const keyword = depth >= reach && depth >= (attention ?? 0) ? 'anchor' : reach >= (attention ?? 0) ? 'rally' : null;
return {
id: source.id, name: source.title, pageId: source.pageId, category: source.category,
cost, power: 2 * cost + (keyword ? 0 : 1), keyword, source: 'owned',
};
}
-112
View File
@@ -1,112 +0,0 @@
/**
* Card derivation (DESIGN.md §1): a frozen CardInput becomes a GameCard.
* Pure and deterministic. The engine never reads raw 0–100 stats as power.
*/
export type Stat = 'attention' | 'depth' | 'reach';
export type Faction = 'Space' | 'Nature' | 'People' | 'Science' | 'History' | 'Culture';
export type Rarity = 'Legendary' | 'Epic' | 'Rare' | 'Common';
export const STATS: readonly Stat[] = ['attention', 'depth', 'reach'];
export const FACTIONS: readonly Faction[] = ['Space', 'Nature', 'People', 'Science', 'History', 'Culture'];
/** §1.4 tie-break order: depth and reach are the hardest to inflate. */
export const HOME_TIE_ORDER: readonly Stat[] = ['depth', 'reach', 'attention'];
export interface CardInput {
cardId: string;
pageId: number;
title: string;
category: Faction;
rarity: Rarity;
snapshot: { stats: { attention: number | null; depth: number; reach: number } };
/** Frozen by the host at match start. */
live: { trendPercent: number | null };
}
export interface GameCard {
cardId: string;
pageId: number;
title: string;
faction: Faction;
rarity: Rarity;
cost: number;
power: number;
home: Stat;
trend: -1 | 0 | 1;
keyword: string | null;
}
/** 99 ascending cut points per stat (§1.1). */
export type PercentileTable = Record<Stat, readonly number[]>;
/** The subset of the rules config that card derivation reads. */
export interface DerivationRules {
costThresholds: readonly number[];
powerByCost: readonly number[];
trendUp: number;
trendDown: number;
}
export type KeywordPicker = (card: Omit<GameCard, 'keyword'>) => string | null;
/** §1.1: cut points strictly below, plus half of those equal, rounded down. */
export function percentile(score: number, cuts: readonly number[]): number {
let below = 0, equal = 0;
for (const cut of cuts) {
if (cut < score) below++;
else if (cut === score) equal++;
}
return Math.floor(below + equal / 2);
}
export function percentiles(stats: CardInput['snapshot']['stats'], table: PercentileTable): Record<Stat, number | null> {
return {
attention: stats.attention === null ? null : percentile(stats.attention, table.attention),
depth: percentile(stats.depth, table.depth),
reach: percentile(stats.reach, table.reach),
};
}
/** §1.2: integer mean of the non-null percentiles, rounded half up. */
export function fame(pct: Record<Stat, number | null>): number {
const values = STATS.map(stat => pct[stat]).filter((value): value is number => value !== null);
const sum = values.reduce((total, value) => total + value, 0);
return Math.floor(sum / values.length + 0.5);
}
/** §1.2: 1 + the number of thresholds ≤ fame. */
export function costFor(fameValue: number, thresholds: readonly number[]): number {
return 1 + thresholds.filter(threshold => threshold <= fameValue).length;
}
/** §1.4: highest percentile, ties by depth > reach > attention; null never wins. */
export function homeStat(pct: Record<Stat, number | null>): Stat {
let best: Stat = HOME_TIE_ORDER[0];
for (const stat of HOME_TIE_ORDER) {
const value = pct[stat];
const current = pct[best];
if (value !== null && (current === null || value > current)) best = stat;
}
return best;
}
/** §1.6: ±1 past the thresholds, null → 0. */
export function trendFor(trendPercent: number | null, rules: Pick<DerivationRules, 'trendUp' | 'trendDown'>): -1 | 0 | 1 {
if (trendPercent === null || !Number.isFinite(trendPercent)) return 0;
if (trendPercent >= rules.trendUp) return 1;
if (trendPercent <= rules.trendDown) return -1;
return 0;
}
export function deriveCard(input: CardInput, rules: DerivationRules, table: PercentileTable,
pickKeyword: KeywordPicker = () => null): GameCard {
const pct = percentiles(input.snapshot.stats, table);
const cost = costFor(fame(pct), rules.costThresholds);
const power = rules.powerByCost[cost];
if (power === undefined) throw new RangeError(`powerByCost has no entry for cost ${cost}`);
const base = {
cardId: input.cardId, pageId: input.pageId, title: input.title,
faction: input.category, rarity: input.rarity,
cost, power, home: homeStat(pct), trend: trendFor(input.live.trendPercent, rules),
};
return { ...base, keyword: pickKeyword(base) };
}
-324
View File
@@ -1,324 +0,0 @@
/**
* WikiDeck game engine core: pure, deterministic, off-chain.
* Every exported function treats its inputs as immutable and returns new data.
* All randomness comes from the match seed via state.rng.
* Contract: docs/game/ENGINE_API.md.
*/
import { KEYWORDS, LANE_MODIFIERS, type EffectContext } from './keywords.ts';
import { Rng, seedRng } from './rng.ts';
import { energyForTurn, parseRuleset } from './ruleset.ts';
import {
IllegalActionError, PLAYERS,
type Action, type CardInPlay, type GameCard, type MatchResult, type MatchState,
type PlayerId, type PlayerState, type PlayerView, type Ruleset,
} from './types.ts';
export const ENGINE_VERSION = 1;
const other = (player: PlayerId): PlayerId => (player === 0 ? 1 : 0);
const clone = <T>(value: T): T => structuredClone(value);
// ---------- validation ----------
export function validateDeck(rules: Ruleset, deck: readonly GameCard[]): string[] {
const problems: string[] = [];
if (deck.length < rules.deck.min || deck.length > rules.deck.max)
problems.push(`Deck must have ${rules.deck.min === rules.deck.max ? rules.deck.min : `${rules.deck.min}–${rules.deck.max}`} cards (has ${deck.length})`);
const ids = new Set<string>();
const copies = new Map<number, number>();
for (const card of deck) {
if (typeof card?.id !== 'string' || !card.id || card.id.length > 128) { problems.push('Card id must be a non-empty string'); continue; }
if (ids.has(card.id)) problems.push(`Duplicate card id ${card.id}`);
ids.add(card.id);
if (!Number.isInteger(card.cost) || card.cost < 0 || card.cost > 20) problems.push(`Card ${card.id}: bad cost`);
if (!Number.isInteger(card.power) || card.power < -100 || card.power > 100) problems.push(`Card ${card.id}: bad power`);
if (card.pageId !== null) {
const n = (copies.get(card.pageId) ?? 0) + 1;
copies.set(card.pageId, n);
if (n === rules.deck.maxCopiesPerPage + 1) problems.push(`More than ${rules.deck.maxCopiesPerPage} copies of page ${card.pageId}`);
}
}
return problems;
}
// ---------- match setup ----------
/**
* Start a match. `decks[0]` belongs to player 0. Throws IllegalActionError for an
* invalid deck and ZodError for an invalid ruleset.
*/
export function createMatch(ruleset: Ruleset, decks: readonly [readonly GameCard[], readonly GameCard[]], seed: string): MatchState {
const rules = parseRuleset(clone(ruleset));
if (typeof seed !== 'string' || !seed) throw new IllegalActionError('Seed must be a non-empty string');
for (const player of PLAYERS) {
const problems = validateDeck(rules, decks[player] ?? []);
if (problems.length) throw new IllegalActionError(`Player ${player} deck: ${problems.join('; ')}`);
}
const rng = new Rng(seedRng(seed));
const modifiers = rules.laneModifiers.pool.length ? rng.shuffle(rules.laneModifiers.pool).slice(0, rules.lanes) : [];
const newPlayer = (player: PlayerId): PlayerState => ({
deck: rng.shuffle(clone(decks[player])), hand: [], energy: 0, staged: [], ended: false, discard: [],
});
const players: [PlayerState, PlayerState] = [newPlayer(0), newPlayer(1)];
const state: MatchState = {
schema: 'wikideck-match/1', ruleset: rules, seed, rng: rng.state, turn: 0, phase: 'planning',
firstToReveal: rng.int(2) as PlayerId, players,
lanes: Array.from({ length: rules.lanes }, (_, lane) => ({ modifier: modifiers[lane] ?? null, cards: [[], []] as [CardInPlay[], CardInPlay[]] })),
log: [], actions: [], result: null,
};
for (const player of PLAYERS) for (let i = 0; i < rules.hand.start; i++) draw(state, player);
startTurn(state, rng);
state.rng = rng.state;
return state;
}
function draw(state: MatchState, player: PlayerId): void {
const p = state.players[player];
if (!p.deck.length || p.hand.length >= state.ruleset.hand.max) return;
const card = p.deck.shift()!;
p.hand.push(card);
state.log.push({ t: 'draw', player, cardId: card.id });
}
function startTurn(state: MatchState, rng: Rng): void {
state.turn += 1;
const energy = energyForTurn(state.ruleset, state.turn);
if (state.turn > 1) state.firstToReveal = leader(state, rng);
for (const player of PLAYERS) Object.assign(state.players[player], { energy, staged: [], ended: false });
state.log.push({ t: 'turnStart', turn: state.turn, energy: [energy, energy] });
state.ruleset.laneModifiers.revealTurns.forEach((turn, lane) => {
if (turn === state.turn) state.log.push({ t: 'laneRevealed', lane, modifier: state.lanes[lane].modifier });
});
for (const player of PLAYERS) for (let i = 0; i < state.ruleset.hand.drawPerTurn; i++) draw(state, player);
}
/** Player winning more lanes reveals first; then higher total power; then a seeded coin flip. */
function leader(state: MatchState, rng: Rng): PlayerId {
const { lanesWon, totalPower } = score(state);
if (lanesWon[0] !== lanesWon[1]) return lanesWon[0] > lanesWon[1] ? 0 : 1;
if (totalPower[0] !== totalPower[1]) return totalPower[0] > totalPower[1] ? 0 : 1;
return rng.int(2) as PlayerId;
}
// ---------- power ----------
export function modifierActive(state: MatchState, lane: number): boolean {
const revealTurn = state.ruleset.laneModifiers.revealTurns[lane] ?? 1;
return state.lanes[lane]?.modifier != null && state.turn >= revealTurn;
}
function context(state: MatchState, rng: Rng, params: Record<string, number> | undefined, lane: number, source: string, player: PlayerId): EffectContext {
return { state, rng, params: params ?? {}, lane, log: text => state.log.push({ t: 'effect', source, player, text }) };
}
function keywordOf(state: MatchState, card: GameCard) {
return card.keyword && Object.hasOwn(state.ruleset.keywords, card.keyword) ? KEYWORDS[card.keyword] : undefined;
}
/** Current power of one card in play, including ongoing keyword and lane effects. */
export function cardPower(state: MatchState, target: CardInPlay): number {
const scratch = new Rng(state.rng); // ongoing effects must not consume real randomness
let power = target.card.power + target.bonus;
for (const lane of state.lanes) for (const side of lane.cards) for (const source of side) {
const keyword = keywordOf(state, source.card);
if (keyword?.ongoing) power += keyword.ongoing(context(state, scratch, state.ruleset.keywords[keyword.id], source.lane, keyword.id, source.owner), source, target);
}
const lane = state.lanes[target.lane];
if (modifierActive(state, target.lane)) {
const modifier = LANE_MODIFIERS[lane.modifier!];
if (modifier?.ongoing) power += modifier.ongoing(context(state, scratch, state.ruleset.laneModifiers.params[modifier.id], target.lane, modifier.id, target.owner), target);
}
return power;
}
export function lanePower(state: MatchState, lane: number): [number, number] {
return PLAYERS.map(player => state.lanes[lane].cards[player].reduce((sum, card) => sum + cardPower(state, card), 0)) as [number, number];
}
function score(state: MatchState): Omit<MatchResult, 'winner' | 'reason' | 'turns'> {
const powers = state.lanes.map((_, lane) => lanePower(state, lane));
const lanesWon: [number, number] = [0, 0];
const totalPower: [number, number] = [0, 0];
for (const [a, b] of powers) {
if (a > b) lanesWon[0]++; else if (b > a) lanesWon[1]++;
totalPower[0] += a; totalPower[1] += b;
}
return { lanesWon, lanePower: powers, totalPower };
}
// ---------- actions ----------
function stagedInLane(p: PlayerState, lane: number): number {
return p.staged.filter(play => play.lane === lane).length;
}
function playProblem(state: MatchState, action: Extract<Action, { type: 'play' }>): string | null {
const p = state.players[action.player];
if (p.ended) return 'You already ended your turn';
const card = p.hand.find(c => c.id === action.cardId);
if (!card) return 'Card is not in your hand';
if (p.staged.some(play => play.cardId === action.cardId)) return 'Card is already staged';
if (!Number.isInteger(action.lane) || action.lane < 0 || action.lane >= state.lanes.length) return 'No such lane';
if (card.cost > p.energy) return 'Not enough energy';
if (state.lanes[action.lane].cards[action.player].length + stagedInLane(p, action.lane) >= state.ruleset.laneCapacity) return 'Lane is full';
if (modifierActive(state, action.lane)) {
const modifier = LANE_MODIFIERS[state.lanes[action.lane].modifier!];
const ctx = context(state, new Rng(state.rng), state.ruleset.laneModifiers.params[modifier?.id ?? ''], action.lane, modifier?.id ?? '', action.player);
if (modifier?.canPlay && !modifier.canPlay(ctx, card, action.player)) return `${modifier.name} lane rejects this card`;
}
return null;
}
/** Why `action` is illegal in `state`, or null if it is legal. */
export function actionProblem(state: MatchState, action: Action): string | null {
if (state.phase === 'over') return 'Match is over';
if (!action || (action.player !== 0 && action.player !== 1)) return 'Unknown player';
switch (action.type) {
case 'play': return playProblem(state, action);
case 'unstage': {
const p = state.players[action.player];
if (p.ended) return 'You already ended your turn';
return p.staged.some(play => play.cardId === action.cardId) ? null : 'Card is not staged';
}
case 'endTurn': return state.players[action.player].ended ? 'You already ended your turn' : null;
case 'concede': return null;
default: return 'Unknown action';
}
}
/**
* Every legal action for `player` except `concede` (always legal while the match
* is running). `endTurn` is always included while the player hasn't ended.
*/
export function legalActions(state: MatchState, player: PlayerId): Action[] {
if (state.phase === 'over') return [];
const p = state.players[player];
if (p.ended) return [];
const actions: Action[] = [];
for (const card of p.hand) {
if (p.staged.some(play => play.cardId === card.id)) continue;
for (let lane = 0; lane < state.lanes.length; lane++) {
const action: Action = { type: 'play', player, cardId: card.id, lane };
if (!playProblem(state, action)) actions.push(action);
}
}
for (const play of p.staged) actions.push({ type: 'unstage', player, cardId: play.cardId });
actions.push({ type: 'endTurn', player });
return actions;
}
/** Apply one action and return the new state. Throws IllegalActionError if illegal. */
export function applyAction(state: MatchState, action: Action): MatchState {
const problem = actionProblem(state, action);
if (problem) throw new IllegalActionError(problem);
const next = clone(state);
next.actions.push(clone(action));
const p = next.players[action.player];
const rng = new Rng(next.rng);
switch (action.type) {
case 'play': {
p.staged.push({ cardId: action.cardId, lane: action.lane });
p.energy -= p.hand.find(c => c.id === action.cardId)!.cost;
break;
}
case 'unstage': {
const index = p.staged.findIndex(play => play.cardId === action.cardId);
p.staged.splice(index, 1);
p.energy += p.hand.find(c => c.id === action.cardId)!.cost;
break;
}
case 'endTurn': {
p.ended = true;
if (next.players.every(player => player.ended)) resolveTurn(next, rng);
break;
}
case 'concede': {
next.log.push({ t: 'concede', player: action.player });
finish(next, other(action.player), 'concede');
break;
}
}
next.rng = rng.state;
return next;
}
function resolveTurn(state: MatchState, rng: Rng): void {
for (const player of [state.firstToReveal, other(state.firstToReveal)]) {
const p = state.players[player];
for (const play of p.staged) {
const index = p.hand.findIndex(c => c.id === play.cardId);
const [card] = p.hand.splice(index, 1);
const inPlay: CardInPlay = { card, owner: player, lane: play.lane, turn: state.turn, bonus: 0 };
state.lanes[play.lane].cards[player].push(inPlay);
state.log.push({ t: 'reveal', player, cardId: card.id, lane: play.lane });
const keyword = keywordOf(state, card);
keyword?.onReveal?.(context(state, rng, state.ruleset.keywords[keyword.id], play.lane, keyword.id, player), inPlay);
if (modifierActive(state, play.lane)) {
const modifier = LANE_MODIFIERS[state.lanes[play.lane].modifier!];
modifier?.onReveal?.(context(state, rng, state.ruleset.laneModifiers.params[modifier.id], play.lane, modifier.id, player), inPlay);
}
}
p.staged = [];
}
if (state.turn >= state.ruleset.maxTurns) finish(state, null, 'lanes');
else startTurn(state, rng);
}
function finish(state: MatchState, concedeWinner: PlayerId | null, reason: 'lanes' | 'concede'): void {
const s = score(state);
let winner: PlayerId | null = concedeWinner;
let why: MatchResult['reason'] = reason;
if (reason !== 'concede') {
if (s.lanesWon[0] !== s.lanesWon[1]) winner = s.lanesWon[0] > s.lanesWon[1] ? 0 : 1;
else if (state.ruleset.tieBreak === 'totalPower' && s.totalPower[0] !== s.totalPower[1]) {
winner = s.totalPower[0] > s.totalPower[1] ? 0 : 1; why = 'totalPower';
} else why = 'draw';
}
state.result = { winner, reason: why, ...s, turns: state.turn };
state.phase = 'over';
state.log.push({ t: 'matchOver', result: state.result });
}
// ---------- queries ----------
export function isOver(state: MatchState): boolean { return state.phase === 'over'; }
/** The final result, or null while the match is running. */
export function result(state: MatchState): MatchResult | null { return state.result; }
/** Hidden-information view for one player. UI and AI should only ever read this. */
export function viewFor(state: MatchState, you: PlayerId): PlayerView {
const them = other(you);
const me = state.players[you], opp = state.players[them];
return clone({
you, ruleset: state.ruleset, turn: state.turn, phase: state.phase, firstToReveal: state.firstToReveal,
energy: me.energy, hand: me.hand, staged: me.staged, ended: me.ended, deckCount: me.deck.length,
opponent: { handCount: opp.hand.length - opp.staged.length, deckCount: opp.deck.length, stagedCount: opp.staged.length, ended: opp.ended },
lanes: state.lanes.map((lane, index) => {
const revealed = modifierActive(state, index);
const power = lanePower(state, index);
return {
modifier: revealed ? lane.modifier : null, modifierRevealed: revealed,
cards: [lane.cards[you], lane.cards[them]] as [CardInPlay[], CardInPlay[]],
power: [power[you], power[them]] as [number, number],
};
}),
result: state.result,
});
}
// ---------- serialisation / replay ----------
export function serialize(state: MatchState): string { return JSON.stringify(state); }
export function deserialize(json: string): MatchState {
const state = JSON.parse(json) as MatchState;
if (state?.schema !== 'wikideck-match/1') throw new Error('Not a wikideck-match/1 state');
state.ruleset = parseRuleset(state.ruleset);
return state;
}
/** Rebuild a match from its inputs; a host can verify a reported result this way. */
export function replay(ruleset: Ruleset, decks: readonly [readonly GameCard[], readonly GameCard[]], seed: string, actions: readonly Action[]): MatchState {
return actions.reduce(applyAction, createMatch(ruleset, decks, seed));
}
-10
View File
@@ -1,10 +0,0 @@
/** Public entry point of the WikiDeck game engine. See docs/game/ENGINE_API.md. */
export * from './types.ts';
export { Rng, seedRng, type RngState } from './rng.ts';
export { DEFAULT_RULESET, RulesetSchema, parseRuleset, energyForTurn } from './ruleset.ts';
export {
ENGINE_VERSION, createMatch, legalActions, applyAction, actionProblem, isOver, result, viewFor,
serialize, deserialize, replay, validateDeck, cardPower, lanePower, modifierActive,
} from './engine.ts';
export { KEYWORDS, LANE_MODIFIERS, CATEGORY_ORDER, MENTION_TOKEN_PREFIX, hiddenFrom, laneFaction, type KeywordDef, type LaneModifierDef, type EffectContext } from './keywords.ts';
export { STARTER_POOL, starterCard, starterDeck, cardFromStats, type CardSource } from './cards.ts';
-208
View File
@@ -1,208 +0,0 @@
/**
* Keyword and lane-modifier registry. Effects are code here, but which ones a
* mode uses and their numbers are data (Ruleset.keywords / laneModifiers.params).
* Owner: engine-b (claude/wikideck#3). engine-a owns the hook contract below.
*
* Hook contract:
* - onReveal: runs once when the card is revealed, after it is placed in its lane.
* May mutate ctx.state (e.g. add `bonus` to cards, draw cards) but must use ctx.rng
* for any randomness and must not throw.
* - ongoing: pure; returns a power delta for `target` while `source` is in play.
* Called for every (source, target) pair in play, including source === target.
* - Lane modifiers have the same shape; `source` is null and `lane` is the modifier's lane.
* canPlay lets a lane reject a card (checked when staging).
*/
import type { Rng } from './rng.ts';
import type { CardInPlay, Category, GameCard, MatchState, PlayerId } from './types.ts';
export interface EffectContext {
state: MatchState;
rng: Rng;
/** Tunable numbers for this keyword/modifier from the ruleset. */
params: Record<string, number>;
lane: number;
log(text: string): void;
/** Current power of a card in play (engine's cardPower). Optional so tests can build contexts by hand. */
power?(card: CardInPlay): number;
}
export interface KeywordDef {
id: string;
name: string;
/** Short rules text with {param} placeholders, for card faces/tooltips. */
text: string;
onReveal?(ctx: EffectContext, self: CardInPlay): void;
ongoing?(ctx: EffectContext, self: CardInPlay, target: CardInPlay): number;
/** Runs at the end of each turn while in play (after all reveals). May mutate ctx.state. */
endOfTurn?(ctx: EffectContext, self: CardInPlay): void;
}
export interface LaneModifierDef {
id: string;
name: string;
text: string;
/** Runs when any card is revealed in this lane (after its own onReveal). */
onReveal?(ctx: EffectContext, card: CardInPlay): void;
ongoing?(ctx: EffectContext, target: CardInPlay): number;
canPlay?(ctx: EffectContext, card: GameCard, player: PlayerId): boolean;
}
/** Cards on the same side of the same lane, excluding `self`. */
export function allies(state: MatchState, self: CardInPlay): CardInPlay[] {
return state.lanes[self.lane].cards[self.owner].filter(card => card !== self);
}
/** Faction of a lane (its Topic), or null. v1: an active `portal` lane modifier names one. */
export function laneFaction(state: MatchState, lane: number): Category | null {
const l = state.lanes[lane];
if (!l || l.modifier !== 'portal') return null;
const revealTurn = state.ruleset.laneModifiers.revealTurns[lane] ?? 1;
if (state.turn < revealTurn) return null;
return CATEGORY_ORDER[state.ruleset.laneModifiers.params.portal?.categoryIndex ?? 0] ?? null;
}
/** Ongoing power of a card, excluding effects that need the full engine (base + bonus + ongoing keywords here). */
function sidePower(ctx: EffectContext, lane: number, owner: PlayerId, exclude?: CardInPlay): number {
return ctx.state.lanes[lane].cards[owner].filter(card => card !== exclude)
.reduce((sum, card) => sum + (ctx.power ? ctx.power(card) : card.card.power + card.bonus), 0);
}
/** True when `card` should be shown face down to `viewer` (Obscure). viewFor uses this. */
export function hiddenFrom(state: MatchState, card: CardInPlay, viewer: PlayerId): boolean {
return card.owner !== viewer && state.phase !== 'over' && card.card.keyword === 'obscure'
&& Object.hasOwn(state.ruleset.keywords, 'obscure');
}
export const MENTION_TOKEN_PREFIX = 'token:mention:';
export const KEYWORDS: Record<string, KeywordDef> = {
// engine-a's original examples, kept for the placeholder starter pool and modes.
rally: {
id: 'rally', name: 'Rally', text: 'On reveal: +{amount} power to your other cards here.',
onReveal(ctx, self) {
const amount = ctx.params.amount ?? 1;
for (const ally of allies(ctx.state, self)) ally.bonus += amount;
ctx.log(`Rally +${amount}`);
},
},
anchor: {
id: 'anchor', name: 'Anchor', text: 'Ongoing: +{amount} power if this is your only card here.',
ongoing(ctx, self, target) {
return target === self && allies(ctx.state, self).length === 0 ? ctx.params.amount ?? 2 : 0;
},
},
// DESIGN.md (designer-b draft) §7.
edition: {
id: 'edition', name: 'Edition', text: 'Ongoing: +{amount} power for each other copy of this article on your side.',
ongoing(ctx, self, target) {
if (target !== self || self.card.pageId === null) return 0;
let copies = 0;
for (const lane of ctx.state.lanes) for (const card of lane.cards[self.owner])
if (card !== self && card.card.pageId === self.card.pageId) copies++;
return copies * (ctx.params.amount ?? 2);
},
},
translated: {
id: 'translated', name: 'Translated', text: 'On reveal: +{amount} power to your first card in each other Topic.',
onReveal(ctx, self) {
const amount = ctx.params.amount ?? 1;
ctx.state.lanes.forEach((lane, index) => {
const first = lane.cards[self.owner][0];
if (index !== self.lane && first) {
first.bonus += amount;
ctx.log(`Translated +${amount} to ${first.card.name}`);
}
});
},
},
viral: {
id: 'viral', name: 'Viral', text: 'On reveal: add a {amount}-power Mention to a random other Topic with space.',
onReveal(ctx, self) {
const cap = ctx.state.ruleset.laneCapacity;
const open = ctx.state.lanes.map((lane, index) => ({ lane, index }))
.filter(({ lane, index }) => index !== self.lane && lane.cards[self.owner].length < cap)
.map(({ index }) => index);
if (!open.length) return;
const lane = open[ctx.rng.int(open.length)];
const token: GameCard = {
id: `${MENTION_TOKEN_PREFIX}${self.card.id}:${ctx.state.turn}`, name: 'Mention', pageId: null,
category: self.card.category, cost: 0, power: ctx.params.amount ?? 1, keyword: null, source: 'loaner',
meta: { token: true },
};
ctx.state.lanes[lane].cards[self.owner].push({ card: token, owner: self.owner, lane, turn: ctx.state.turn, bonus: 0 });
ctx.log(`Viral: Mention in lane ${lane + 1}`);
},
},
rising: {
id: 'rising', name: 'Rising', text: 'End of turn: +{amount} power (up to +{max}).',
endOfTurn(ctx, self) {
const amount = ctx.params.amount ?? 1, max = ctx.params.max ?? 3;
const risen = Number(self.card.meta?.risen ?? 0);
const gain = Math.max(0, Math.min(amount, max - risen));
if (!gain) return;
self.bonus += gain;
self.card.meta = { ...self.card.meta, risen: risen + gain };
ctx.log(`Rising +${gain}`);
},
},
nostalgic: {
id: 'nostalgic', name: 'Nostalgic', text: "On reveal: if you're losing here, +{amount} power.",
onReveal(ctx, self) {
const mine = sidePower(ctx, self.lane, self.owner, self);
const theirs = sidePower(ctx, self.lane, self.owner === 0 ? 1 : 0);
if (mine < theirs) {
self.bonus += ctx.params.amount ?? 3;
ctx.log(`Nostalgic +${ctx.params.amount ?? 3}`);
}
},
},
encyclopedic: {
id: 'encyclopedic', name: 'Encyclopedic', text: "Can't have its power reduced. On reveal: if it's your only card here, +{amount} power.",
onReveal(ctx, self) {
if (allies(ctx.state, self).length === 0) {
self.bonus += ctx.params.amount ?? 2;
ctx.log(`Encyclopedic +${ctx.params.amount ?? 2}`);
}
},
// Floor: cancel any negative bonus on itself (v1 has no negative effects; kept for modes).
ongoing(_ctx, self, target) { return target === self && self.bonus < 0 ? -self.bonus : 0; },
},
obscure: {
id: 'obscure', name: 'Obscure', text: 'The opponent sees this card face down until the match ends.',
},
local: {
id: 'local', name: 'Local', text: "Ongoing: +{amount} power in a Topic of this card's faction.",
ongoing(ctx, self, target) {
return target === self && laneFaction(ctx.state, self.lane) === self.card.category ? ctx.params.amount ?? 2 : 0;
},
},
wildcard: {
id: 'wildcard', name: 'Wildcard', text: "On reveal: this card's faction becomes its Topic's faction.",
onReveal(ctx, self) {
const faction = laneFaction(ctx.state, self.lane);
if (faction && faction !== self.card.category) {
self.card.category = faction;
ctx.log(`Wildcard becomes ${faction}`);
}
},
},
};
export const LANE_MODIFIERS: Record<string, LaneModifierDef> = {
plain: { id: 'plain', name: 'Plain', text: 'No effect.' },
portal: {
id: 'portal', name: 'Portal', text: 'Cards of category {category} get +{amount} power here.',
// params.categoryIndex picks from CATEGORY_ORDER so params stay numeric.
ongoing(ctx, target) {
const category = CATEGORY_ORDER[ctx.params.categoryIndex ?? 0];
return target.card.category === category ? ctx.params.amount ?? 2 : 0;
},
},
narrow: {
id: 'narrow', name: 'Narrow', text: 'Only cards costing {maxCost} or less can be played here.',
canPlay(ctx, card) { return card.cost <= (ctx.params.maxCost ?? 3); },
},
};
export const CATEGORY_ORDER = ['Space', 'Nature', 'People', 'Science', 'History', 'Culture'] as const;
-73
View File
@@ -1,73 +0,0 @@
/**
* Seeded, serialisable PRNG for the game engine (off-chain only).
* sfc32 seeded by cyrb128 of a string. The state is four uint32 numbers so it
* round-trips through JSON and a match can be resumed or replayed exactly.
*/
export type RngState = [number, number, number, number];
function cyrb128(text: string): RngState {
let h1 = 1779033703, h2 = 3144134277, h3 = 1013904242, h4 = 2773480762;
for (let i = 0; i < text.length; i++) {
const k = text.charCodeAt(i);
h1 = h2 ^ Math.imul(h1 ^ k, 597399067);
h2 = h3 ^ Math.imul(h2 ^ k, 2869860233);
h3 = h4 ^ Math.imul(h3 ^ k, 951274213);
h4 = h1 ^ Math.imul(h4 ^ k, 2716044179);
}
h1 = Math.imul(h3 ^ (h1 >>> 18), 597399067);
h2 = Math.imul(h4 ^ (h2 >>> 22), 2869860233);
h3 = Math.imul(h1 ^ (h3 >>> 17), 951274213);
h4 = Math.imul(h2 ^ (h4 >>> 19), 2716044179);
h1 ^= h2 ^ h3 ^ h4; h2 ^= h1; h3 ^= h1; h4 ^= h1;
return [h1 >>> 0, h2 >>> 0, h3 >>> 0, h4 >>> 0];
}
export function seedRng(seed: string): RngState {
const state = cyrb128(seed);
// Warm up so similar seeds diverge.
const rng = new Rng(state);
for (let i = 0; i < 12; i++) rng.nextUint32();
return rng.state;
}
/** Mutable wrapper over an RngState. The engine keeps `state` inside MatchState. */
export class Rng {
state: RngState;
constructor(state: RngState) { this.state = [state[0] >>> 0, state[1] >>> 0, state[2] >>> 0, state[3] >>> 0]; }
static fromSeed(seed: string): Rng { return new Rng(seedRng(seed)); }
nextUint32(): number {
let [a, b, c, d] = this.state;
const t = (((a + b) | 0) + d) | 0;
d = (d + 1) | 0;
a = b ^ (b >>> 9);
b = (c + (c << 3)) | 0;
c = (c << 21) | (c >>> 11);
c = (c + t) | 0;
this.state = [a >>> 0, b >>> 0, c >>> 0, d >>> 0];
return t >>> 0;
}
/** Float in [0, 1). */
next(): number { return this.nextUint32() / 4294967296; }
/** Integer in [0, n). Unbiased via rejection sampling. */
int(n: number): number {
if (!Number.isInteger(n) || n <= 0 || n > 4294967296) throw new RangeError('Rng.int needs a positive integer bound');
const limit = 4294967296 - (4294967296 % n);
let x: number;
do x = this.nextUint32(); while (x >= limit);
return x % n;
}
pick<T>(items: readonly T[]): T {
if (!items.length) throw new RangeError('Rng.pick on empty list');
return items[this.int(items.length)];
}
/** Fisher–Yates; returns a new array. */
shuffle<T>(items: readonly T[]): T[] {
const out = items.slice();
for (let i = out.length - 1; i > 0; i--) {
const j = this.int(i + 1);
[out[i], out[j]] = [out[j], out[i]];
}
return out;
}
}
-70
View File
@@ -1,70 +0,0 @@
/**
* Ruleset: every rule number as data, so peer-hosted modes can vary them
* without running code. parseRuleset() is the only way untrusted JSON should
* become a Ruleset; it enforces bounds that keep matches short and terminating.
*/
import { z } from 'zod';
import { KEYWORDS, LANE_MODIFIERS } from './keywords.ts';
import type { Ruleset } from './types.ts';
const int = (min: number, max: number) => z.number().int().min(min).max(max);
const params = z.record(z.string().max(32), z.number().finite().min(-100).max(100))
.refine(value => Object.keys(value).length <= 8, 'Too many params');
export const RulesetSchema = z.object({
id: z.string().regex(/^[a-z0-9][a-z0-9-]{0,47}$/),
name: z.string().min(1).max(64),
version: int(1, 1_000_000),
lanes: int(1, 5),
laneCapacity: int(1, 8),
maxTurns: int(1, 12),
deck: z.object({ min: int(1, 40), max: int(1, 40), maxCopiesPerPage: int(1, 40) }).strict(),
hand: z.object({ start: int(0, 10), max: int(1, 12), drawPerTurn: int(0, 3) }).strict(),
energy: z.object({ start: int(0, 20), perTurn: int(0, 5), max: int(1, 20) }).strict(),
keywords: z.record(z.string(), params).refine(value => Object.keys(value).length <= 32, 'Too many keywords'),
laneModifiers: z.object({
pool: z.array(z.string()).max(32),
revealTurns: z.array(int(1, 12)).max(5),
params: z.record(z.string(), params),
}).strict(),
tieBreak: z.enum(['totalPower', 'draw']),
}).strict().superRefine((rules, ctx) => {
const issue = (message: string) => ctx.addIssue({ code: 'custom', message });
if (rules.deck.min > rules.deck.max) issue('deck.min > deck.max');
if (rules.hand.start > rules.hand.max) issue('hand.start > hand.max');
if (rules.energy.start > rules.energy.max) issue('energy.start > energy.max');
if (rules.laneModifiers.revealTurns.length !== rules.lanes) issue('laneModifiers.revealTurns must have one entry per lane');
if (rules.laneModifiers.pool.length && rules.laneModifiers.pool.length < rules.lanes) issue('laneModifiers.pool needs at least one modifier per lane (or be empty)');
for (const id of Object.keys(rules.keywords)) if (!Object.hasOwn(KEYWORDS, id)) issue(`Unknown keyword: ${id}`);
for (const id of [...rules.laneModifiers.pool, ...Object.keys(rules.laneModifiers.params)])
if (!Object.hasOwn(LANE_MODIFIERS, id)) issue(`Unknown lane modifier: ${id}`);
});
/** Validate untrusted ruleset JSON. Throws a ZodError with readable issues. */
export function parseRuleset(input: unknown): Ruleset {
return RulesetSchema.parse(input) as Ruleset;
}
/** Placeholder base rules (Snap-style lanes) until DESIGN.md v1 lands. */
export const DEFAULT_RULESET: Ruleset = {
id: 'wikideck-standard',
name: 'WikiDeck Standard',
version: 1,
lanes: 3,
laneCapacity: 4,
maxTurns: 6,
deck: { min: 12, max: 12, maxCopiesPerPage: 2 },
hand: { start: 3, max: 7, drawPerTurn: 1 },
energy: { start: 1, perTurn: 1, max: 6 },
keywords: { rally: { amount: 1 }, anchor: { amount: 2 } },
laneModifiers: {
pool: ['plain', 'portal', 'narrow'],
revealTurns: [1, 2, 3],
params: { portal: { categoryIndex: 0, amount: 2 }, narrow: { maxCost: 3 } },
},
tieBreak: 'totalPower',
};
export function energyForTurn(rules: Ruleset, turn: number): number {
return Math.min(rules.energy.max, rules.energy.start + (turn - 1) * rules.energy.perTurn);
}
-158
View File
@@ -1,158 +0,0 @@
/**
* WikiDeck game engine types (off-chain). Everything here is plain JSON data:
* MatchState round-trips through JSON.stringify/parse with no loss.
* Contract: docs/game/ENGINE_API.md. Announce changes on claude/wikideck#3.
*/
import type { RngState } from './rng.ts';
export type PlayerId = 0 | 1;
export const PLAYERS: readonly PlayerId[] = [0, 1];
/** Category buckets from server/wiki.ts. */
export type Category = 'Space' | 'Nature' | 'People' | 'Science' | 'History' | 'Culture';
/** A card as the engine sees it. Built from enrichment data by cards.ts, or a starter/loaner card. */
export interface GameCard {
/** Unique within one deck (e.g. the NFT card hash, or `starter:<pageId>:<n>`). */
id: string;
name: string;
pageId: number | null;
category: Category;
cost: number;
power: number;
/** Keyword id from the ruleset's keyword list, or null. */
keyword: string | null;
/** 'owned' = an NFT the player holds (never moved or burned by a match). */
source: 'owned' | 'starter' | 'loaner';
/** Optional display/tie-break data; never used for rules unless a keyword says so. */
meta?: Record<string, string | number | boolean | null>;
}
/** All rule numbers. Peer-hosted modes override these as data (see ruleset.ts). */
export interface Ruleset {
id: string;
name: string;
version: number;
lanes: number;
/** Cards that may sit on one side of one lane. */
laneCapacity: number;
maxTurns: number;
deck: { min: number; max: number; maxCopiesPerPage: number };
hand: { start: number; max: number; drawPerTurn: number };
/** Energy available on turn t (1-based) = min(max, start + (t - 1) * perTurn). Unspent energy is lost. */
energy: { start: number; perTurn: number; max: number };
/** Keyword ids that cards may carry in this mode, with tunable numbers per keyword. */
keywords: Record<string, Record<string, number>>;
laneModifiers: {
/** Pool of lane modifier ids; one is drawn (without replacement) per lane at match start. */
pool: string[];
/** Turn on which lane i's modifier becomes visible and active (length = lanes). */
revealTurns: number[];
params: Record<string, Record<string, number>>;
};
/** How the match ends when lanes tie on count. */
tieBreak: 'totalPower' | 'draw';
}
export interface CardInPlay {
card: GameCard;
owner: PlayerId;
lane: number;
/** Turn the card was revealed. */
turn: number;
/** Permanent power changes from effects (onReveal buffs etc.). */
bonus: number;
}
export interface StagedPlay { cardId: string; lane: number }
export interface PlayerState {
deck: GameCard[];
hand: GameCard[];
/** Energy left this turn (after staging). */
energy: number;
/** Plays chosen this turn, hidden from the opponent until reveal. Order matters. */
staged: StagedPlay[];
ended: boolean;
discard: GameCard[];
}
export interface LaneState {
modifier: string | null;
cards: [CardInPlay[], CardInPlay[]];
}
export type MatchPhase = 'planning' | 'over';
export type LogEvent =
| { t: 'turnStart'; turn: number; energy: [number, number] }
| { t: 'draw'; player: PlayerId; cardId: string }
| { t: 'reveal'; player: PlayerId; cardId: string; lane: number }
| { t: 'laneRevealed'; lane: number; modifier: string | null }
| { t: 'effect'; source: string; player: PlayerId; text: string }
| { t: 'concede'; player: PlayerId }
| { t: 'matchOver'; result: MatchResult };
export interface MatchState {
schema: 'wikideck-match/1';
ruleset: Ruleset;
seed: string;
rng: RngState;
turn: number;
phase: MatchPhase;
/** Player who reveals first this turn. */
firstToReveal: PlayerId;
players: [PlayerState, PlayerState];
lanes: LaneState[];
log: LogEvent[];
/** Every action applied so far: (ruleset, decks, seed, actions) replays the match exactly. */
actions: Action[];
result: MatchResult | null;
}
export type Action =
| { type: 'play'; player: PlayerId; cardId: string; lane: number }
/** Take back a staged (unrevealed) play this turn; refunds its energy. */
| { type: 'unstage'; player: PlayerId; cardId: string }
| { type: 'endTurn'; player: PlayerId }
| { type: 'concede'; player: PlayerId };
export interface MatchResult {
/** null = draw. */
winner: PlayerId | null;
reason: 'lanes' | 'totalPower' | 'draw' | 'concede';
lanesWon: [number, number];
/** lanePower[lane][player] at the end. */
lanePower: [number, number][];
totalPower: [number, number];
turns: number;
}
/** What one player is allowed to see. Use this for UI and AI, never raw MatchState. */
export interface PlayerView {
you: PlayerId;
ruleset: Ruleset;
turn: number;
phase: MatchPhase;
firstToReveal: PlayerId;
energy: number;
hand: GameCard[];
staged: StagedPlay[];
ended: boolean;
deckCount: number;
opponent: { handCount: number; deckCount: number; stagedCount: number; ended: boolean };
lanes: {
/** null when not yet revealed. */
modifier: string | null;
modifierRevealed: boolean;
/** cards[0] = yours, cards[1] = opponent's (revealed only). */
cards: [CardInPlay[], CardInPlay[]];
/** power[0] = yours, power[1] = opponent's. */
power: [number, number];
}[];
result: MatchResult | null;
}
export class IllegalActionError extends Error {
constructor(message: string) { super(message); this.name = 'IllegalActionError'; }
}
-105
View File
@@ -1,105 +0,0 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
percentile, percentiles, fame, costFor, homeStat, trendFor, deriveCard,
type CardInput, type PercentileTable, type DerivationRules,
} from '../shared/game/derive.ts';
import { forAll } from './game/property.ts';
/** Cut points 1..99: score s sits at percentile ~s, which makes examples readable. */
const LINEAR = Array.from({ length: 99 }, (_, i) => i + 1);
const TABLE: PercentileTable = { attention: LINEAR, depth: LINEAR, reach: LINEAR };
const RULES: DerivationRules = {
costThresholds: [15, 35, 55, 75, 90], powerByCost: [0, 1, 2, 4, 5, 7, 9], trendUp: 25, trendDown: -25,
};
function input(stats: CardInput['snapshot']['stats'], trendPercent: number | null = null): CardInput {
return { cardId: 'c1', pageId: 1, title: 'T', category: 'Science', rarity: 'Common',
snapshot: { stats }, live: { trendPercent } };
}
test('percentile counts cuts strictly below plus half of equal ones, rounded down (§1.1)', () => {
assert.equal(percentile(0, LINEAR), 0);
assert.equal(percentile(50, LINEAR), 49); // 49 below + 0.5 equal → 49
assert.equal(percentile(50.5, LINEAR), 50);
assert.equal(percentile(1000, LINEAR), 99);
assert.equal(percentile(5, [5, 5, 5, 5]), 2);
assert.equal(percentile(5, [1, 5, 5, 9]), 2); // 1 + 2/2
});
test('null attention gives a null percentile and is ignored by fame (§1.1, §1.2)', () => {
const pct = percentiles({ attention: null, depth: 61, reach: 31 }, TABLE);
assert.deepEqual(pct, { attention: null, depth: 60, reach: 30 });
assert.equal(fame(pct), 45);
});
test('fame rounds half up', () => {
assert.equal(fame({ attention: 10, depth: 11, reach: null }), 11); // 10.5 → 11
assert.equal(fame({ attention: 10, depth: 10, reach: 11 }), 10); // 10.33 → 10
assert.equal(fame({ attention: 10, depth: 11, reach: 11 }), 11); // 10.67 → 11
});
test('cost is 1 + thresholds ≤ fame, spanning 1–6 (§1.2)', () => {
const t = RULES.costThresholds;
assert.equal(costFor(0, t), 1);
assert.equal(costFor(14, t), 1);
assert.equal(costFor(15, t), 2);
assert.equal(costFor(54, t), 3);
assert.equal(costFor(55, t), 4);
assert.equal(costFor(89, t), 5);
assert.equal(costFor(90, t), 6);
assert.equal(costFor(100, t), 6);
});
test('home stat is the highest percentile, ties broken depth > reach > attention (§1.4)', () => {
assert.equal(homeStat({ attention: 90, depth: 10, reach: 10 }), 'attention');
assert.equal(homeStat({ attention: 50, depth: 50, reach: 50 }), 'depth');
assert.equal(homeStat({ attention: 50, depth: 40, reach: 50 }), 'reach');
assert.equal(homeStat({ attention: 60, depth: 40, reach: 60 }), 'reach');
assert.equal(homeStat({ attention: null, depth: 0, reach: 0 }), 'depth');
assert.equal(homeStat({ attention: null, depth: 0, reach: 1 }), 'reach');
});
test('trend is ±1 at the inclusive thresholds and 0 for null (§1.6)', () => {
assert.equal(trendFor(25, RULES), 1);
assert.equal(trendFor(24.9, RULES), 0);
assert.equal(trendFor(-25, RULES), -1);
assert.equal(trendFor(-24.9, RULES), 0);
assert.equal(trendFor(null, RULES), 0);
assert.equal(trendFor(Number.NaN, RULES), 0);
assert.equal(trendFor(1e9, RULES), 1); // inflated live views are still worth only +1
});
test('deriveCard assembles cost, power, home, faction and trend', () => {
const card = deriveCard(input({ attention: 81, depth: 71, reach: 61 }, 40), RULES, TABLE);
// pct 80/70/60 → fame 70 → cost 4 → power 5
assert.deepEqual(card, { cardId: 'c1', pageId: 1, title: 'T', faction: 'Science', rarity: 'Common',
cost: 4, power: 5, home: 'attention', trend: 1, keyword: null });
});
test('deriveCard passes the keyword picker the derived card', () => {
const card = deriveCard(input({ attention: 10, depth: 20, reach: 30 }), RULES, TABLE,
base => `${base.faction}:${base.home}:${base.cost}`);
assert.equal(card.keyword, 'Science:reach:2');
});
test('power depends only on cost: forged 100/100/100 stats only move a card up the curve (§1.3)', () => {
const forged = deriveCard(input({ attention: 100, depth: 100, reach: 100 }), RULES, TABLE);
assert.equal(forged.cost, 6);
assert.equal(forged.power, RULES.powerByCost[6]);
forAll(300, g => {
const stats = { attention: g.bool(0.1) ? null : g.int(0, 100), depth: g.int(0, 100), reach: g.int(0, 100) };
const card = deriveCard(input(stats, g.bool(0.2) ? null : g.int(-100, 100)), RULES, TABLE);
assert.ok(card.cost >= 1 && card.cost <= 6);
assert.equal(card.power, RULES.powerByCost[card.cost]);
assert.ok(stats[card.home] !== null, 'home is never a null stat');
// Raising any single stat never lowers cost.
const bumped = { ...stats, depth: Math.min(100, stats.depth + g.int(1, 30)) };
assert.ok(deriveCard(input(bumped), RULES, TABLE).cost >= card.cost);
});
});
test('deriveCard rejects a rules config without a power for the derived cost', () => {
assert.throws(() => deriveCard(input({ attention: 100, depth: 100, reach: 100 }),
{ ...RULES, powerByCost: [0, 1, 2] }, TABLE), RangeError);
});
-95
View File
@@ -1,95 +0,0 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
DEFAULT_RULESET, IllegalActionError, Rng, applyAction, createMatch, deserialize, isOver, legalActions,
parseRuleset, replay, result, serialize, starterDeck, viewFor, type Action, type GameCard, type MatchState, type PlayerId,
} from '../shared/game/index.ts';
const decks = (seed = 'd'): [GameCard[], GameCard[]] => [starterDeck(`${seed}-a`), starterDeck(`${seed}-b`)];
function randomPlay(seed: string, ruleset = DEFAULT_RULESET): MatchState {
let state = createMatch(ruleset, decks(seed), seed);
const chooser = Rng.fromSeed(`bot:${seed}`);
for (let steps = 0; !isOver(state); steps++) {
assert.ok(steps < 1000, 'match must terminate');
const player = chooser.int(2) as PlayerId;
const actions = legalActions(state, player);
if (!actions.length) continue;
state = applyAction(state, chooser.pick(actions));
}
return state;
}
test('rng is deterministic and seed-sensitive', () => {
const a = Rng.fromSeed('x'), b = Rng.fromSeed('x'), c = Rng.fromSeed('y');
const seq = (r: Rng) => Array.from({ length: 8 }, () => r.nextUint32());
assert.deepEqual(seq(a), seq(b));
assert.notDeepEqual(seq(Rng.fromSeed('x')), seq(c));
const r = Rng.fromSeed('bounds');
for (let i = 0; i < 1000; i++) { const n = r.int(7); assert.ok(n >= 0 && n < 7); }
});
test('default ruleset validates; bad rulesets are rejected', () => {
assert.deepEqual(parseRuleset(DEFAULT_RULESET), DEFAULT_RULESET);
assert.throws(() => parseRuleset({ ...DEFAULT_RULESET, maxTurns: 99 }));
assert.throws(() => parseRuleset({ ...DEFAULT_RULESET, keywords: { nope: {} } }));
assert.throws(() => parseRuleset({ ...DEFAULT_RULESET, extra: 1 }));
});
test('starter decks are legal, deterministic and non-NFT', () => {
const deck = starterDeck('s');
assert.equal(deck.length, 12);
assert.deepEqual(deck, starterDeck('s'));
assert.ok(deck.every(card => card.source === 'starter'));
assert.deepEqual(deck.map(c => c.cost).sort().join(''), '112233445566');
});
test('match setup: hands, energy, turn 1', () => {
const state = createMatch(DEFAULT_RULESET, decks(), 'setup');
assert.equal(state.turn, 1);
for (const p of state.players) { assert.equal(p.hand.length, 4); assert.equal(p.deck.length, 8); assert.equal(p.energy, 1); }
assert.throws(() => createMatch(DEFAULT_RULESET, [decks()[0].slice(0, 5), decks()[1]], 's'), IllegalActionError);
});
test('staging is hidden from the opponent until reveal', () => {
let state = createMatch(DEFAULT_RULESET, decks(), 'hidden');
const play = legalActions(state, 0).find(a => a.type === 'play') as Extract<Action, { type: 'play' }>;
assert.ok(play, 'turn 1 should have a 1-cost play');
state = applyAction(state, play);
assert.equal(viewFor(state, 1).opponent.stagedCount, 1);
assert.equal(viewFor(state, 1).lanes[play.lane].cards[1].length, 0);
assert.equal(JSON.stringify(viewFor(state, 1)).includes(`"${play.cardId}"`), false);
state = applyAction(state, { type: 'endTurn', player: 0 });
state = applyAction(state, { type: 'endTurn', player: 1 });
assert.equal(state.turn, 2);
assert.equal(viewFor(state, 1).lanes[play.lane].cards[1][0].card.id, play.cardId);
assert.throws(() => applyAction(state, { type: 'play', player: 0, cardId: play.cardId, lane: 0 }), IllegalActionError);
});
test('unstage refunds energy', () => {
let state = createMatch(DEFAULT_RULESET, decks(), 'unstage');
const play = legalActions(state, 0).find(a => a.type === 'play') as Extract<Action, { type: 'play' }>;
state = applyAction(state, play);
state = applyAction(state, { type: 'unstage', player: 0, cardId: play.cardId });
assert.equal(state.players[0].energy, 1);
assert.equal(state.players[0].staged.length, 0);
});
test('concede ends the match for the other player', () => {
const state = applyAction(createMatch(DEFAULT_RULESET, decks(), 'c'), { type: 'concede', player: 1 });
assert.equal(isOver(state), true);
assert.equal(result(state)?.winner, 0);
assert.deepEqual(legalActions(state, 0), []);
});
test('random legal play terminates within maxTurns, and replays and serialises exactly', () => {
for (let i = 0; i < 40; i++) {
const seed = `prop-${i}`;
const end = randomPlay(seed);
const r = result(end)!;
assert.ok(r.turns <= DEFAULT_RULESET.maxTurns);
assert.deepEqual(randomPlay(seed), end);
assert.deepEqual(replay(DEFAULT_RULESET, decks(seed), seed, end.actions), end);
assert.deepEqual(deserialize(serialize(end)), end);
}
});
-147
View File
@@ -1,147 +0,0 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { KEYWORDS, Rng, hiddenFrom, laneFaction, parseRuleset } from '../shared/game/index.ts';
import { card, cardPower, emptyBoard, endOfTurn, lanePower, place, reveal, testRules } from './game/build.ts';
test('every keyword has an id matching its key, a name and rules text', () => {
for (const [id, def] of Object.entries(KEYWORDS)) {
assert.equal(def.id, id);
assert.ok(def.name && def.text, `${id} needs name and text`);
}
});
test('the all-keywords test ruleset validates', () => {
assert.doesNotThrow(() => parseRuleset(testRules()));
});
test('Edition: +2 for each other copy of the same article on your side, any lane', () => {
const s = emptyBoard();
const a = place(s, 0, 0, card({ pageId: 42, power: 5, keyword: 'edition' }));
assert.equal(cardPower(s, a), 5);
const b = place(s, 0, 2, card({ pageId: 42, power: 5, keyword: 'edition' }));
assert.equal(cardPower(s, a), 7);
assert.equal(cardPower(s, b), 7);
place(s, 1, 0, card({ pageId: 42, power: 5 })); // the opponent's copy doesn't count
assert.equal(cardPower(s, a), 7);
});
test('Translated: +1 to your first card in each other lane that has one', () => {
const s = emptyBoard();
const left = place(s, 0, 0, card({ power: 2 }));
const leftSecond = place(s, 0, 0, card({ power: 2 }));
const enemy = place(s, 1, 2, card({ power: 2 }));
const t = reveal(s, 0, 1, card({ power: 4, keyword: 'translated' }));
assert.equal(left.bonus, 1);
assert.equal(leftSecond.bonus, 0);
assert.equal(enemy.bonus, 0);
assert.equal(t.bonus, 0);
});
test('Viral: adds a 1-power Mention token to a random other lane with space', () => {
const s = emptyBoard();
reveal(s, 0, 1, card({ keyword: 'viral' }), new Rng([9, 9, 9, 9]));
const tokens = s.lanes.flatMap((lane, index) => lane.cards[0].filter(c => c.card.meta?.token).map(c => ({ c, index })));
assert.equal(tokens.length, 1);
assert.notEqual(tokens[0].index, 1);
assert.equal(tokens[0].c.lane, tokens[0].index);
assert.equal(cardPower(s, tokens[0].c), 1);
});
test('Viral: deterministic for the same rng, and a no-op when no other lane has space', () => {
const run = () => { const s = emptyBoard(); reveal(s, 0, 1, card({ id: 'v', name: 'V', pageId: 1, keyword: 'viral' }), new Rng([5, 6, 7, 8])); return s.lanes; };
assert.deepEqual(run(), run());
const s = emptyBoard();
for (const lane of [0, 2]) for (let i = 0; i < s.ruleset.laneCapacity; i++) place(s, 0, lane, card());
const before = JSON.stringify(s.lanes);
reveal(s, 0, 1, card({ id: 'viral-full', keyword: 'viral' }));
s.lanes[1].cards[0].pop();
assert.equal(JSON.stringify(s.lanes), before);
});
test('Rising: +1 at each end of turn, capped at +3', () => {
const s = emptyBoard();
const r = place(s, 0, 1, card({ power: 3, keyword: 'rising' }));
const seen = [];
for (let i = 0; i < 5; i++) { endOfTurn(s, r); seen.push(cardPower(s, r)); }
assert.deepEqual(seen, [4, 5, 6, 6, 6]);
});
test('Rising: the cap counts only Rising gains, not other bonuses', () => {
const s = emptyBoard();
const r = place(s, 0, 1, card({ power: 3, keyword: 'rising' }));
r.bonus += 5; // e.g. Translated/Rally
for (let i = 0; i < 4; i++) endOfTurn(s, r);
assert.equal(cardPower(s, r), 11);
});
test('Nostalgic: +3 only when losing the lane, judged without itself (DESIGN example: 2 vs 8)', () => {
const s = emptyBoard();
place(s, 0, 1, card({ power: 2 }));
place(s, 1, 1, card({ power: 8 }));
const n = reveal(s, 0, 1, card({ power: 3, keyword: 'nostalgic' }));
assert.equal(cardPower(s, n), 6);
assert.deepEqual(lanePower(s, 1), [8, 8]);
});
test('Nostalgic: no bonus when tied or winning', () => {
const s = emptyBoard();
place(s, 0, 1, card({ power: 4 }));
place(s, 1, 1, card({ power: 4 }));
assert.equal(reveal(s, 0, 1, card({ power: 3, keyword: 'nostalgic' })).bonus, 0);
const t = emptyBoard();
assert.equal(reveal(t, 0, 1, card({ power: 3, keyword: 'nostalgic' })).bonus, 0); // 0 vs 0 is not losing
});
test('Encyclopedic: +2 when alone here; floors its own negative bonus', () => {
const s = emptyBoard();
const e = reveal(s, 0, 1, card({ power: 7, keyword: 'encyclopedic' }));
assert.equal(cardPower(s, e), 9);
place(s, 0, 2, card());
const f = (() => { place(s, 0, 2, card()); return reveal(s, 0, 2, card({ power: 7, keyword: 'encyclopedic' })); })();
assert.equal(cardPower(s, f), 7);
f.bonus = -4;
assert.equal(cardPower(s, f), 7);
});
test('Local: +2 only in a lane whose faction matches', () => {
const s = emptyBoard();
assert.equal(laneFaction(s, 0), 'Science');
assert.equal(laneFaction(s, 1), null);
const home = place(s, 0, 0, card({ power: 2, category: 'Science', keyword: 'local' }));
const away = place(s, 0, 1, card({ power: 2, category: 'Science', keyword: 'local' }));
const wrong = place(s, 0, 0, card({ power: 2, category: 'History', keyword: 'local' }));
assert.deepEqual([cardPower(s, home), cardPower(s, away), cardPower(s, wrong)], [4, 2, 2]);
});
test('laneFaction is null until the portal lane is revealed', () => {
const s = emptyBoard(testRules({ laneModifiers: { pool: [], revealTurns: [3, 1, 1], params: { portal: { categoryIndex: 3, amount: 0 } } } }));
assert.equal(laneFaction(s, 0), null);
s.turn = 3;
assert.equal(laneFaction(s, 0), 'Science');
});
test('Wildcard: takes the lane faction on reveal, and then counts for Local', () => {
const s = emptyBoard();
const w = reveal(s, 0, 0, card({ category: 'Culture', keyword: 'wildcard' }));
assert.equal(w.card.category, 'Science');
const plain = reveal(s, 0, 1, card({ category: 'Culture', keyword: 'wildcard' }));
assert.equal(plain.card.category, 'Culture');
});
test('Obscure: hidden from the opponent only, and only while the match runs', () => {
const s = emptyBoard();
const o = place(s, 0, 1, card({ keyword: 'obscure' }));
assert.equal(hiddenFrom(s, o, 1), true);
assert.equal(hiddenFrom(s, o, 0), false);
s.phase = 'over';
assert.equal(hiddenFrom(s, o, 1), false);
});
test('a keyword the ruleset does not enable has no effect', () => {
const s = emptyBoard(testRules({ keywords: {} }));
place(s, 0, 0, card({ pageId: 7, power: 5, keyword: 'edition' }));
const b = place(s, 0, 1, card({ pageId: 7, power: 5, keyword: 'edition' }));
assert.equal(cardPower(s, b), 5);
const o = place(s, 0, 2, card({ keyword: 'obscure' }));
assert.equal(hiddenFrom(s, o, 1), false);
});
-100
View File
@@ -1,100 +0,0 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import {
createMatch, legalActions, applyAction, isOver, result, serialize, deserialize, starterDeck, PLAYERS,
type Action, type GameCard, type MatchState,
} from '../shared/game/index.ts';
import { forAll, type Gen } from './game/property.ts';
import { testRules } from './game/build.ts';
type State = MatchState;
/** Every keyword enabled, so property runs exercise all effects. */
const RULES = testRules({ laneModifiers: { pool: ['plain', 'portal', 'narrow'], revealTurns: [1, 2, 3],
params: { portal: { categoryIndex: 3, amount: 1 }, narrow: { maxCost: 3 } } } });
const KEYWORD_IDS = Object.keys(RULES.keywords);
/** Generous bound: a match must finish well within this many actions. */
const MAX_ACTIONS = 2000;
/** Starter deck with random keywords sprinkled in (shared pageIds so Edition can fire). */
function randomDeck(g: Gen, tag: string): GameCard[] {
return starterDeck(tag, RULES).map(c => ({ ...c, keyword: g.bool(0.6) ? g.pick(KEYWORD_IDS) : null,
category: g.pick(['Space', 'Nature', 'People', 'Science', 'History', 'Culture'] as const) }));
}
function randomMatch(g: Gen, seed: number) {
return createMatch(RULES, [randomDeck(g, `a-${seed}`), randomDeck(g, `b-${seed}`)], `match-${seed}`);
}
/** Plays random legal actions until the match ends; returns the final state and the action log. */
function playOut(g: Gen, state: State, check?: (s: State) => void) {
const log: unknown[] = [];
let steps = 0;
while (!isOver(state)) {
const options = PLAYERS.flatMap(player => legalActions(state, player));
assert.ok(options.length > 0, `no legal actions in a live match at step ${steps}`);
const action = g.pick(options);
log.push(action);
state = applyAction(state, action);
check?.(state);
assert.ok(++steps <= MAX_ACTIONS, `match did not terminate within ${MAX_ACTIONS} actions`);
}
return { state, log };
}
test('random legal play never crashes and always terminates with a result', () => {
forAll(200, (g, seed) => {
const { state } = playOut(g, randomMatch(g, seed));
const outcome = result(state);
assert.ok(outcome, 'finished match has a result');
});
});
test('same seed and same actions give the same result', () => {
forAll(50, (g, seed) => {
const decks: [GameCard[], GameCard[]] = [randomDeck(g, `a-${seed}`), randomDeck(g, `b-${seed}`)];
const first = playOut(g, createMatch(RULES, decks, `m-${seed}`));
// Replay the exact action log on a fresh match from the same seed.
let replay = createMatch(RULES, decks, `m-${seed}`);
for (const action of first.log) replay = applyAction(replay, action as Action);
assert.deepEqual(replay, first.state);
assert.deepEqual(result(replay), result(first.state));
});
});
test('createMatch is deterministic for a seed and varies across seeds', () => {
const a = createMatch(RULES, [starterDeck('x'), starterDeck('y')], 'same');
const b = createMatch(RULES, [starterDeck('x'), starterDeck('y')], 'same');
assert.deepEqual(a, b);
const distinct = new Set(Array.from({ length: 20 }, (_, i) =>
JSON.stringify(createMatch(RULES, [starterDeck('x'), starterDeck('y')], `seed-${i}`))));
assert.ok(distinct.size > 1, 'different seeds should shuffle differently');
});
test('serialize/deserialize round-trips after every action', () => {
forAll(30, (g, seed) => {
playOut(g, randomMatch(g, seed), s => {
assert.deepEqual(deserialize(serialize(s)), s);
});
});
});
test('applyAction never mutates its input state', () => {
forAll(30, (g, seed) => {
let state = randomMatch(g, seed);
let steps = 0;
while (!isOver(state) && steps++ < MAX_ACTIONS) {
const before = JSON.stringify(state);
const action = g.pick(PLAYERS.flatMap(player => legalActions(state, player)));
const next = applyAction(state, action);
assert.equal(JSON.stringify(state), before);
state = next;
}
});
});
test('a finished match offers no legal actions', () => {
forAll(30, (g, seed) => {
const { state } = playOut(g, randomMatch(g, seed));
for (const player of PLAYERS) assert.deepEqual(legalActions(state, player), []);
});
});
-61
View File
@@ -1,61 +0,0 @@
/** Hand-built match states for keyword unit tests. */
import {
DEFAULT_RULESET, Rng, createMatch, starterDeck, KEYWORDS, cardPower, lanePower,
type CardInPlay, type Category, type EffectContext, type GameCard, type MatchState, type PlayerId, type Ruleset,
} from '../../shared/game/index.ts';
export const ALL_KEYWORDS: Ruleset['keywords'] = {
rally: { amount: 1 }, anchor: { amount: 2 }, edition: { amount: 2 }, translated: { amount: 1 },
viral: { amount: 1 }, rising: { amount: 1, max: 3 }, nostalgic: { amount: 3 }, encyclopedic: { amount: 2 },
obscure: {}, local: { amount: 2 }, wildcard: {},
};
/** A ruleset with every keyword on and lane 0 a revealed Science portal (lanes 1–2 plain). */
export function testRules(overrides: Partial<Ruleset> = {}): Ruleset {
return {
...DEFAULT_RULESET, keywords: ALL_KEYWORDS,
laneModifiers: { pool: [], revealTurns: [1, 1, 1], params: { portal: { categoryIndex: 3, amount: 0 } } },
...overrides,
};
}
/** An empty board on turn 1 with lane 0 set to the Science portal. */
export function emptyBoard(rules = testRules()): MatchState {
const state = createMatch(rules, [starterDeck('a', rules), starterDeck('b', rules)], 'keyword-test');
for (const lane of state.lanes) lane.cards = [[], []];
state.lanes[0].modifier = 'portal';
state.lanes[1].modifier = 'plain';
state.lanes[2].modifier = 'plain';
return state;
}
let serial = 0;
export function card(overrides: Partial<GameCard> = {}): GameCard {
serial++;
return { id: `t${serial}`, name: `Card ${serial}`, pageId: 1000 + serial, category: 'Culture' as Category,
cost: 1, power: 2, keyword: null, source: 'loaner', ...overrides };
}
export function place(state: MatchState, owner: PlayerId, lane: number, c: GameCard): CardInPlay {
const inPlay: CardInPlay = { card: c, owner, lane, turn: state.turn, bonus: 0 };
state.lanes[lane].cards[owner].push(inPlay);
return inPlay;
}
export function ctxFor(state: MatchState, keyword: string, lane: number, rng = new Rng([1, 2, 3, 4])): EffectContext {
return { state, rng, params: state.ruleset.keywords[keyword] ?? {}, lane, log: () => {}, power: c => cardPower(state, c) };
}
/** Place a card and fire its onReveal, as the engine does at reveal. */
export function reveal(state: MatchState, owner: PlayerId, lane: number, c: GameCard, rng?: Rng): CardInPlay {
const inPlay = place(state, owner, lane, c);
if (c.keyword) KEYWORDS[c.keyword]?.onReveal?.(ctxFor(state, c.keyword, lane, rng), inPlay);
return inPlay;
}
export function endOfTurn(state: MatchState, self: CardInPlay): void {
const keyword = self.card.keyword;
if (keyword) KEYWORDS[keyword]?.endOfTurn?.(ctxFor(state, keyword, self.lane), self);
}
export { cardPower, lanePower };
-47
View File
@@ -1,47 +0,0 @@
/**
* Tiny dependency-free property-testing helper. Each case gets its own seed
* so a failure reports a reproducible seed: rerun with PROP_SEED=<seed>.
*/
export function mulberry32(seed: number): () => number {
let a = seed >>> 0;
return () => {
a = (a + 0x6d2b79f5) >>> 0;
let t = a;
t = Math.imul(t ^ (t >>> 15), t | 1);
t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
};
}
export interface Gen {
rand: () => number;
int(min: number, max: number): number;
pick<T>(items: readonly T[]): T;
bool(p?: number): boolean;
}
export function gen(seed: number): Gen {
const rand = mulberry32(seed);
return {
rand,
int: (min, max) => min + Math.floor(rand() * (max - min + 1)),
pick: items => {
if (!items.length) throw new Error('pick from empty list');
return items[Math.floor(rand() * items.length)];
},
bool: (p = 0.5) => rand() < p,
};
}
export function forAll(runs: number, property: (g: Gen, seed: number) => void, baseSeed = 0x5eed): void {
const fixed = process.env.PROP_SEED;
const seeds = fixed ? [Number(fixed)] : Array.from({ length: runs }, (_, i) => (baseSeed + i * 2654435761) >>> 0);
for (const seed of seeds) {
try {
property(gen(seed), seed);
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
throw new Error(`Property failed for seed ${seed} (rerun with PROP_SEED=${seed}): ${message}`, { cause: error });
}
}
}