Compare commits

..
17 changed files with 1259 additions and 1130 deletions
-223
View File
@@ -1,223 +0,0 @@
# WikiDeck game engine API (v1)
**Owner:** engine-a (core and API) and engine-b (keywords, card derivation, tests). Issue: claude/wikideck#3.
**Rules:** `docs/game/DESIGN.md` v1 ("Edit War", as frozen in PR #17 @ cf2fceb). Where this file and DESIGN.md disagree, raise it on #3.
**Stability:** UI, simulation and modes build against this file. Any change to a name or shape below is
announced on #3 before it merges.
The engine is a pure TypeScript library in `shared/game/`:
- It does no I/O and has no clocks: no `Date.now()`, no `Math.random()`.
- It imports nothing from `server/` or `src/`.
- It runs entirely **off-chain**. A match never reads, moves, locks or burns an NFT.
- It is deterministic: the same `(ruleset, decks, seed, actions)` always gives the same state, byte for byte.
**Import only from `shared/game/index.ts`.**
```ts
import { createMatch, legalActions, applyAction, isOver, result, viewFor,
serialize, deserialize, replay, DEFAULT_RULESET, parseRuleset, validateDeck,
starterDeck, previewPool, type MatchState, type Action, type GameCard } from '../shared/game/index.ts';
```
## 1. Lifecycle
```ts
let state = createMatch(DEFAULT_RULESET, [deck0, deck1], seed); // turn 1, planning
while (!isOver(state)) {
// Each seat (in any order, any interleaving) queues plays, then commits.
const actions = legalActions(state, seat); // play / undo / commit
state = applyAction(state, chosen); // returns a NEW state
// When both seats have committed, the turn resolves inside applyAction.
}
const r = result(state); // { winner: 0 | 1 | null, reason, topicsLed, lanePower, totalPower, turns }
```
| Function | Description |
|---|---|
| `createMatch(ruleset, [deck0, deck1], seed: number \| string): MatchState` | Validates the ruleset (`parseRuleset`) and both decks (`validateDeck`), then performs DESIGN §4 setup and turn-1 start. A `seed` is a uint32. A string is hashed with FNV-1a (`seedFromString`). Throws `ZodError` for a bad ruleset and `IllegalActionError` for a bad deck. |
| `legalActions(state, seat): Action[]` | Lists every `play` (each card × each lane it can legally go into), every `undo`, and `commit`. Returns `[]` once the seat has committed or the match is over. It never lists `concede` (always legal while the match is running) or `timeout` (host only). |
| `applyAction(state, action): MatchState` | Pure: the input is never mutated. Throws `IllegalActionError` if the action is illegal. |
| `actionProblem(state, action): string \| null` | Explains why an action is illegal, without throwing. Use it for UI hints and for validating client input on a host. |
| `isOver(state)` / `result(state)` | `result` is `null` while the match is running. |
| `viewFor(state, seat): PlayerView` | The **hidden-information view**. Send only this to clients and AIs, never `MatchState`, because a `MatchState` contains both deck orders and the RNG state. |
| `serialize(state): string` / `deserialize(json): MatchState` | Lossless JSON. `MatchState` is plain data. |
| `replay(ruleset, decks, seed, actions): MatchState` | Rebuilds a match from its inputs. `state.actions` records every action applied, so a host can store `(ruleset, decks, seed, actions)` and verify a result later. |
| `validateDeck(ruleset, cards): string[]` | Returns the list of problems; empty means the deck is legal. |
| `cardPower(state, cardInPlay)`, `lanePower(state, lane)`, `laneLeader(state, lane)`, `topicsLed(state)` | Power queries (DESIGN §6). `laneLeader` and `topicsLed` apply the consensus tie-break. |
| `scoringPower(state, lane)` | Lane power plus revealed "at scoring" Portals (§7). `result().lanePower` uses this. |
| `laneCapacity(state, lane)` | Per-seat capacity of a lane. A Portal such as Stub may override it. |
| `isOnTopic(state, cardInPlay)` | §1.4/§6 on-topic test, including Disambiguation. |
| `starterDeck(seed): GameCard[]` | A 12-card loaner deck (DESIGN §2). **Placeholder** cards until starter-cards.json lands. |
| `previewPool(): GameCard[]` | Every loaner card once. For draft modes. |
| `placeCard(state, seat, lane, card)`, `revealPortal(state, lane)` | Test helpers for building boards by hand. |
## 2. Actions
```ts
type Action =
| { type: 'play'; player: 0 | 1; cardId: string; lane: number } // queue a card from hand (hidden)
| { type: 'undo'; player: 0 | 1; cardId: string } // un-queue it (refunds energy)
| { type: 'commit'; player: 0 | 1 } // lock in this turn (empty = pass)
| { type: 'timeout'; player: 0 | 1 } // HOST ONLY: turn timer expired
| { type: 'concede'; player: 0 | 1 };
```
**Queuing a play**
- `play` reserves the card's cost from this turn's energy. It checks the energy, the lane's room (cards already in the lane plus queued plays must stay under `laneCapacity(state, lane)`), and, once the Portal is revealed, whether it accepts the card (`canPlay`).
- Your plays reveal in **your queue order**, interleaved with the opponent's (see below).
- `undo` and new plays are allowed until the seat sends `commit`.
**Resolving a turn**
- When both seats have committed, `applyAction` resolves the turn (DESIGN §5.4–5.5):
1. Carry is set: min(`energyCarryMax`, energy not reserved by queued plays). Energy spent on a play that later fizzles is still spent.
2. **Interleaved reveal:** the initiative seat's 1st play, then the other seat's 1st, then the initiative seat's 2nd, and so on. When one seat runs out, the other's remaining plays reveal in order. Each card gets the next global `seq` number, and its on-reveal effects (keyword, then Portal) run at once.
3. End-of-turn effects run: the initiative seat's cards first, then lanes left→right, then `seq` order.
4. On the last turn, scoring follows (§7). Otherwise the next turn starts:
- initiative **alternates**
- any Portal scheduled by `portalReveal` is revealed
- energy = `energyByTurn[t-1]` + carry + `bonusEnergy`
- each seat draws
- the underdog bonus applies (only if `underdog` is on)
- **A play that is illegal at reveal** (the lane filled up, or a Portal rejects the card) fizzles. The card stays in hand and its energy is lost. A `fizzle` log event records it.
**Timeouts.** `timeout` is how a host enforces `turnSeconds`. It commits whatever is queued. A timeout with an empty queue counts toward `afkTurns`. When that count is reached, the seat concedes and the result has `reason: 'afk'`. An ordinary `commit` resets the count.
**Seat ownership.** The engine does not authenticate anyone. The host must check that the seat in `action.player` is the caller's.
## 3. Cards
```ts
interface GameCard {
cardId: string; // unique within a deck: the NFT card hash, or `loaner:<pageId>:<n>`
pageId: number | null; // at most maxCopiesPerPage cards share a pageId; null (unpinned loaners) → counted per cardId
title: string;
faction: 'Space' | 'Nature' | 'People' | 'Science' | 'History' | 'Culture';
rarity: 'Common' | 'Rare' | 'Epic' | 'Legendary'; // cosmetic in v1
cost: number; // 0–6 (uncheckedCostCap already applied by derivation)
power: number; // 0–30, base power
home: 'attention' | 'depth' | 'reach';
trend: -1 | 0 | 1; // frozen at match start
keyword: string | null; // an id in KEYWORDS
source: 'owned' | 'loaner';
check?: 'verified' | 'unverified' | 'unchecked' | 'loaner'; // host plausibility result (§1.10), for logs
}
```
- **The engine takes already-derived cards and never reads raw stats.** The council asked for this, because snapshot stats are self-reported (#1, critic brief A.1).
- Derivation (DESIGN §1 and §10.1: percentile → fame → cost → power, home, trend, keyword and vanillaBonus) lives in `shared/game/derive.ts`, which engine-b owns. Hosts run it on host-frozen, plausibility-checked inputs before calling `createMatch`.
- Modes may adjust `GameCard` fields such as `power` before `createMatch`. The engine does not re-derive them.
- A keyword that isn't in `ruleset.keywordsEnabled` never runs. Derivation is responsible for not giving that card `vanillaBonus`.
- Lane power = `power` + `bonus` + `trend` + `onTopicBonus[cost]` if on-topic + ongoing keyword and Portal effects, floored at 0.
## 4. Ruleset
`Ruleset` holds the DESIGN §9 keys, **flat** (nothing deeper than one level, apart from `topicPool` entries and the param tables).
- `parseRuleset(unknown)` is a **strict** zod parse: unknown keys are rejected and every number is bounded, so any ruleset that passes terminates within `turns` turns.
- Modes merge overrides onto `DEFAULT_RULESET` and then call `parseRuleset`.
Notes on the §9 keys:
- `topicPool` is inline `TopicDef[] = { id, name, stat, portal: PortalId | null }[]`. `DEFAULT_TOPIC_POOL` is the 9 Topics of §10.3. A Portal id is one of `PORTAL_IDS` (`main-page, trending, featured-article, stub, interwiki, disambiguation`).
- `keywordParams[keywordId]` holds keyword numbers; keys must be in `KEYWORD_IDS`. `portalParams[topicId]` holds Portal numbers, and falls back to `portalParams[portalId]`, so a mode can add a Topic that reuses a Portal kind with new numbers.
- `keywordsEnabled` ⊆ `KEYWORD_IDS` (the 6 v1 ids plus `edition`, `obscure` and `wildcard`).
- `mulligan` must be `false`. Mulligans are not implemented in v1.
- `percentiles`, `starterDecks`, `trendUp/Down`, `trendMinDaily`, `uncheckedCostCap`, `vanillaBonus`, `costThresholds`, `powerByCost`, `verifyStats` and `factionSynergyCap` are for derivation and the host. The core loop doesn't read them.
Validation also enforces:
- `turns × turnSeconds ≤ 240`
- `energyByTurn.length ≥ turns`
- `portalReveal.length = topicCount`
- `openingHand ≤ handLimit`
- `costThresholds` in ascending order
- with `distinctStats`, `topicCount == 3` and the pool has all 3 stats
- the ranges in DESIGN §11 are **stricter** and are enforced by modes (`shared/game/modes.ts`). The engine's bounds only guarantee safety and termination.
## 5. Determinism and the RNG
- The RNG is **mulberry32(seed: uint32)**, as in DESIGN §4. Its state is a single uint32 in `state.rng`.
- Draw order:
1. p0's deck is shuffled.
2. p1's deck is shuffled.
3. **The Topics are drawn.** With `distinctStats`: for each stat in the order `attention, depth, reach`, take `group[floor(next() × group.length)]`, where `group` is that stat's Topics in `topicPool` order. Then the picks are shuffled, and that is the lane order. Without `distinctStats`: the whole pool is shuffled and the first `topicCount` are taken.
4. The initiative coin is flipped: p0 has initiative on turn 1 (and every odd turn) if `next() < 0.5`; otherwise p1 does. After that, initiative strictly alternates.
5. Keyword and Portal hooks draw in resolution order.
- Shuffles are Fisher–Yates with `i` from n−1 down to 1 and `j = floor(next() × (i+1))`.
- `ongoing` power hooks get a throwaway RNG copy, so computing power never changes the match RNG.
## 6. State and views
The full `MatchState` (plain JSON) is for the **host only**:
```ts
interface MatchState {
schema: 'wikideck-match/1'; engineVersion: number; ruleset: Ruleset; seed: number; rng: number;
turn: number /* 1-based */; phase: 'planning' | 'over'; initiative: 0 | 1;
players: [PlayerState, PlayerState]; // deck, hand, energy, queue, committed, afk
lanes: { topic: TopicDef; portalRevealed: boolean; cards: [CardInPlay[], CardInPlay[]] }[];
revealSeq: number; log: LogEvent[]; actions: Action[]; result: MatchResult | null;
}
interface PlayerState { deck; hand; energy; queue: { cardId; lane }[]; committed; afk; carry }
interface CardInPlay { card: GameCard; owner: 0 | 1; lane: number; turn: number; seq: number; bonus: number }
```
`PlayerView`, returned by `viewFor(state, seat)`, is what a seat may see. In it, "you" is always index 0 and the opponent is index 1:
```ts
interface PlayerView {
you: 0 | 1; ruleset; turn; phase; initiative;
energy: number; energyLeft: number; hand: GameCard[]; queue: { cardId; lane }[]; committed; deckCount;
opponent: { handCount; deckCount; queuedCount; committed }; // never their cards or queue
lanes: { topic: TopicDef /* stat always; id/name/portal masked until portalRevealed */, portalRevealed, cards: [mine, theirs],
cardPower: [number[], number[]], power: [mine, theirs], leader: 'you' | 'opponent' | null }[];
result: MatchResult | null;
}
```
`state.log` is an append-only event list for animation and replays. Event types: `turnStart`, `portalRevealed`, `underdog`, `draw`, `reveal`, `fizzle`, `effect`, `concede` and `matchOver`. It contains both seats' draws, so a host must filter it per seat before sending it.
## 7. Results
```ts
interface MatchResult {
winner: 0 | 1 | null; // null = draw
reason: 'topics' | 'totalPower' | 'draw' | 'concede' | 'afk';
topicsLed: [number, number]; lanePower: [number, number][]; totalPower: [number, number]; turns: number;
}
```
Scoring runs after the last turn's End phase. Lane powers include revealed "at scoring" Portals, and each lane's leader uses the consensus tie-break (§6). Winner, per DESIGN §7:
1. The seat that leads more Topics.
2. If tied on Topics, the seat with more total power.
3. If that is also tied, a draw.
## 8. Keywords and Portals (extension contract)
`KEYWORDS` and `PORTALS` in `shared/game/keywords.ts` (engine-b) are registries of hook objects. The header of that file is normative. Every hook gets `ctx = { state, rng, params, lane, log, power(card) }`.
**Keywords**
- `onReveal(ctx, self)` and `endOfTurn(ctx, self)` may change `bonus` on cards in `ctx.state`.
- `ongoing(ctx, self, target) → number` must be **pure**, and must not call `ctx.power`.
- Keyword hooks run only if the keyword is in `keywordsEnabled`.
**Portals** have the same hooks, plus:
- `onPortalReveal(ctx)`
- `canPlay(ctx, card, seat) → boolean`, checked when a play is queued and again at reveal
- `capacity(ctx) → number`
- `allOnTopic: true`
- `atScoring(ctx) → [delta0, delta1]`
Portal hooks act only once the Portal is revealed.
**Rules for all hooks**
- Hooks must not move or remove cards (DESIGN §10).
- Any randomness must come from `ctx.rng`. No v1 keyword uses it.
## 9. Testing
- `tests/game-core.test.ts` (engine-a) covers the core loop:
- the RNG reference value, ruleset bounds and setup
- hidden information and hidden Portals
- energy carry, interleaved reveal and alternating initiative
- on-topic power, the consensus tie-break, and Portal capacity, fizzle and at-scoring hooks
- disabled keywords, AFK and concede, and draws
- the random-play property: matches terminate, replay exactly, and serialise after every action
- `tests/game-*.test.ts` (engine-b): keywords, card derivation, property tests and the DESIGN §12 golden match.
+92
View File
@@ -0,0 +1,92 @@
/**
* 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
@@ -0,0 +1,112 @@
/**
* 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) };
}
+168 -298
View File
@@ -1,109 +1,72 @@
/**
* WikiDeck game engine core ("Edit War", docs/game/DESIGN.md): pure,
* deterministic, off-chain. Exported functions never mutate their inputs.
* All randomness comes from the match seed via state.rng (mulberry32, §4).
* 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, KEYWORD_IDS, activePortal, isOnTopic, type EffectContext, type KeywordDef, type PortalDef } from './keywords.ts';
import { Rng, normalizeSeed } from './rng.ts';
import { parseRuleset } from './ruleset.ts';
import { KEYWORDS, LANE_MODIFIERS, type EffectContext } from './keywords.ts';
import { Rng, seedRng } from './rng.ts';
import { energyForTurn, parseRuleset } from './ruleset.ts';
import {
IllegalActionError, PLAYERS, STATS,
IllegalActionError, PLAYERS,
type Action, type CardInPlay, type GameCard, type MatchResult, type MatchState,
type PlayerId, type PlayerState, type PlayerView, type Ruleset, type TopicDef,
type PlayerId, type PlayerState, type PlayerView, type Ruleset,
} from './types.ts';
export const ENGINE_VERSION = 1;
export const other = (player: PlayerId): PlayerId => (player === 0 ? 1 : 0);
const other = (player: PlayerId): PlayerId => (player === 0 ? 1 : 0);
const clone = <T>(value: T): T => structuredClone(value);
const RARITIES = new Set(['Common', 'Rare', 'Epic', 'Legendary']);
const FACTION_SET = new Set(['Space', 'Nature', 'People', 'Science', 'History', 'Culture']);
const CHECKS = new Set(['verified', 'unverified', 'unchecked', 'loaner']);
// ---------- validation ----------
/** Problems with a deck under `rules` (empty = legal). DESIGN §2. */
export function validateDeck(rules: Ruleset, deck: readonly GameCard[]): string[] {
const problems: string[] = [];
if (!Array.isArray(deck)) return ['Deck must be an array'];
if (deck.length !== rules.deckSize) problems.push(`Deck must have exactly ${rules.deckSize} cards (has ${deck.length})`);
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<string, number>();
let loaners = 0;
const copies = new Map<number, number>();
for (const card of deck) {
if (typeof card?.cardId !== 'string' || !card.cardId || card.cardId.length > 128) { problems.push('cardId must be a non-empty string'); continue; }
const label = card.cardId;
if (ids.has(card.cardId)) problems.push(`Duplicate cardId ${label}`);
ids.add(card.cardId);
if (card.pageId !== null && !Number.isInteger(card.pageId)) problems.push(`${label}: bad pageId`);
if (card.pageId === null && card.source !== 'loaner') problems.push(`${label}: owned cards need a pageId`);
if (typeof card.title !== 'string' || card.title.length > 256) problems.push(`${label}: bad title`);
if (!FACTION_SET.has(card.faction)) problems.push(`${label}: bad faction`);
if (!RARITIES.has(card.rarity)) problems.push(`${label}: bad rarity`);
if (!Number.isInteger(card.cost) || card.cost < 0 || card.cost > 6) problems.push(`${label}: cost must be 0–6`);
if (!Number.isInteger(card.power) || card.power < 0 || card.power > 30) problems.push(`${label}: power must be 0–30`);
if (!STATS.includes(card.home)) problems.push(`${label}: bad home stat`);
if (card.trend !== -1 && card.trend !== 0 && card.trend !== 1) problems.push(`${label}: trend must be -1, 0 or 1`);
if (card.keyword !== null && !(KEYWORD_IDS as readonly string[]).includes(card.keyword)) problems.push(`${label}: unknown keyword ${card.keyword}`);
if (card.source !== 'owned' && card.source !== 'loaner') problems.push(`${label}: bad source`);
if (card.check !== undefined && !CHECKS.has(card.check)) problems.push(`${label}: bad check`);
if (card.source === 'loaner') loaners++;
if (card.source === 'owned' && !rules.ownedCards) problems.push(`${label}: owned cards are not allowed in this mode`);
// §2 / §2.1: owned and loaner copies count together by pageId; unpinned loaners (pageId null) by cardId.
const key = card.pageId !== null ? `page:${card.pageId}` : `card:${card.cardId}`;
const n = (copies.get(key) ?? 0) + 1;
copies.set(key, n);
if (n === rules.maxCopiesPerPage + 1) problems.push(`More than ${rules.maxCopiesPerPage} copies of ${card.pageId !== null ? `page ${card.pageId}` : card.cardId}`);
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}`);
}
}
if (loaners > rules.maxLoaners) problems.push(`At most ${rules.maxLoaners} loaner cards`);
return problems;
}
// ---------- match setup (§4) ----------
// ---------- match setup ----------
/**
* Draw the match's Topics (§4.2.3). distinctStats: for each stat in STATS order
* (attention, depth, reach) pick one Topic of that stat with rng.int(groupSize),
* then Fisher–Yates the picks, then keep the first topicCount. Otherwise
* Fisher–Yates the whole pool and keep the first topicCount.
* Start a match. `decks[0]` belongs to player 0. Throws IllegalActionError for an
* invalid deck and ZodError for an invalid ruleset.
*/
function drawTopics(rules: Ruleset, rng: Rng): TopicDef[] {
if (!rules.distinctStats) return rng.shuffle(rules.topicPool).slice(0, rules.topicCount);
const picked: TopicDef[] = [];
for (const stat of STATS) {
const group = rules.topicPool.filter(topic => topic.stat === stat);
if (group.length) picked.push(group[rng.int(group.length)]);
}
return rng.shuffle(picked).slice(0, rules.topicCount);
}
/**
* Start a match. `decks[0]` belongs to seat 0. Seed is a uint32 (or a string,
* hashed with FNV-1a). Throws ZodError for a bad ruleset, IllegalActionError for a bad deck.
*/
export function createMatch(ruleset: Ruleset, decks: readonly [readonly GameCard[], readonly GameCard[]], seed: number | string): MatchState {
export function createMatch(ruleset: Ruleset, decks: readonly [readonly GameCard[], readonly GameCard[]], seed: string): MatchState {
const rules = parseRuleset(clone(ruleset));
const seedValue = normalizeSeed(seed);
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] as GameCard[]);
if (problems.length) throw new IllegalActionError(`Seat ${player} deck: ${problems.join('; ')}`);
const problems = validateDeck(rules, decks[player] ?? []);
if (problems.length) throw new IllegalActionError(`Player ${player} deck: ${problems.join('; ')}`);
}
const rng = new Rng(seedValue);
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, queue: [], committed: false, afk: 0, carry: 0,
deck: rng.shuffle(clone(decks[player])), hand: [], energy: 0, staged: [], ended: false, discard: [],
});
const p0 = newPlayer(0);
const p1 = newPlayer(1);
const topics = drawTopics(rules, rng);
const initiative: PlayerId = rng.next() < 0.5 ? 0 : 1;
const players: [PlayerState, PlayerState] = [newPlayer(0), newPlayer(1)];
const state: MatchState = {
schema: 'wikideck-match/1', engineVersion: ENGINE_VERSION, ruleset: rules, seed: seedValue, rng: rng.state,
turn: 0, phase: 'planning', initiative, revealSeq: 0, players: [p0, p1],
lanes: topics.map(topic => ({ topic: clone(topic), portalRevealed: false, cards: [[], []] as [CardInPlay[], CardInPlay[]] })),
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.openingHand; i++) draw(state, player);
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;
@@ -111,179 +74,136 @@ export function createMatch(ruleset: Ruleset, decks: readonly [readonly GameCard
function draw(state: MatchState, player: PlayerId): void {
const p = state.players[player];
if (!p.deck.length || p.hand.length >= state.ruleset.handLimit) return;
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.cardId });
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 }),
power: card => cardPower(state, card),
};
return { state, rng, params: params ?? {}, lane, log: text => state.log.push({ t: 'effect', source, player, text }) };
}
/** Enabled keyword definition for a card, if any. */
function keywordOf(state: MatchState, card: GameCard): KeywordDef | undefined {
return card.keyword && state.ruleset.keywordsEnabled.includes(card.keyword) ? KEYWORDS[card.keyword] : undefined;
function keywordOf(state: MatchState, card: GameCard) {
return card.keyword && Object.hasOwn(state.ruleset.keywords, card.keyword) ? KEYWORDS[card.keyword] : undefined;
}
function keywordCtx(state: MatchState, rng: Rng, keyword: KeywordDef, card: CardInPlay): EffectContext {
return context(state, rng, state.ruleset.keywordParams[keyword.id], card.lane, keyword.id, card.owner);
}
function portalCtx(state: MatchState, rng: Rng, lane: number, portal: PortalDef, player: PlayerId): EffectContext {
const topic = state.lanes[lane].topic;
const params = state.ruleset.portalParams[topic.id] ?? state.ruleset.portalParams[portal.id];
return context(state, rng, params, lane, portal.id, player);
}
/** Per-seat card capacity of a lane (a Portal may override it, e.g. Stub). */
export function laneCapacity(state: MatchState, lane: number): number {
const portal = activePortal(state, lane);
return portal?.capacity ? portal.capacity(portalCtx(state, new Rng(state.rng), lane, portal, state.initiative)) : state.ruleset.laneCapacity;
}
/** §5.1 Start (Portal reveal, energy, draw), then §5.2 Underdog. Initiative alternates (§5.5). */
function startTurn(state: MatchState, rng: Rng): void {
state.turn += 1;
if (state.turn > 1) state.initiative = other(state.initiative);
const rules = state.ruleset;
state.lanes.forEach((lane, index) => {
if (lane.portalRevealed || (rules.portalReveal[index] ?? 1) > state.turn) return;
lane.portalRevealed = true;
state.log.push({ t: 'portalRevealed', lane: index, topic: clone(lane.topic) });
const portal = activePortal(state, index);
portal?.onPortalReveal?.(portalCtx(state, rng, index, portal, state.initiative));
});
const base = (rules.energyByTurn[state.turn - 1] ?? rules.energyByTurn.at(-1)!) + rules.bonusEnergy;
for (const player of PLAYERS) {
const p = state.players[player];
Object.assign(p, { energy: base + p.carry, queue: [], committed: false });
}
for (const player of PLAYERS) draw(state, player);
if (rules.underdog && state.turn >= 2) {
const led = topicsLed(state);
for (const player of PLAYERS) if (led[player] === 0 && led[other(player)] >= 2) {
state.players[player].energy += 1;
state.log.push({ t: 'underdog', player });
}
}
state.log.push({ t: 'turnStart', turn: state.turn, energy: [state.players[0].energy, state.players[1].energy], initiative: state.initiative });
}
// ---------- power (§6) ----------
/** A card's current lane power (§6, never below 0). */
/** Current power of one card in play, including ongoing keyword and lane effects. */
export function cardPower(state: MatchState, target: CardInPlay): number {
const rules = state.ruleset;
const scratch = new Rng(state.rng); // ongoing effects must not consume real randomness
let power = target.card.power + target.bonus + target.card.trend;
if (isOnTopic(state, target)) power += rules.onTopicBonus[target.card.cost] ?? 0;
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(keywordCtx(state, scratch, keyword, source), source, target);
if (keyword?.ongoing) power += keyword.ongoing(context(state, scratch, state.ruleset.keywords[keyword.id], source.lane, keyword.id, source.owner), source, target);
}
const portal = activePortal(state, target.lane);
if (portal?.ongoing) power += portal.ongoing(portalCtx(state, scratch, target.lane, portal, target.owner), target);
return Math.max(0, power);
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;
}
/** [seat 0 power, seat 1 power] in one lane (during play; excludes "at scoring" Portals). */
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];
}
/** §6: who leads a lane given its powers. Equal and > 0 → more on-topic cards leads (consensus). */
export function laneLeader(state: MatchState, lane: number, power: [number, number] = lanePower(state, lane)): PlayerId | null {
const [a, b] = power;
if (a !== b) return a > b ? 0 : 1;
if (a === 0) return null;
const onTopic = PLAYERS.map(player => state.lanes[lane].cards[player].filter(card => isOnTopic(state, card)).length);
return onTopic[0] === onTopic[1] ? null : onTopic[0] > onTopic[1] ? 0 : 1;
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 };
}
/** Number of Topics each seat leads right now (with the consensus tie-break). */
export function topicsLed(state: MatchState): [number, number] {
const led: [number, number] = [0, 0];
state.lanes.forEach((_, lane) => {
const leader = laneLeader(state, lane);
if (leader !== null) led[leader]++;
});
return led;
}
// ---------- actions ----------
/** Final lane powers: lanePower plus revealed "at scoring" Portals (§7, §10.3). */
export function scoringPower(state: MatchState, lane: number): [number, number] {
const power = lanePower(state, lane);
const portal = activePortal(state, lane);
if (!portal?.atScoring) return power;
const [d0, d1] = portal.atScoring(portalCtx(state, new Rng(state.rng), lane, portal, state.initiative));
return [power[0] + d0, power[1] + d1];
}
// ---------- actions (§5.3) ----------
const queuedCost = (p: PlayerState) => p.queue.reduce((sum, play) => sum + (p.hand.find(c => c.cardId === play.cardId)?.cost ?? 0), 0);
const queuedInLane = (p: PlayerState, lane: number) => p.queue.filter(play => play.lane === lane).length;
function laneRejects(state: MatchState, lane: number, card: GameCard, player: PlayerId): string | null {
const portal = activePortal(state, lane);
if (!portal?.canPlay) return null;
return portal.canPlay(portalCtx(state, new Rng(state.rng), lane, portal, player), card, player) ? null : `${portal.name} rejects this card`;
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.committed) return 'Already committed this turn';
const card = p.hand.find(c => c.cardId === action.cardId);
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.queue.some(play => play.cardId === action.cardId)) return 'Card is already queued';
if (!Number.isInteger(action.lane) || action.lane < 0 || action.lane >= state.lanes.length) return 'No such Topic';
if (card.cost > p.energy - queuedCost(p)) return 'Not enough energy';
if (state.lanes[action.lane].cards[action.player].length + queuedInLane(p, action.lane) >= laneCapacity(state, action.lane)) return 'Topic is full';
return laneRejects(state, action.lane, card, action.player);
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';
const p = state.players[action.player];
switch (action.type) {
case 'play': return playProblem(state, action);
case 'undo':
if (p.committed) return 'Already committed this turn';
return p.queue.some(play => play.cardId === action.cardId) ? null : 'Card is not queued';
case 'commit':
case 'timeout':
return p.committed ? 'Already committed this turn' : null;
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';
}
}
/**
* Legal actions for `player`: every `play`, every `undo`, and `commit`.
* `concede` (always legal while running) and `timeout` (host-only) are not listed.
* Empty once the player has committed or the match is over.
* 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.committed) return [];
if (p.ended) return [];
const actions: Action[] = [];
for (const card of p.hand) {
if (p.queue.some(play => play.cardId === card.cardId)) continue;
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.cardId, lane };
const action: Action = { type: 'play', player, cardId: card.id, lane };
if (!playProblem(state, action)) actions.push(action);
}
}
for (const play of p.queue) actions.push({ type: 'undo', player, cardId: play.cardId });
actions.push({ type: 'commit', player });
for (const play of p.staged) actions.push({ type: 'unstage', player, cardId: play.cardId });
actions.push({ type: 'endTurn', player });
return actions;
}
@@ -296,92 +216,67 @@ export function applyAction(state: MatchState, action: Action): MatchState {
const p = next.players[action.player];
const rng = new Rng(next.rng);
switch (action.type) {
case 'play': p.queue.push({ cardId: action.cardId, lane: action.lane }); break;
case 'undo': p.queue.splice(p.queue.findIndex(play => play.cardId === action.cardId), 1); break;
case 'commit': p.committed = true; p.afk = 0; break;
case 'timeout':
p.committed = true;
p.afk = p.queue.length ? 0 : p.afk + 1;
if (p.afk >= next.ruleset.afkTurns) {
next.log.push({ t: 'concede', player: action.player, afk: true });
finish(next, other(action.player), 'afk');
}
case 'play': {
p.staged.push({ cardId: action.cardId, lane: action.lane });
p.energy -= p.hand.find(c => c.id === action.cardId)!.cost;
break;
case 'concede':
next.log.push({ t: 'concede', player: action.player, afk: false });
}
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;
}
}
if (next.phase !== 'over' && next.players.every(player => player.committed)) resolveTurn(next, rng);
next.rng = rng.state;
return next;
}
/** §5.4 Reveal (interleaved) and §5.5 End. */
function resolveTurn(state: MatchState, rng: Rng): void {
const rules = state.ruleset;
const order: PlayerId[] = [state.initiative, other(state.initiative)];
// Carry (§5.1): energy not reserved by a queued play. Fizzled plays still spent theirs.
for (const player of PLAYERS) {
for (const player of [state.firstToReveal, other(state.firstToReveal)]) {
const p = state.players[player];
p.carry = Math.min(rules.energyCarryMax, Math.max(0, p.energy - queuedCost(p)));
}
const queues = order.map(player => state.players[player].queue.slice());
for (let i = 0; i < Math.max(queues[0].length, queues[1].length); i++) {
for (const [k, player] of order.entries()) {
const play = queues[k][i];
if (play) reveal(state, rng, player, play.cardId, play.lane);
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 = [];
}
for (const player of PLAYERS) state.players[player].queue = [];
for (const player of order) for (const lane of state.lanes) {
for (const card of lane.cards[player].slice().sort((x, y) => x.seq - y.seq)) {
const keyword = keywordOf(state, card.card);
keyword?.endOfTurn?.(keywordCtx(state, rng, keyword, card), card);
}
}
if (state.turn >= rules.turns) finish(state, null, 'topics');
if (state.turn >= state.ruleset.maxTurns) finish(state, null, 'lanes');
else startTurn(state, rng);
}
function reveal(state: MatchState, rng: Rng, player: PlayerId, cardId: string, lane: number): void {
const p = state.players[player];
const index = p.hand.findIndex(c => c.cardId === cardId);
const card = p.hand[index];
if (index < 0 || state.lanes[lane].cards[player].length >= laneCapacity(state, lane) || laneRejects(state, lane, card, player)) {
state.log.push({ t: 'fizzle', player, cardId, lane }); // stays in hand, energy lost
return;
}
p.hand.splice(index, 1);
const inPlay: CardInPlay = { card, owner: player, lane, turn: state.turn, seq: ++state.revealSeq, bonus: 0 };
state.lanes[lane].cards[player].push(inPlay);
state.log.push({ t: 'reveal', player, cardId, lane });
const keyword = keywordOf(state, card);
keyword?.onReveal?.(keywordCtx(state, rng, keyword, inPlay), inPlay);
const portal = activePortal(state, lane);
portal?.onReveal?.(portalCtx(state, rng, lane, portal, player), inPlay);
}
/** §7 scoring (after the last End phase, with "at scoring" Portals), or a concede. */
function finish(state: MatchState, forcedWinner: PlayerId | null, reason: 'topics' | 'concede' | 'afk'): void {
const lanePowers = state.lanes.map((_, lane) => scoringPower(state, lane));
const led: [number, number] = [0, 0];
const totalPower: [number, number] = [0, 0];
lanePowers.forEach((power, lane) => {
const leader = laneLeader(state, lane, power);
if (leader !== null) led[leader]++;
totalPower[0] += power[0]; totalPower[1] += power[1];
});
let winner: PlayerId | null = forcedWinner;
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 === 'topics') {
if (led[0] !== led[1]) winner = led[0] > led[1] ? 0 : 1;
else if (totalPower[0] !== totalPower[1]) { winner = totalPower[0] > totalPower[1] ? 0 : 1; why = 'totalPower'; }
else why = 'draw';
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, topicsLed: led, lanePower: lanePowers, totalPower, turns: state.turn };
state.result = { winner, reason: why, ...s, turns: state.turn };
state.phase = 'over';
state.log.push({ t: 'matchOver', result: clone(state.result) });
state.log.push({ t: 'matchOver', result: state.result });
}
// ---------- queries ----------
@@ -391,34 +286,28 @@ export function isOver(state: MatchState): boolean { return state.phase === 'ove
/** 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 seat. Send only this to clients and AIs. */
/** 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, initiative: state.initiative,
energy: me.energy, energyLeft: me.energy - queuedCost(me), hand: me.hand, queue: me.queue,
committed: me.committed, deckCount: me.deck.length,
opponent: { handCount: opp.hand.length - opp.queue.length, deckCount: opp.deck.length, queuedCount: opp.queue.length, committed: opp.committed },
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);
const mine = power[you], theirs = power[them];
const leader = laneLeader(state, index, power);
return {
// Until its Portal is revealed only the stat is visible (the id/name would give the Portal away).
topic: lane.portalRevealed ? lane.topic : { id: `lane-${index + 1}`, name: '?', stat: lane.topic.stat, portal: null },
portalRevealed: lane.portalRevealed,
modifier: revealed ? lane.modifier : null, modifierRevealed: revealed,
cards: [lane.cards[you], lane.cards[them]] as [CardInPlay[], CardInPlay[]],
cardPower: [lane.cards[you].map(c => cardPower(state, c)), lane.cards[them].map(c => cardPower(state, c))] as [number[], number[]],
power: [mine, theirs] as [number, number],
leader: leader === null ? null : leader === you ? 'you' as const : 'opponent' as const,
power: [power[you], power[them]] as [number, number],
};
}),
result: state.result,
});
}
// ---------- serialisation, replay, test helpers ----------
// ---------- serialisation / replay ----------
export function serialize(state: MatchState): string { return JSON.stringify(state); }
@@ -430,25 +319,6 @@ export function deserialize(json: string): MatchState {
}
/** 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: number | string, actions: readonly Action[]): MatchState {
let state = createMatch(ruleset, decks, seed);
for (const action of actions) state = applyAction(state, action);
return state;
}
/**
* Test helper: put `card` straight into a lane (no on-reveal, no energy, no hand).
* Returns a new state. For unit-testing keywords against hand-built boards.
*/
export function placeCard(state: MatchState, player: PlayerId, lane: number, card: GameCard, bonus = 0): MatchState {
const next = clone(state);
next.lanes[lane].cards[player].push({ card: clone(card), owner: player, lane, turn: next.turn, seq: ++next.revealSeq, bonus });
return next;
}
/** Test helper: reveal a Topic's Portal now (runs nothing). */
export function revealPortal(state: MatchState, lane: number): MatchState {
const next = clone(state);
next.lanes[lane].portalRevealed = true;
return next;
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));
}
+6 -6
View File
@@ -1,10 +1,10 @@
/** Public entry point of the WikiDeck game engine. Other teams import only from here. See docs/game/ENGINE_API.md. */
/** Public entry point of the WikiDeck game engine. See docs/game/ENGINE_API.md. */
export * from './types.ts';
export { Rng, seedFromString, normalizeSeed, type RngState } from './rng.ts';
export { DEFAULT_RULESET, DEFAULT_TOPIC_POOL, RulesetSchema, TopicSchema, parseRuleset } from './ruleset.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, laneLeader, laneCapacity, scoringPower, topicsLed, other, placeCard, revealPortal,
serialize, deserialize, replay, validateDeck, cardPower, lanePower, modifierActive,
} from './engine.ts';
export { KEYWORDS, PORTALS, KEYWORD_IDS, PORTAL_IDS, allies, activePortal, isOnTopic, type KeywordDef, type PortalDef, type EffectContext } from './keywords.ts';
export { STARTER_POOL, loanerCard, previewPool, starterDeck } from './starter.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';
+168 -55
View File
@@ -1,74 +1,50 @@
/**
* Keyword and Portal registry (DESIGN §10.2, §10.3). Effects are code here; which
* ones a card/topic uses and their numbers are data (GameCard.keyword,
* TopicDef.portal, Ruleset.keywordsEnabled / keywordParams / portalParams).
* Owner of the effects: engine-b (claude/wikideck#3). engine-a owns the hook contract:
* 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.
*
* - Hooks get an EffectContext over the engine's *working copy* of the state and may
* mutate it (e.g. `bonus` on cards). Safe: applyAction already cloned.
* Any randomness must come from ctx.rng (match RNG, resolution order, §4.2.5).
* - A keyword's hooks run only if its id is in ruleset.keywordsEnabled.
* - onReveal(ctx, self): right after `self` is pushed into its lane (§5.4). Cards revealed
* earlier (any seat, any turn) are on the board; later ones are not. self.seq is its global
* reveal number; cards revealed this turn have `turn === ctx.state.turn`.
* - endOfTurn(ctx, self): §5.5 order: initiative seat's cards first, then lanes 1→N, then seq.
* Also runs on the last turn, before scoring (§7).
* - ongoing(ctx, self, target) → delta: PURE. Called for every (self, target) pair in play,
* including self === target. ctx.rng is a throwaway copy. Don't call ctx.power on a card from
* inside ongoing (infinite recursion); read base fields instead.
* - Portals: same, plus onPortalReveal(ctx), canPlay(ctx, card, seat), capacity(ctx) → number
* (lane capacity override), allOnTopic (Disambiguation) and atScoring(ctx) → [delta0, delta1]
* (Topic power added at scoring, §7). All Portal hooks apply only once the Portal is revealed.
* Params: ruleset.portalParams[topic.id], falling back to portalParams[portal id].
* - Hooks must not throw and must not move or remove cards (§10, v1).
* 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, GameCard, MatchState, PlayerId } from './types.ts';
/** The 9 implemented keyword ids (§10.2; edition, obscure and wildcard are disabled by default). */
export const KEYWORD_IDS = ['viral', 'rising', 'local', 'encyclopedic', 'nostalgic', 'translated', 'edition', 'obscure', 'wildcard'] as const;
/** The 6 Portal kinds (§10.3), named after their default Topic. */
export const PORTAL_IDS = ['main-page', 'trending', 'featured-article', 'stub', 'interwiki', 'disambiguation'] as const;
import type { CardInPlay, Category, GameCard, MatchState, PlayerId } from './types.ts';
export interface EffectContext {
state: MatchState;
rng: Rng;
/** Tunable numbers for this keyword/portal from the ruleset. */
/** Tunable numbers for this keyword/modifier from the ruleset. */
params: Record<string, number>;
/** Lane the effect lives in. */
lane: number;
/** Add a line to the match log (attributed to this keyword/portal). */
log(text: string): void;
/** Current lane power of a card in play (the engine's cardPower). Not for use inside `ongoing`. */
power(card: CardInPlay): number;
/** 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;
/** One short line of reminder text with {param} placeholders. */
/** Short rules text with {param} placeholders, for card faces/tooltips. */
text: string;
onReveal?(ctx: EffectContext, self: CardInPlay): void;
endOfTurn?(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 PortalDef {
export interface LaneModifierDef {
id: string;
name: string;
text: string;
onPortalReveal?(ctx: EffectContext): void;
/** Runs when any card is revealed in this Topic (after the card's own onReveal). */
/** 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;
/** Lets a Topic reject a card; checked when queuing and again at reveal. */
canPlay?(ctx: EffectContext, card: GameCard, player: PlayerId): boolean;
/** Per-player lane capacity in this Topic (replaces ruleset.laneCapacity). */
capacity?(ctx: EffectContext): number;
/** Every card here counts as on-topic. */
allOnTopic?: boolean;
/** Topic power added to [seat 0, seat 1] here at scoring. */
atScoring?(ctx: EffectContext): [number, number];
}
/** Cards on the same side of the same lane, excluding `self`. */
@@ -76,20 +52,157 @@ export function allies(state: MatchState, self: CardInPlay): CardInPlay[] {
return state.lanes[self.lane].cards[self.owner].filter(card => card !== self);
}
/** The lane's Portal, if it has one and it is revealed. */
export function activePortal(state: MatchState, lane: number): PortalDef | undefined {
/** 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];
return l?.portalRevealed && l.topic.portal ? PORTALS[l.topic.portal] : undefined;
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;
}
/** §1.4/§6 on-topic: home stat matches the Topic's stat, or an active Disambiguation-style Portal. */
export function isOnTopic(state: MatchState, card: CardInPlay): boolean {
const lane = state.lanes[card.lane];
return lane.topic.stat === card.card.home || activePortal(state, card.lane)?.allOnTopic === true;
/** 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);
}
/** Filled in by engine-b (§10.2). Ids must be in KEYWORD_IDS. */
export const KEYWORDS: Record<string, KeywordDef> = {};
/** 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');
}
/** Filled in by engine-b (§10.3). Ids must be in PORTAL_IDS. */
export const PORTALS: Record<string, PortalDef> = {};
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;
+42 -25
View File
@@ -1,50 +1,67 @@
/**
* Seeded, serialisable PRNG for the game engine (off-chain only).
* DESIGN.md §4: mulberry32(seed: uint32). The state is one uint32, so it
* 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;
export type RngState = [number, number, number, number];
/** Hash a string seed (e.g. a lobby id) to a uint32 with FNV-1a. */
export function seedFromString(text: string): number {
let h = 0x811c9dc5;
function cyrb128(text: string): RngState {
let h1 = 1779033703, h2 = 3144134277, h3 = 1013904242, h4 = 2773480762;
for (let i = 0; i < text.length; i++) {
h ^= text.charCodeAt(i);
h = Math.imul(h, 0x01000193);
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);
}
return h >>> 0;
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 normalizeSeed(seed: number | string): number {
if (typeof seed === 'string') return seedFromString(seed);
if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff) throw new RangeError('Seed must be a uint32 or a string');
return seed >>> 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; }
static fromSeed(seed: number | string): Rng { return new Rng(normalizeSeed(seed)); }
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)); }
/** mulberry32: float in [0, 1). */
next(): number {
this.state = (this.state + 0x6d2b79f5) >>> 0;
let t = this.state;
t = Math.imul(t ^ (t >>> 15), t | 1);
t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
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;
}
/** Integer in [0, n): floor(next() × n), as DESIGN.md §4 specifies. */
/** 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) throw new RangeError('Rng.int needs a positive integer bound');
return Math.floor(this.next() * n);
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 per DESIGN.md §4: i from n−1 down to 1, j = floor(next() × (i+1)). Returns a new array. */
/** 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--) {
+50 -107
View File
@@ -1,81 +1,43 @@
/**
* Ruleset (DESIGN §9 RulesConfig): 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; its bounds keep matches short and
* guarantee termination.
* 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 { KEYWORD_IDS, PORTAL_IDS } from './keywords.ts';
import { STATS, type Ruleset } from './types.ts';
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 id = z.string().regex(/^[a-z0-9][a-z0-9-]{0,31}$/);
const params = z.record(z.string().regex(/^[A-Za-z0-9]{1,24}$/), z.number().finite().min(-100).max(100))
.refine(value => Object.keys(value).length <= 8, 'At most 8 params');
const paramTable = z.record(id, params).refine(value => Object.keys(value).length <= 32, 'At most 32 entries');
export const TopicSchema = z.object({
id, name: z.string().min(1).max(32), stat: z.enum(STATS as [string, ...string[]]), portal: z.enum(PORTAL_IDS).nullable(),
}).strict();
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({
version: z.string().min(1).max(16),
deckSize: int(1, 30),
maxCopiesPerPage: int(1, 30),
maxLoaners: int(0, 30),
openingHand: int(0, 10),
handLimit: int(1, 12),
mulligan: z.literal(false), // not implemented in v1
turns: int(1, 12),
turnSeconds: int(5, 120),
afkTurns: int(1, 12),
energyByTurn: z.array(int(0, 20)).min(1).max(12),
energyCarryMax: int(0, 10),
bonusEnergy: int(0, 10),
underdog: z.boolean(),
topicCount: int(1, 5),
distinctStats: z.boolean(),
portalReveal: z.array(int(1, 12)).max(5),
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),
topicPool: z.array(TopicSchema).min(1).max(32),
keywordParams: paramTable,
portalParams: paramTable,
costThresholds: z.array(int(0, 100)).length(5),
powerByCost: z.array(int(0, 30)).length(7),
onTopicBonus: z.array(int(0, 10)).length(7),
vanillaBonus: int(0, 10),
keywordsEnabled: z.array(z.enum(KEYWORD_IDS)).max(KEYWORD_IDS.length),
ownedCards: z.boolean(),
trendUp: z.number().finite().min(-1000).max(1000),
trendDown: z.number().finite().min(-1000).max(1000),
trendMinDaily: z.number().finite().min(0).max(1e9),
uncheckedCostCap: int(1, 6),
factionSynergyCap: int(0, 12),
verifyStats: z.boolean(),
percentiles: id,
starterDecks: id,
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.turns * rules.turnSeconds > 240) issue('turns × turnSeconds must be ≤ 240');
if (rules.energyByTurn.length < rules.turns) issue('energyByTurn needs one entry per turn');
if (rules.portalReveal.length !== rules.topicCount) issue('portalReveal needs one entry per Topic');
if (rules.openingHand > rules.handLimit) issue('openingHand > handLimit');
if (rules.trendDown > rules.trendUp) issue('trendDown > trendUp');
if (rules.costThresholds.some((value, i) => i > 0 && value < rules.costThresholds[i - 1])) issue('costThresholds must ascend');
if (rules.distinctStats) {
if (rules.topicCount !== STATS.length) issue('distinctStats needs topicCount == 3');
const stats = new Set(rules.topicPool.map(topic => topic.stat));
if (stats.size < rules.topicCount) issue('topicPool lacks enough distinct stats');
} else if (rules.topicPool.length < rules.topicCount) issue('topicPool smaller than topicCount');
const topicIds = new Set<string>();
for (const topic of rules.topicPool) {
if (topicIds.has(topic.id)) issue(`Duplicate topic id: ${topic.id}`);
topicIds.add(topic.id);
}
if (new Set(rules.keywordsEnabled).size !== rules.keywordsEnabled.length) issue('Duplicate keywordsEnabled entry');
for (const key of Object.keys(rules.keywordParams)) if (!(KEYWORD_IDS as readonly string[]).includes(key)) issue(`Unknown keyword: ${key}`);
for (const key of Object.keys(rules.portalParams))
if (!topicIds.has(key) && !(PORTAL_IDS as readonly string[]).includes(key)) issue(`portalParams key is neither a Topic id nor a Portal id: ${key}`);
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. */
@@ -83,45 +45,26 @@ export function parseRuleset(input: unknown): Ruleset {
return RulesetSchema.parse(input) as Ruleset;
}
/** DESIGN §10.3 default Topic pool: per stat one plain Topic and two with Portals. Portal kind = Topic id. */
export const DEFAULT_TOPIC_POOL: Ruleset['topicPool'] = [
{ id: 'current-events', name: 'Current Events', stat: 'attention', portal: null },
{ id: 'main-page', name: 'Main Page', stat: 'attention', portal: 'main-page' },
{ id: 'trending', name: 'Trending', stat: 'attention', portal: 'trending' },
{ id: 'archive', name: 'Archive', stat: 'depth', portal: null },
{ id: 'featured-article', name: 'Featured Article', stat: 'depth', portal: 'featured-article' },
{ id: 'stub', name: 'Stub', stat: 'depth', portal: 'stub' },
{ id: 'translations', name: 'Translations', stat: 'reach', portal: null },
{ id: 'interwiki', name: 'Interwiki', stat: 'reach', portal: 'interwiki' },
{ id: 'disambiguation', name: 'Disambiguation', stat: 'reach', portal: 'disambiguation' },
];
/** DESIGN §9 defaults (v1). */
/** Placeholder base rules (Snap-style lanes) until DESIGN.md v1 lands. */
export const DEFAULT_RULESET: Ruleset = {
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_TOPIC_POOL,
keywordParams: {
viral: { amount: 1, cap: 2, powerDelta: 0 }, rising: { amount: 1, cap: 2, powerDelta: 0 },
local: { amount: 1, powerDelta: 0 }, encyclopedic: { amount: 2, powerDelta: 0 },
nostalgic: { amount: 2, powerDelta: 0 }, translated: { amount: 1, powerDelta: 0 },
edition: { amount: 2, powerDelta: 0 }, obscure: { powerDelta: 0 }, wildcard: { powerDelta: 0 },
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 } },
},
portalParams: {
'main-page': { amount: 1 }, trending: { factor: 2 }, 'featured-article': { amount: 2 },
stub: { value: 2 }, interwiki: { amount: 1 },
},
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: ['viral', 'rising', 'local', 'encyclopedic', 'nostalgic', 'translated'], ownedCards: true,
trendUp: 25, trendDown: -200, trendMinDaily: 20, uncheckedCostCap: 4,
factionSynergyCap: 3,
verifyStats: true,
percentiles: 'card-sample-2026-11-16',
starterDecks: 'default',
tieBreak: 'totalPower',
};
export function energyForTurn(rules: Ruleset, turn: number): number {
return Math.min(rules.energy.max, rules.energy.start + (turn - 1) * rules.energy.perTurn);
}
-66
View File
@@ -1,66 +0,0 @@
/**
* PLACEHOLDER loaner cards and starter decks (DESIGN §2) so the engine, UI and
* sims can run before council-data's docs/game/starter-cards.json lands.
* Loaners are off-chain preview cards: not NFTs, never minted or moved.
* engine-b / council-data replace STARTER_POOL with derived cards (cards.ts).
*/
import { Rng } from './rng.ts';
import type { Faction, GameCard, Stat } from './types.ts';
type Spec = [pageId: number, title: string, faction: Faction, cost: number, home: Stat];
/** DESIGN §1.3 powerByCost and §10.1 keyword choice (cost 1 = vanilla +vanillaBonus). pageIds outside shared/catalog.ts are unverified. */
const POWER_BY_COST = [0, 1, 2, 4, 6, 8, 10];
const VANILLA_BONUS = 1;
const FACTION_KEYWORD: Record<Faction, string> = {
Culture: 'viral', Nature: 'rising', People: 'local', Science: 'encyclopedic', History: 'nostalgic', Space: 'translated',
};
export const STARTER_POOL: readonly Spec[] = [
[22780, 'Octopus', 'Nature', 1, 'depth'],
[19331, 'Moon', 'Space', 1, 'reach'],
[23053, 'Periodic table', 'Science', 1, 'depth'],
[3383, 'Bronze Age', 'History', 1, 'depth'],
[5843419, 'Chess', 'Culture', 2, 'attention'],
[9228, 'Earth', 'Space', 2, 'reach'],
[2008, 'Ada Lovelace', 'People', 2, 'attention'],
[21830, 'Honey bee', 'Nature', 2, 'depth'],
[736, 'Albert Einstein', 'People', 3, 'reach'],
[10979, 'Fungus', 'Nature', 3, 'depth'],
[26903, 'Solar System', 'Space', 3, 'reach'],
[30758, 'Roman Empire', 'History', 3, 'depth'],
[9649, 'Evolution', 'Science', 4, 'depth'],
[8424, 'Jazz', 'Culture', 4, 'attention'],
[12898, 'Marie Curie', 'People', 4, 'reach'],
[14533, 'Silk Road', 'History', 4, 'reach'],
[19468, 'Mount Everest', 'Nature', 5, 'attention'],
[22936, 'Photosynthesis', 'Science', 5, 'depth'],
[18110, 'Leonardo da Vinci', 'People', 5, 'reach'],
[14627, 'Ancient Egypt', 'History', 5, 'attention'],
[4177, 'Black hole', 'Space', 6, 'attention'],
[25443, 'Quantum mechanics', 'Science', 6, 'depth'],
[17867, 'Library of Alexandria', 'History', 6, 'depth'],
[20217, 'Music', 'Culture', 6, 'reach'],
];
export function loanerCard(spec: Spec, copy = 0): GameCard {
const [pageId, title, faction, cost, home] = spec;
const keyword = cost === 1 ? null : FACTION_KEYWORD[faction];
return {
cardId: `loaner:${pageId}:${copy}`, pageId, title, faction, rarity: 'Common', cost,
power: POWER_BY_COST[cost] + (keyword ? 0 : VANILLA_BONUS), home, trend: 0, keyword, source: 'loaner', check: 'loaner',
};
}
/** Every placeholder loaner card, once each (24 cards). Draft modes can sample from this. */
export function previewPool(): GameCard[] { return STARTER_POOL.map(spec => loanerCard(spec)); }
/** A deterministic 12-card loaner deck: 2 cards of each cost 1–6, chosen by `seed`. */
export function starterDeck(seed: number | string): GameCard[] {
const rng = Rng.fromSeed(`starter:${seed}`);
const deck: GameCard[] = [];
for (let cost = 1; cost <= 6; cost++) {
deck.push(...rng.shuffle(STARTER_POOL.filter(spec => spec[3] === cost)).slice(0, 2).map(spec => loanerCard(spec)));
}
return deck;
}
+66 -138
View File
@@ -1,7 +1,6 @@
/**
* WikiDeck game engine types (off-chain). Implements docs/game/DESIGN.md ("Edit War").
* Everything here is plain JSON data: MatchState round-trips through
* JSON.stringify/parse with no loss (no Maps, classes or functions).
* 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';
@@ -9,98 +8,50 @@ import type { RngState } from './rng.ts';
export type PlayerId = 0 | 1;
export const PLAYERS: readonly PlayerId[] = [0, 1];
/** Category buckets from server/wiki.ts; a card's faction (DESIGN §1.5). */
export type Faction = 'Space' | 'Nature' | 'People' | 'Science' | 'History' | 'Culture';
export const FACTIONS: readonly Faction[] = ['Space', 'Nature', 'People', 'Science', 'History', 'Culture'];
export type Stat = 'attention' | 'depth' | 'reach';
export const STATS: readonly Stat[] = ['attention', 'depth', 'reach'];
export type Rarity = 'Common' | 'Rare' | 'Epic' | 'Legendary';
/** Category buckets from server/wiki.ts. */
export type Category = 'Space' | 'Nature' | 'People' | 'Science' | 'History' | 'Culture';
/**
* A card as the engine sees it: already derived (DESIGN §1) by cards.ts from a
* host-frozen CardInput. The engine never reads raw snapshot stats. Hosts/modes
* may adjust fields (e.g. power) before createMatch; the engine does not re-derive.
*/
/** 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 (the NFT card hash, or `loaner:<pageId>:<n>`). */
cardId: string;
/** null for unpinned loaners (DESIGN §2.1): copies then count per cardId. */
pageId: number | null;
title: string;
faction: Faction;
/** Cosmetic in v1 (§1.7). */
rarity: Rarity;
cost: number;
power: number;
home: Stat;
/** Live trend arrow, frozen at match start (§1.6). Adds to power in every Topic. */
trend: -1 | 0 | 1;
keyword: string | null;
/** 'owned' = an NFT the player holds (never moved or burned by a match). */
source: 'owned' | 'loaner';
/** Host plausibility result (§1.10). Derivation already applied uncheckedCostCap. Default: 'loaner' for loaners, 'verified' for owned. */
check?: 'verified' | 'unverified' | 'unchecked' | 'loaner';
}
/** A Topic (lane) definition in a ruleset's topic pool (§3). */
export interface TopicDef {
/** Unique within one deck (e.g. the NFT card hash, or `starter:<pageId>:<n>`). */
id: string;
name: string;
stat: Stat;
/** Portal kind id in PORTALS (§10.3), or null for a plain Topic. Numbers: Ruleset.portalParams[topic id] (falls back to [portal id]). */
portal: string | null;
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>;
}
/**
* DESIGN §9 RulesConfig: every rule number as flat data so peer-hosted modes can
* override it. Use parseRuleset() for untrusted input.
*/
/** All rule numbers. Peer-hosted modes override these as data (see ruleset.ts). */
export interface Ruleset {
version: string;
deckSize: number;
maxCopiesPerPage: number;
maxLoaners: number;
openingHand: number;
handLimit: number;
mulligan: boolean;
turns: number;
turnSeconds: number;
afkTurns: number;
/** energyByTurn[t-1] is the base energy on turn t. Length must be ≥ turns. */
energyByTurn: number[];
/** Unspent energy carried to next turn, capped at this. */
energyCarryMax: number;
bonusEnergy: number;
underdog: boolean;
topicCount: number;
distinctStats: boolean;
/** portalReveal[i] = turn on which Topic i's Portal is revealed (stats are always visible). Length = topicCount. */
portalReveal: number[];
id: string;
name: string;
version: number;
lanes: number;
/** Cards that may sit on one side of one lane. */
laneCapacity: number;
topicPool: TopicDef[];
/** Per-keyword numbers, keyed by keyword id. */
keywordParams: Record<string, Record<string, number>>;
/** Per-Portal numbers, keyed by Topic id (or Portal kind id as a fallback). */
portalParams: Record<string, Record<string, number>>;
costThresholds: number[];
/** Index = cost (0–6). */
powerByCost: number[];
/** Index = cost (0–6): on-topic bonus. */
onTopicBonus: number[];
vanillaBonus: number;
/** Keyword ids whose hooks run. Cards with a disabled keyword are vanilla (derivation handles power). */
keywordsEnabled: string[];
ownedCards: boolean;
trendUp: number;
trendDown: number;
trendMinDaily: number;
uncheckedCostCap: number;
factionSynergyCap: number;
verifyStats: boolean;
/** Id of the percentile reference table used by derive.ts. */
percentiles: string;
/** Id of the starter deck list. */
starterDecks: string;
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 {
@@ -109,61 +60,48 @@ export interface CardInPlay {
lane: number;
/** Turn the card was revealed. */
turn: number;
/** Global reveal sequence number (1, 2, 3 … across both seats and all turns). */
seq: number;
/** Permanent power changes from effects (on-reveal buffs etc.). */
/** Permanent power changes from effects (onReveal buffs etc.). */
bonus: number;
}
export interface QueuedPlay { cardId: string; lane: number }
export interface StagedPlay { cardId: string; lane: number }
export interface PlayerState {
deck: GameCard[];
hand: GameCard[];
/** Energy available this turn (before queued plays). */
/** Energy left this turn (after staging). */
energy: number;
/** Plays chosen this turn, hidden from the opponent until reveal. Order matters. */
queue: QueuedPlay[];
committed: boolean;
/** Consecutive timeouts with nothing queued (§7 afkTurns). */
afk: number;
/** Energy carried into this turn (already included in `energy`). */
carry: number;
staged: StagedPlay[];
ended: boolean;
discard: GameCard[];
}
export interface LaneState {
/** Stat and name are always visible; the Portal only once portalRevealed. */
topic: TopicDef;
portalRevealed: boolean;
modifier: string | null;
cards: [CardInPlay[], CardInPlay[]];
}
export type MatchPhase = 'planning' | 'over';
export type LogEvent =
| { t: 'turnStart'; turn: number; energy: [number, number]; initiative: PlayerId }
| { t: 'portalRevealed'; lane: number; topic: TopicDef }
| { t: 'underdog'; player: PlayerId }
| { t: 'turnStart'; turn: number; energy: [number, number] }
| { t: 'draw'; player: PlayerId; cardId: string }
| { t: 'reveal'; player: PlayerId; cardId: string; lane: number }
| { t: 'fizzle'; 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; afk: boolean }
| { t: 'concede'; player: PlayerId }
| { t: 'matchOver'; result: MatchResult };
export interface MatchState {
schema: 'wikideck-match/1';
engineVersion: number;
ruleset: Ruleset;
seed: number;
seed: string;
rng: RngState;
/** 1-based current turn. */
turn: number;
phase: MatchPhase;
/** Player who reveals first this turn (§5.4). Alternates every turn. */
initiative: PlayerId;
/** Last reveal sequence number handed out (CardInPlay.seq). */
revealSeq: number;
/** Player who reveals first this turn. */
firstToReveal: PlayerId;
players: [PlayerState, PlayerState];
lanes: LaneState[];
log: LogEvent[];
@@ -173,54 +111,44 @@ export interface MatchState {
}
export type Action =
/** Queue a card from hand into a lane (§5.3). */
| { type: 'play'; player: PlayerId; cardId: string; lane: number }
/** Take back a queued play this turn (refunds its energy). */
| { type: 'undo'; player: PlayerId; cardId: string }
/** Commit the queue (empty = pass). When both have committed, the turn resolves. */
| { type: 'commit'; player: PlayerId }
/** The host's turn timer expired for this player: commits what's queued, counts toward afkTurns if empty. */
| { type: 'timeout'; player: PlayerId }
/** 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: 'topics' | 'totalPower' | 'draw' | 'concede' | 'afk';
topicsLed: [number, number];
/** lanePower[lane][player] at the end, including "at scoring" Portals. */
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. UI and AI read only this, never raw MatchState. */
/** 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;
initiative: PlayerId;
firstToReveal: PlayerId;
energy: number;
/** Energy left after your queued plays. */
energyLeft: number;
hand: GameCard[];
queue: QueuedPlay[];
committed: boolean;
staged: StagedPlay[];
ended: boolean;
deckCount: number;
opponent: { handCount: number; deckCount: number; queuedCount: number; committed: boolean };
opponent: { handCount: number; deckCount: number; stagedCount: number; ended: boolean };
lanes: {
/** Always visible; `portal` is null until the Portal is revealed. */
topic: TopicDef;
portalRevealed: boolean;
/** cards[0] = yours, cards[1] = opponent's (revealed cards only). */
/** null when not yet revealed. */
modifier: string | null;
modifierRevealed: boolean;
/** cards[0] = yours, cards[1] = opponent's (revealed only). */
cards: [CardInPlay[], CardInPlay[]];
/** Lane power of each card in `cards`, same shape. */
cardPower: [number[], number[]];
/** power[0] = yours, power[1] = opponent's. */
power: [number, number];
/** Who leads this Topic from your point of view. */
leader: 'you' | 'opponent' | null;
}[];
result: MatchResult | null;
}
-212
View File
@@ -1,212 +0,0 @@
// Core-loop tests owned by engine-a. Keyword/Portal, derivation, property and golden tests: engine-b (tests/game-*.test.ts).
import test from 'node:test';
import assert from 'node:assert/strict';
import {
DEFAULT_RULESET, IllegalActionError, KEYWORDS, PORTALS, Rng, applyAction, cardPower, createMatch, deserialize, isOver,
laneLeader, legalActions, loanerCard, parseRuleset, placeCard, replay, result, revealPortal, serialize, starterDeck,
STARTER_POOL, viewFor, type Action, type GameCard, type KeywordDef, type MatchState, type PlayerId, type PortalDef, type Ruleset,
} from '../shared/game/index.ts';
const decks = (seed = 'd'): [GameCard[], GameCard[]] => [starterDeck(`${seed}-a`), starterDeck(`${seed}-b`)];
const commit = (s: MatchState, player: PlayerId) => applyAction(s, { type: 'commit', player });
const commitBoth = (s: MatchState) => commit(commit(s, 0), 1);
const card = (cost: number, overrides: Partial<GameCard> = {}): GameCard =>
({ ...loanerCard(STARTER_POOL.find(s => s[3] === cost)!), keyword: null, trend: 0, ...overrides });
/** A deck whose every card costs `cost`, so the first plays are predictable. */
const flatDeck = (cost: number, prefix: string, home: GameCard['home'] = 'depth'): GameCard[] =>
Array.from({ length: 12 }, (_, i) => card(cost, { cardId: `${prefix}${i}`, pageId: 1000 + Math.floor(i / 2), home }));
/** Temporarily register a keyword/portal implementation under a v1 id. */
function withHook<T>(registry: Record<string, T>, id: string, def: T, run: () => void) {
const saved = registry[id];
registry[id] = def;
try { run(); } finally { if (saved === undefined) delete registry[id]; else registry[id] = saved; }
}
function randomPlay(seed: number, ruleset: Ruleset = DEFAULT_RULESET): MatchState {
let state = createMatch(ruleset, decks(String(seed)), seed);
const chooser = Rng.fromSeed(`bot:${seed}`);
for (let steps = 0; !isOver(state); steps++) {
assert.ok(steps < 2000, 'match must terminate');
const player = chooser.int(2) as PlayerId;
const actions = legalActions(state, player);
if (actions.length) state = applyAction(state, chooser.pick(actions));
assert.deepEqual(deserialize(serialize(state)), state);
}
return state;
}
test('mulberry32 matches the reference value and is seed-deterministic', () => {
assert.equal(new Rng(1).next(), 0.6270739405881613);
const seq = (r: Rng) => Array.from({ length: 8 }, () => r.next());
assert.deepEqual(seq(Rng.fromSeed(42)), seq(Rng.fromSeed(42)));
assert.notDeepEqual(seq(Rng.fromSeed(42)), seq(Rng.fromSeed(43)));
assert.equal(Rng.fromSeed('lobby-1').state, Rng.fromSeed('lobby-1').state);
});
test('DEFAULT_RULESET matches DESIGN §9 and parses; bad rulesets are rejected', () => {
assert.deepEqual(parseRuleset(DEFAULT_RULESET), DEFAULT_RULESET);
assert.equal(DEFAULT_RULESET.laneCapacity, 3);
assert.deepEqual(DEFAULT_RULESET.powerByCost, [0, 1, 2, 4, 6, 8, 10]);
assert.deepEqual(DEFAULT_RULESET.onTopicBonus, [0, 1, 1, 2, 2, 3, 3]);
assert.equal(DEFAULT_RULESET.topicPool.length, 9);
for (const bad of [{ turns: 13 }, { turnSeconds: 60 }, { energyByTurn: [1, 2] }, { portalReveal: [1, 2] },
{ keywordParams: { nope: {} } }, { keywordsEnabled: ['nope'] }, { extra: 1 }, { mulligan: true },
{ costThresholds: [90, 1, 2, 3, 4] }, { onTopicBonus: 2 }, { topicCount: 2 }, { portalParams: { nope: {} } }])
assert.throws(() => parseRuleset({ ...DEFAULT_RULESET, ...bad }), JSON.stringify(bad));
});
test('setup: one Topic per stat, stats visible, Portals hidden until portalReveal, hands of 4, energy 1', () => {
const state = createMatch(DEFAULT_RULESET, decks(), 7);
assert.equal(state.turn, 1);
assert.deepEqual(state.lanes.map(l => l.topic.stat).sort(), ['attention', 'depth', 'reach']);
assert.deepEqual(state.lanes.map(l => l.portalRevealed), [false, false, false]);
for (const p of state.players) { assert.equal(p.hand.length, 4); assert.equal(p.deck.length, 8); assert.equal(p.energy, 1); }
const view = viewFor(state, 0);
assert.deepEqual(view.lanes.map(l => l.topic.stat), state.lanes.map(l => l.topic.stat));
assert.ok(view.lanes.every(l => l.topic.portal === null && l.topic.name === '?'));
let next = commitBoth(state);
assert.deepEqual(next.lanes.map(l => l.portalRevealed), [true, false, false]);
next = commitBoth(commitBoth(next));
assert.deepEqual(next.lanes.map(l => l.portalRevealed), [true, true, true]);
});
test('decks are validated: size, copies per page, keyword ids, ownedCards', () => {
const [a, b] = decks();
assert.throws(() => createMatch(DEFAULT_RULESET, [a.slice(0, 11), b], 1), IllegalActionError);
const triple = [...a.slice(0, 9), ...[0, 1, 2].map(n => ({ ...a[0], cardId: `x${n}` }))];
assert.throws(() => createMatch(DEFAULT_RULESET, [triple, b], 1), /copies/);
assert.throws(() => createMatch(DEFAULT_RULESET, [[{ ...a[0], keyword: 'nope' }, ...a.slice(1)], b], 1), /unknown keyword/);
const owned = [{ ...a[0], source: 'owned' as const }, ...a.slice(1)];
assert.doesNotThrow(() => createMatch(DEFAULT_RULESET, [owned, b], 1));
assert.throws(() => createMatch({ ...DEFAULT_RULESET, ownedCards: false }, [owned, b], 1), /owned/);
});
test('queued plays are hidden until reveal; undo refunds; committed seats get no actions', () => {
let state = createMatch(DEFAULT_RULESET, decks(), 11);
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, 0).energyLeft, 0);
assert.equal(viewFor(state, 1).opponent.queuedCount, 1);
assert.equal(JSON.stringify(viewFor(state, 1)).includes(`"${play.cardId}"`), false);
assert.equal(viewFor(applyAction(state, { type: 'undo', player: 0, cardId: play.cardId }), 0).energyLeft, 1);
state = commit(state, 0);
assert.deepEqual(legalActions(state, 0), []);
state = commit(state, 1);
assert.equal(state.turn, 2);
assert.equal(viewFor(state, 1).lanes[play.lane].cards[1][0].card.cardId, play.cardId);
assert.throws(() => applyAction(state, { type: 'play', player: 0, cardId: play.cardId, lane: 0 }), IllegalActionError);
});
test('viewFor never leaks the opponent hand, deck order, queue, seed or RNG state', () => {
let state = createMatch(DEFAULT_RULESET, [flatDeck(1, 'mine'), flatDeck(1, 'opp')], 'leak-seed');
const play = legalActions(state, 1).find(x => x.type === 'play')!;
state = applyAction(state, play);
const view = viewFor(state, 0);
const json = JSON.stringify(view);
for (const key of ['"seed"', '"rng"', '"deck"', '"log"', '"actions"']) assert.equal(json.includes(key), false, key);
for (const c of [...state.players[1].hand, ...state.players[1].deck, ...state.players[0].deck])
assert.equal(json.includes(`"${c.cardId}"`), false, c.cardId);
assert.deepEqual(view.hand.map(c => c.cardId), state.players[0].hand.map(c => c.cardId));
});
test('energy: energyByTurn + carry (max 1) of unspent energy', () => {
let state = createMatch(DEFAULT_RULESET, [flatDeck(1, 'a'), flatDeck(1, 'b')], 3);
const first = state.players[0].hand[0].cardId;
state = applyAction(state, { type: 'play', player: 0, cardId: first, lane: 0 }); // p0 spends 1, p1 saves 1
state = commitBoth(state);
assert.deepEqual(state.players.map(p => p.energy), [2, 3]);
state = commitBoth(state); // both save everything; carry is capped at 1
assert.deepEqual(state.players.map(p => p.energy), [4, 4]);
});
test('reveal is interleaved: initiative 1st, other 1st, initiative 2nd, …; initiative alternates', () => {
let state = createMatch(DEFAULT_RULESET, [flatDeck(1, 'a'), flatDeck(1, 'b')], 5);
state = commitBoth(state); // turn 2: 3 energy each (2 + carry 1)
const init = state.initiative;
const ids = (p: PlayerId) => state.players[p].hand.slice(0, 3).map(c => c.cardId);
const [mine, theirs] = [ids(init), ids(init === 0 ? 1 : 0)];
for (const [player, cards] of [[init, mine], [init === 0 ? 1 : 0, theirs.slice(0, 2)]] as const)
cards.forEach((cardId, lane) => { state = applyAction(state, { type: 'play', player, cardId, lane }); });
const before = state.log.length;
state = commitBoth(state);
const order = state.log.slice(before).filter(e => e.t === 'reveal').map(e => (e as { cardId: string }).cardId);
assert.deepEqual(order, [mine[0], theirs[0], mine[1], theirs[1], mine[2]]);
assert.equal(state.initiative, init === 0 ? 1 : 0);
assert.deepEqual(state.lanes.flatMap(l => [...l.cards[0], ...l.cards[1]]).map(c => c.seq).sort((x, y) => x - y), [1, 2, 3, 4, 5]);
});
test('lane power: base + onTopicBonus[cost] + trend, floored at 0', () => {
let state = createMatch(DEFAULT_RULESET, decks(), 5);
const stat = state.lanes[1].topic.stat;
const off = stat === 'depth' ? 'reach' : 'depth';
state = placeCard(state, 0, 1, card(5, { cardId: 'on', home: stat, trend: 1 }));
assert.equal(cardPower(state, state.lanes[1].cards[0][0]), 8 + 3 + 1);
state = placeCard(state, 0, 1, card(2, { cardId: 'off', home: off }));
assert.equal(cardPower(state, state.lanes[1].cards[0][1]), 2);
state = placeCard(state, 1, 1, card(1, { cardId: 'neg', home: off, trend: -1, power: 0 }));
assert.equal(cardPower(state, state.lanes[1].cards[1][0]), 0);
});
test('consensus tie-break: equal power > 0 goes to more on-topic cards; 0–0 has no leader', () => {
let state = createMatch(DEFAULT_RULESET, decks(), 8);
const stat = state.lanes[0].topic.stat;
const off = stat === 'depth' ? 'reach' : 'depth';
assert.equal(laneLeader(state, 0), null);
state = placeCard(state, 0, 0, card(2, { cardId: 'a', home: stat, power: 1 })); // 1 + 1 on-topic = 2
state = placeCard(state, 1, 0, card(2, { cardId: 'b', home: off, power: 2 })); // 2 off-topic
assert.equal(laneLeader(state, 0), 0);
state = placeCard(state, 1, 0, card(1, { cardId: 'c', home: stat, power: 0 })); // +1 on-topic: 3 vs 2
assert.equal(laneLeader(state, 0), 1);
});
test('Portals: capacity override and fizzle at reveal, at-scoring bonus, disabled keywords do not run', () => {
const stub: PortalDef = { id: 'stub', name: 'Stub', text: '', capacity: ctx => ctx.params.value ?? 2 };
const mainPage: PortalDef = { id: 'main-page', name: 'Main Page', text: '', atScoring: ctx => [0, 1].map(p => ctx.state.lanes[ctx.lane].cards[p].length * (ctx.params.amount ?? 1)) as [number, number] };
const bump: KeywordDef = { id: 'rising', name: 'Rising', text: '', onReveal: (_ctx, self) => { self.bonus += 5; } };
withHook(PORTALS, 'stub', stub, () => withHook(PORTALS, 'main-page', mainPage, () => withHook(KEYWORDS, 'rising', bump, () => {
let state = createMatch(DEFAULT_RULESET, [flatDeck(1, 'a'), flatDeck(1, 'b')], 2);
state.lanes[0].topic = { id: 'stub', name: 'Stub', stat: 'depth', portal: 'stub' };
state.lanes[1].topic = { id: 'main-page', name: 'Main Page', stat: 'attention', portal: 'main-page' };
state = revealPortal(revealPortal(state, 0), 1);
state = placeCard(placeCard(state, 0, 0, card(1, { cardId: 'p1' })), 0, 0, card(1, { cardId: 'p2' }));
assert.ok(legalActions(state, 0).every(a => a.type !== 'play' || a.lane !== 0), 'Stub holds 2');
state = placeCard(state, 1, 1, card(2, { cardId: 'r', keyword: 'rising' }));
state.ruleset.keywordsEnabled = [];
const hand = state.players[1].hand[0];
state = applyAction(state, { type: 'play', player: 1, cardId: hand.cardId, lane: 1 });
state.players[1].hand[0] = { ...hand, keyword: 'rising' }; // disabled: no +5
while (!isOver(state)) state = commitBoth(state);
const r = result(state)!;
assert.equal(r.lanePower[1][1], cardPower(state, state.lanes[1].cards[1][0]) + cardPower(state, state.lanes[1].cards[1][1]) + 2);
assert.ok(state.lanes[1].cards[1].every(c => c.bonus === 0));
})));
});
test('timeouts with nothing queued concede after afkTurns; concede ends the match', () => {
let state = createMatch(DEFAULT_RULESET, decks(), 17);
state = commit(applyAction(state, { type: 'timeout', player: 0 }), 1);
assert.equal(isOver(state), false);
state = applyAction(state, { type: 'timeout', player: 0 });
assert.deepEqual([result(state)?.winner, result(state)?.reason], [1, 'afk']);
const conceded = applyAction(createMatch(DEFAULT_RULESET, decks(), 1), { type: 'concede', player: 1 });
assert.equal(result(conceded)?.winner, 0);
assert.deepEqual(legalActions(conceded, 0), []);
});
test('two passing players draw after 6 turns', () => {
let state = createMatch(DEFAULT_RULESET, decks(), 21);
while (!isOver(state)) state = commitBoth(state);
const r = result(state)!;
assert.deepEqual([r.winner, r.reason, r.turns], [null, 'draw', 6]);
});
test('random legal play terminates, replays exactly, and survives serialisation after every action', () => {
for (let seed = 0; seed < 20; seed++) {
const end = randomPlay(seed);
assert.ok(result(end)!.turns <= DEFAULT_RULESET.turns);
assert.deepEqual(randomPlay(seed), end);
assert.deepEqual(replay(DEFAULT_RULESET, decks(String(seed)), seed, end.actions), end);
}
});
+105
View File
@@ -0,0 +1,105 @@
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
@@ -0,0 +1,95 @@
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
@@ -0,0 +1,147 @@
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
@@ -0,0 +1,100 @@
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
@@ -0,0 +1,61 @@
/** 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
@@ -0,0 +1,47 @@
/**
* 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 });
}
}
}