Peer-hosted game modes: mode schema, node API, host credit, three example modes

Modes are inert JSON (shared/game/modes.ts): rule overrides on the engine's
DEFAULT_RULESET, re-validated by parseRuleset; card-mapping presets from a
fixed list; deck policy and limits. server/game/ publishes this node's modes,
discovers configured peers' modes as data (byte cap, timeout, pinned origin),
and hosts lobbies, snake drafts and matches with the deterministic engine.
Finished matches are off-chain JSONL records with seed, decks and action log
(replayable). Per-mode and host leaderboards. Docs in docs/game/HOSTING.md,
including security notes and an on-chain host-reward proposal.

One mount line in server/testnet/http.ts; no consensus changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-16 23:00:17 -05:00
co-authored by Claude Opus 5.5
parent 7c86ed35f5
commit 7fef46e38e
19 changed files with 1797 additions and 0 deletions
+224
View File
@@ -0,0 +1,224 @@
# Hosting WikiDeck game modes
Anyone running a WikiDeck node can host their own **game modes**: their own twist on the
rules, played with WikiDeck cards on their node, with visible credit for hosting them.
Hosting a popular mode is the night-1 incentive to run a peer.
- Schema and validator: `shared/game/modes.ts`
- Node API: `server/game/` (mounted at `/api/game` by `server/testnet/http.ts`)
- Example modes: `server/game/modes/*.json` (shipped in the node image)
- Tests: `tests/modes-*.test.ts`
Everything here is **off-chain**. Hosting a mode never touches blocks, transfers, trades,
validation or NFT ownership. A match never moves or burns a card.
## 1. Modes are data, never code
A mode is a JSON document, at most 8 KiB:
```json
{
"schema": "wikideck.mode/1",
"id": "trending",
"version": 1,
"name": "Trending",
"description": "Live Wikipedia pageview trends power cards up or down.",
"tags": ["live-data"],
"rules": { "maxTurns": 6, "energy": { "max": 7 } },
"cards": { "preset": "trending", "percentPerPoint": 25, "maxBonus": 3, "penalise": true },
"decks": { "kind": "starter" },
"limits": { "maxConcurrentMatches": 32, "turnSeconds": 90, "lobbyMinutes": 15 }
}
```
| Field | Meaning |
|---|---|
| `id`, `version` | Lowercase slug and a version integer. Bump `version` whenever the rules change, so old match records and leaderboards stay attributable (`<origin>#<id>@<version>`). |
| `name`, `description`, `tags` | Plain text only: no control characters or `<` `>`. |
| `rules` | **Overrides** on top of the engine's `DEFAULT_RULESET` (see `docs/game/ENGINE_API.md`). Objects merge one level deep; arrays and numbers replace. The merged result then goes through the engine's strict `parseRuleset`, so the engine alone decides what's legal (bounded turns, lanes, deck sizes, known keywords and lane modifiers only). |
| `cards` | A card-mapping **preset** from a fixed list: `standard` (the at-mint snapshot), `live` (current stats) or `trending` (standard power ± a bounded bonus from the live 6-month pageview trend). The mode only picks a preset and tunes its bounded numbers. |
| `decks` | `starter` (everyone gets a seeded starter deck), `draft` (snake draft from a host-seeded pool of preview cards) or `constructed` (bring your own; see "Not yet" below). |
| `limits` | Concurrency, turn timer and lobby expiry for this mode on this host. |
The schema is strict: unknown fields are rejected, as are prototype keys
(`__proto__`, `constructor`, `prototype`) anywhere in the document, nesting deeper than two
levels inside `rules`, more than 48 rule keys, and oversized strings and arrays. A peer
**never** evaluates, imports or runs anything another peer sends. Nothing in a mode can name
a file, a URL, a script or a function.
## 2. Running your own modes
Configure modes with environment variables on your node:
| Variable | Default | Meaning |
|---|---|---|
| `WIKIDECK_MODES` | `classic` | Comma list of built-in ids (`classic`, `trending`, `draft`) and/or paths to `.json` files. `none` hosts nothing (the node still lists its peers' modes). |
| `WIKIDECK_MODES_DIR` | unset | A directory: every `*.json` in it is loaded as a mode. |
| `WIKIDECK_GAME_OPERATOR` | your origin's host | The name shown as **"Hosted by …"**. |
| `WIKIDECK_GAME_NOTE` | unset | A short note shown next to your name, e.g. "EU, best effort". |
| `WIKIDECK_GAME_PEERS` | `WIKIDECK_PEERS` | Peer origins whose modes to list. Use the peers' **public** origins, because players open the peer's own site to play there. |
| `PUBLIC_ORIGIN` | `http://127.0.0.1:$PORT` | Your node's identity as a host. |
At most 16 modes per node. A bad mode file stops the node at startup with a readable error,
because rules are validated once with the engine's parser when the node starts.
Example for the night-1 testnet (three nodes, different modes):
```yaml
# node-a: the base rules plus Trending
WIKIDECK_MODES: classic,trending
WIKIDECK_GAME_OPERATOR: Testnet A
WIKIDECK_GAME_PEERS: http://192.168.1.32:3102,http://192.168.1.32:3103
# node-b: the draft
WIKIDECK_MODES: draft
WIKIDECK_GAME_OPERATOR: Testnet B
# node-c: everything, including a custom file
WIKIDECK_MODES: classic,trending,draft,/app/data/modes/blitz.json
```
### Writing a new mode
Start from `server/game/modes/classic.json`, change `id`, `name` and `description`, then
override rules. Some ideas within tonight's rules:
- **Blitz:** `"rules": { "maxTurns": 4, "energy": { "start": 3, "perTurn": 1, "max": 6 } }`
- **Wide board:** `"rules": { "lanes": 4, "laneModifiers": { "pool": ["plain","portal","narrow","plain"], "revealTurns": [1,2,3,4] } }`
- **Big decks:** `"rules": { "deck": { "min": 16, "max": 16, "maxCopiesPerPage": 2 } }`
Check that a mode parses with `npm test` (the built-in modes are tested), or load it on a
local node: it fails at startup if the engine rejects it.
## 3. The node API
Everything is under `/api/game`, behind the node's existing `/api` admission budget and
global rate limit, plus stricter per-route limits.
| Method | Path | What it does |
|---|---|---|
| GET | `/modes` | **Publish:** this node's host identity, total matches hosted, and each mode with live stats (players online, open lobbies, live matches, matches played, distinct players). |
| GET | `/network/modes` | **Discover:** this node's list plus each configured peer's list, fetched as data. |
| GET | `/hosts/leaderboard` | Hosts ranked by matches hosted (this node plus peers). |
| GET | `/modes/:id/leaderboard` | Per-mode player leaderboard (wins, losses, draws). |
| GET | `/modes/:id/lobbies` | Open lobbies waiting for an opponent. |
| POST | `/modes/:id/lobbies` | Create a lobby: `{ name, secret }` → `{ lobbyId, seat: 0, token }`. |
| POST | `/lobbies/:lobby/join` | Join: `{ name, secret }` → `{ lobbyId, seat: 1, token }`. The match (or draft) starts. |
| GET | `/lobbies/:lobby` | Status. With `Authorization: Bearer <token>`: your `PlayerView` and your `legalActions`. |
| POST | `/lobbies/:lobby/pick` | Draft pick: `{ index }`. |
| POST | `/lobbies/:lobby/actions` | Play: `{ action }`, which must equal one of your `legalActions`. |
| POST | `/lobbies/:lobby/resign` | Resign (or cancel a waiting lobby). |
| GET | `/matches/:matchId` | A finished match record: seed, both decks, the full action log and the result. |
**Players.** The browser generates a random `secret` once and keeps it in local storage. The
host only ever stores and shows `sha256("wikideck-player:" + secret)` as the player id, so a
leaderboard name can't be claimed by someone else who uses the same display name. Each seat
also gets a fresh bearer token per lobby; only its hash is kept. When eom.dev accounts land
(#7), the player id can come from the account instead.
**Playing on a peer's mode.** The browser's CSP keeps API calls same-origin, so the lobby
shows peer modes with "Hosted by …" and links to the peer's own site to play there. No node
proxies another node's matches.
## 4. Credit for hosts
Every mode shows **"Hosted by &lt;operator&gt;"** (with the node's origin), its player counts,
its own leaderboard, and the node's total matches hosted. `/hosts/leaderboard` ranks nodes by
matches hosted.
Tonight these numbers are **informational**: each node reports its own counts. See section 6
for how they could become rewards without trusting the host's word.
## 5. Security notes
### Limits
| Limit | Value |
|---|---|
| Mode document | 8 KiB; 48 rule keys; rule nesting depth 2; strings ≤ 64 chars inside rules |
| Modes per node / per peer response | 16 |
| Peer `/api/game/modes` response | 192 KiB, read with a streaming byte cap; 3 s timeout; no redirects; cached 30 s; at most one refresh in flight |
| Peers | at most 16, operator-configured origins only (HTTPS, or HTTP with `WIKIDECK_ALLOW_PRIVATE_PEERS=1`) |
| Lobbies + matches in memory | 512 per node; `maxConcurrentMatches` per mode; 3 per player |
| Match length | engine bounds (`maxTurns` ≤ 12) plus a hard 2,000-action cap |
| Rate limits per IP | 240/min reads and plays, 60/min lobby create/join/resign, 30/min peer-discovery routes (on top of the node-wide 300/min `/api` limit and the RPC admission budget) |
| Request body | the node's 68 KB JSON limit |
| Wikipedia lookups (`trending`) | background only: one page per 3 s, at most 256 queued, never per request |
### Cheating
- **The client is never trusted.** Each action must deep-equal one of the engine's
`legalActions` for the token's seat, so you can't act for the other seat, play cards you
don't hold, overspend energy or act after the match ends.
- **Hidden information stays on the host.** Each seat only ever receives `viewFor(state, seat)`;
the opponent's hand and staged plays never leave the server. Spectators see status only.
- **Seeds are the host's.** The match seed is 128 random bits chosen by the host when the lobby
opens, so players can't grind for a favourable shuffle.
- **Stalling** forfeits: whoever still owes an action after `turnSeconds` loses; if both do, the
match ends as a draw. A stalled draft pick is made automatically.
- **Sybils and win-trading:** anyone can make a new player id, and two ids controlled by the same
person can feed each other wins. Tonight's leaderboards are for fun. Accounts (#7) or
wallet-signed identities would raise the cost.
- **Card stats.** Card numbers come from the engine's card mapping. Minted stats are self-reported
by the minter (see council-critic in #3); a mode can only pick a mapping preset, not supply numbers.
### What a malicious host can and can't do
A host runs its own matches, so it is **trusted for the matches it hosts**, and only those.
A malicious host **can**:
- lie about its stats, its matches hosted and its leaderboards;
- rig its own matches: pick seeds, peek at hands, or ignore the rules;
- drop or stall your match, or record a false result.
A malicious host **can't**:
- touch your cards: matches are off-chain, and the host never receives a key or signature;
- run code on other nodes: its modes are inert data, validated with hard limits;
- make other nodes fetch anything except its own `/api/game/modes`, or make them fetch it
in a way that slows them down (byte cap, timeout, cache, single flight);
- publish modes under another node's origin: discovery pins the origin it actually fetched;
- see your player secret: it only receives it once, over its own origin, and stores the hash.
**Use a different secret per host** if you don't trust a host (the UI can derive one per origin).
**Audit trail.** Every finished match record publishes the seed, both decks and the full action
log, so anyone can re-run it with the engine's `replay(ruleset, decks, seed, actions)` and check
the result. A host that lies about a result can be caught; a host that peeked at hands can't.
## 6. Proposal: on-chain host rewards (not tonight)
Rewarding hosts on-chain is a **protocol change**, so it's out of scope for night 1. This is a
proposal for later, to be reviewed like any consensus change.
**Goal:** pay hosts for matches real players actually played, without trusting the host's count.
1. **Signed match results.** Both players sign the final result
(`matchId`, `<origin>#<id>@<version>`, seed hash, action-log hash, winner) with their wallet
keys. The host signs too. A result needs all three signatures, so a host can't invent matches
or results alone, and players can't deny a match they played.
2. **Replayable evidence.** The record keeps the seed, decks and action log. Anyone can replay it
with the pinned engine version to check the result. Disputes are settled by replay, not by vote.
3. **Batched claims.** Once per epoch, a host submits one transaction committing a Merkle root of
its signed results. A new `hostClaim` transaction type would carry the root and a count. This is
the protocol change: a new transaction type, its validation and its reward rule.
4. **Rewards that resist farming.** A host's reward per epoch grows with the number of **distinct
paired wallets** (not matches), each wallet counts toward at most one host per epoch, wallets
must hold at least one minted card older than N blocks, and the total is a small, capped
share of block rewards. That makes sybil farms cost real mining work.
5. **Challenges.** For a window after a claim, anyone can post a replay that contradicts a
committed result, or proof that a wallet was double-counted. A successful challenge voids
the host's claim for that epoch.
Open questions: who pays (a share of block rewards versus a fee from players), how to stop
colluding players and hosts from farming one another, and whether the engine version must
be pinned in consensus.
## Not yet
- `constructed` decks of **owned NFTs**: the policy exists, but tonight the host deals
starter decks for it. Playing with your own cards needs a wallet-signed ownership proof
for the lobby (and then the engine's `cardFromStats`). That's a follow-up once accounts and
wallet linking (#7) settle.
- The `live` preset is accepted, but tonight it behaves like `standard`.
- `trending` never calls Wikipedia when a match starts. The node warms a cache-only trend
store in the background, one page every 3 s, through its existing enrichment cache (6 h TTL),
starting with the preview-card pages. A card whose page isn't warm yet gets no bonus. This
keeps load on the shared, rate-limited Wikipedia egress tiny: about 24 pages per 6 hours per node.
- Spectating and rematches.
+55
View File
@@ -0,0 +1,55 @@
/**
* Operator configuration for hosted modes. Everything comes from the operator's own
* environment and files; nothing here is learned from peers.
*
* WIKIDECK_MODES comma list of built-in mode ids and/or JSON file paths
* (default "classic"; "none" hosts nothing but still discovers)
* WIKIDECK_MODES_DIR optional directory: every *.json in it is a mode
* WIKIDECK_GAME_OPERATOR name shown as "Hosted by ..." (default: the origin's host name)
* WIKIDECK_GAME_NOTE optional short note shown with the host
* WIKIDECK_GAME_PEERS peer origins whose modes to list (default: WIKIDECK_PEERS)
* PUBLIC_ORIGIN this node's public origin (the host identity)
*/
import { readFileSync, readdirSync } from 'node:fs';
import { join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import { HostIdentitySchema, MAX_MODES_PER_NODE, parseModeJson, type HostIdentity, type ModeDocument } from '../../shared/game/modes.ts';
import { parsePeerOrigins } from './discovery.ts';
export const BUILTIN_MODES_DIR = fileURLToPath(new URL('./modes/', import.meta.url));
export const BUILTIN_MODE_IDS = ['classic', 'trending', 'draft'] as const;
export function loadModes(env: NodeJS.ProcessEnv = process.env): ModeDocument[] {
const modes: ModeDocument[] = [];
const spec = (env.WIKIDECK_MODES ?? 'classic').trim();
if (spec !== 'none') for (const item of spec.split(',').map(s => s.trim()).filter(Boolean)) {
if ((BUILTIN_MODE_IDS as readonly string[]).includes(item)) modes.push(readMode(join(BUILTIN_MODES_DIR, `${item}.json`)));
else if (item.endsWith('.json')) modes.push(readMode(resolve(item)));
else throw new Error(`WIKIDECK_MODES: unknown built-in mode "${item.slice(0, 40)}" (use ${BUILTIN_MODE_IDS.join(', ')} or a .json path)`);
}
if (env.WIKIDECK_MODES_DIR) {
const dir = resolve(env.WIKIDECK_MODES_DIR);
for (const f of readdirSync(dir).filter(f => f.endsWith('.json')).sort()) modes.push(readMode(join(dir, f)));
}
if (modes.length > MAX_MODES_PER_NODE) throw new Error(`At most ${MAX_MODES_PER_NODE} modes per node`);
const ids = new Set<string>();
for (const m of modes) { if (ids.has(m.id)) throw new Error(`Duplicate mode id ${m.id}`); ids.add(m.id); }
return modes;
}
function readMode(path: string): ModeDocument {
try { return parseModeJson(readFileSync(path, 'utf8')); }
catch (e) { throw new Error(`Invalid mode file ${path}: ${(e as Error).message.slice(0, 300)}`); }
}
export function hostIdentity(env: NodeJS.ProcessEnv = process.env): HostIdentity {
const origin = new URL(env.PUBLIC_ORIGIN ?? `http://127.0.0.1:${env.PORT ?? 3001}`).origin;
return HostIdentitySchema.parse({ origin, operator: (env.WIKIDECK_GAME_OPERATOR ?? new URL(origin).host).slice(0, 48),
...(env.WIKIDECK_GAME_NOTE ? { note: env.WIKIDECK_GAME_NOTE.slice(0, 120) } : {}) });
}
export function gamePeers(env: NodeJS.ProcessEnv = process.env): string[] {
const self = hostIdentity(env).origin;
return parsePeerOrigins(env.WIKIDECK_GAME_PEERS ?? env.WIKIDECK_PEERS, env.WIKIDECK_ALLOW_PRIVATE_PEERS === '1')
.filter(o => o !== self);
}
+93
View File
@@ -0,0 +1,93 @@
/**
* Discover the modes of explicitly configured peers. No discovery service, no gossip:
* the operator lists peer origins (WIKIDECK_GAME_PEERS, else WIKIDECK_PEERS). Each peer's
* GET /api/game/modes is fetched with a timeout, a byte cap and no redirects, then parsed
* strictly as data. The fetched origin replaces whatever origin the peer claims.
*/
import { parseModeList, MAX_MODE_LIST_BYTES, type ModeList } from '../../shared/game/modes.ts';
export type PeerModes = { origin: string; ok: boolean; error?: string; fetchedAt: number; rejected?: number; list?: ModeList };
export type Fetcher = (url: string, init: { signal: AbortSignal; redirect: 'error'; headers: Record<string, string> }) => Promise<Response>;
export function parsePeerOrigins(raw: string | undefined, allowPrivate: boolean): string[] {
const out = new Set<string>();
for (const text of (raw ?? '').split(',').map(s => s.trim()).filter(Boolean)) {
if (text.length > 256 || !/^https?:\/\/[^/?#\\@\s]+\/?$/i.test(text)) throw new Error(`Invalid game peer origin: ${text.slice(0, 80)}`);
const url = new URL(text);
if (url.protocol !== 'https:' && !(allowPrivate && url.protocol === 'http:')) throw new Error('Game peers must be HTTPS (or HTTP with WIKIDECK_ALLOW_PRIVATE_PEERS=1)');
out.add(url.origin);
}
if (out.size > 16) throw new Error('At most 16 game peers');
return [...out];
}
export class ModeDiscovery {
private readonly peers: string[];
private readonly fetcher: Fetcher;
private readonly ttlMs: number;
private readonly timeoutMs: number;
private readonly cache = new Map<string, PeerModes>();
private inflight: Promise<PeerModes[]> | null = null;
private readonly now: () => number;
constructor(options: { peers: string[]; fetcher?: Fetcher; ttlMs?: number; timeoutMs?: number; now?: () => number }) {
this.peers = options.peers;
this.fetcher = options.fetcher ?? ((url, init) => fetch(url, init));
this.ttlMs = options.ttlMs ?? 30_000;
this.timeoutMs = options.timeoutMs ?? 3_000;
this.now = options.now ?? Date.now;
}
/** Cached peer results; refreshes stale entries at most once concurrently. */
async all(): Promise<PeerModes[]> {
const now = this.now();
const stale = this.peers.some(p => { const c = this.cache.get(p); return !c || now - c.fetchedAt > this.ttlMs; });
if (stale) {
this.inflight ??= Promise.all(this.peers.map(p => this.fetchPeer(p))).finally(() => { this.inflight = null; });
await this.inflight;
}
return this.peers.map(p => this.cache.get(p)!).filter(Boolean);
}
private async fetchPeer(origin: string): Promise<PeerModes> {
const fetchedAt = this.now();
let result: PeerModes;
try {
const signal = AbortSignal.timeout(this.timeoutMs);
const res = await this.fetcher(`${origin}/api/game/modes`, { signal, redirect: 'error', headers: { accept: 'application/json' } });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const body = await readCapped(res, MAX_MODE_LIST_BYTES);
const { list, rejected } = parseModeList(body);
// The peer may claim any operator name, but not any origin: we know where we fetched it.
result = { origin, ok: true, fetchedAt, rejected, list: { ...list, host: { ...list.host, origin } } };
} catch (e) {
const previous = this.cache.get(origin);
result = { origin, ok: false, error: describe(e), fetchedAt, ...(previous?.list ? { list: previous.list } : {}) };
}
this.cache.set(origin, result);
return result;
}
}
async function readCapped(res: Response, max: number): Promise<string> {
const declared = Number(res.headers.get('content-length') ?? 0);
if (declared > max) throw new Error('Mode list too large');
if (!res.body) return '';
const reader = res.body.getReader();
const chunks: Uint8Array[] = [];
let total = 0;
for (;;) {
const { done, value } = await reader.read();
if (done) break;
total += value.byteLength;
if (total > max) { await reader.cancel(); throw new Error('Mode list too large'); }
chunks.push(value);
}
return new TextDecoder().decode(Buffer.concat(chunks));
}
function describe(e: unknown): string {
const m = e instanceof Error ? e.message : String(e);
return (m.includes('too large') ? 'response too large' : m.includes('abort') || m.includes('timeout') ? 'timeout'
: /^HTTP \d+$/.test(m) ? m : e instanceof SyntaxError ? 'invalid JSON' : 'invalid or unreachable').slice(0, 80);
}
+45
View File
@@ -0,0 +1,45 @@
/** Binds the mode host to the real engine through its public API (shared/game/index.ts). */
import { DEFAULT_RULESET, parseRuleset, starterDeck, starterCard, STARTER_POOL, validateDeck, createMatch,
legalActions, applyAction, isOver, result, viewFor, Rng,
type Action, type GameCard, type MatchState, type Ruleset } from '../../shared/game/index.ts';
import type { EnginePort, Seat } from './engine-port.ts';
/**
* Deterministic pool of preview (non-NFT) cards for draft modes: seeded shuffles of the
* starter pool, one copy per round, never exceeding the ruleset's per-page copy limit.
*/
export function previewPool(rules: Ruleset, seed: string, size: number): GameCard[] {
const rng = Rng.fromSeed(`draft-pool:${seed}`);
const pool: GameCard[] = [];
for (let copy = 0; pool.length < size && copy < rules.deck.maxCopiesPerPage; copy++) {
for (const spec of rng.shuffle(STARTER_POOL)) { if (pool.length >= size) break; pool.push(starterCard(spec, copy)); }
}
return pool;
}
export const engineBinding: EnginePort<Ruleset, GameCard, MatchState, Action> = {
defaultRuleset: DEFAULT_RULESET,
parseRuleset,
deckSize: rules => rules.deck.min,
starterDeck: (rules, seed) => starterDeck(seed, rules),
previewPool,
validateDeck: (rules, cards) => {
const problems = validateDeck(rules, cards);
if (problems.length) throw new Error(problems.slice(0, 3).join('; '));
},
cardPower: card => card.power,
withPower: (card, power) => ({ ...card, power }),
cardPageId: card => card.pageId,
cardSummary: card => ({ id: card.id, name: card.name, pageId: card.pageId, category: card.category,
cost: card.cost, power: card.power, keyword: card.keyword }),
createMatch: (rules, decks, seed) => createMatch(rules, decks, seed),
legalActions: (state, seat) => legalActions(state, seat),
applyAction: (state, seat: Seat, action) => {
if (action.player !== seat) throw new Error('Action for the wrong seat');
return applyAction(state, action);
},
concedeAction: seat => ({ type: 'concede', player: seat }),
isOver,
result: state => { const r = result(state); return { winner: r?.winner ?? null, reason: r?.reason ?? 'complete' }; },
viewFor: (state, seat) => viewFor(state, seat),
};
+35
View File
@@ -0,0 +1,35 @@
/**
* The slice of the engine API (docs/game/ENGINE_API.md) the mode host uses.
* The host is engine-agnostic behind this port: the real binding lives in engine-binding.ts,
* tests use a tiny stub. Card and state values are opaque to the host.
*/
export type Seat = 0 | 1;
export type MatchOutcome = { winner: Seat | null; reason?: string };
export interface EnginePort<Rules = unknown, Card = unknown, State = unknown, Action = unknown> {
readonly defaultRuleset: Rules;
/** Strict engine-side validation of a merged ruleset. Throws on anything invalid. */
parseRuleset(value: unknown): Rules;
deckSize(rules: Rules): number;
starterDeck(rules: Rules, seed: string): Card[];
/** Deterministic pool of non-NFT preview cards, for draft modes. */
previewPool(rules: Rules, seed: string, size: number): Card[];
/** Throws if the deck is not legal under the rules. */
validateDeck(rules: Rules, cards: Card[]): void;
cardPower(card: Card): number;
withPower(card: Card, power: number): Card;
/** Wikipedia page id of a card, if it has one (for live/trending mappings). */
cardPageId(card: Card): number | null;
/** Public, JSON-safe summary shown in a draft pool. */
cardSummary(card: Card): unknown;
createMatch(rules: Rules, decks: [Card[], Card[]], seed: string): State;
legalActions(state: State, seat: Seat): Action[];
applyAction(state: State, seat: Seat, action: Action): State;
/** Optional engine-level concede, so a resignation is part of the replayable action log. */
concedeAction?(seat: Seat): Action;
isOver(state: State): boolean;
result(state: State): MatchOutcome;
/** What one seat may see (hides the opponent's hand and staged plays). */
viewFor(state: State, seat: Seat): unknown;
}
+332
View File
@@ -0,0 +1,332 @@
/**
* Hosts lobbies and matches for this node's modes, with the deterministic engine.
* All state is off-chain and in memory; finished matches go to the MatchStore.
*
* Trust model: the host is authoritative for its own matches. Players are identified by a
* client-held secret (only its SHA-256 is stored or shown) and act through per-seat bearer
* tokens. Every action must equal one of the engine's legalActions for that seat.
*/
import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
import { isDeepStrictEqual } from 'node:util';
import { modeKey, resolveRuleset, trendBonus, clampPower, MODE_SCHEMA_VERSION,
type HostIdentity, type ModeDocument, type ModeList, type ModeStats, type LiveCardData } from '../../shared/game/modes.ts';
import type { EnginePort, Seat } from './engine-port.ts';
import { MatchStore, type MatchRecord } from './store.ts';
export class GameError extends Error {
readonly status: number;
constructor(status: number, message: string) { super(message); this.status = status; }
}
type Player = { id: string; name: string; tokenHash: Buffer; seen: number };
type Phase = 'waiting' | 'drafting' | 'playing' | 'finished' | 'expired';
type Lobby = {
id: string; mode: ModeDocument; rules: unknown; seed: string; createdAt: number;
players: Player[]; phase: Phase;
draft?: { pool: unknown[]; taken: (Seat | null)[]; order: Seat[]; turn: number; deadline: number };
decks?: [unknown[], unknown[]];
state?: unknown; actions: { seat: Seat; action: unknown }[]; startedAt?: number; lastMove: number;
outcome?: { winner: Seat | null; reason: string }; matchId?: string;
};
type HostedMode = { mode: ModeDocument; rules: unknown };
export type HostOptions = {
identity: HostIdentity;
modes: ModeDocument[];
engine: EnginePort<any, any, any, any>;
store: MatchStore;
/** Optional live Wikipedia trend lookup for `trending` modes. Failures mean "no bonus". */
liveData?: (pageId: number) => Promise<LiveCardData | null>;
now?: () => number;
/** Node-wide cap on lobbies + matches in memory across all modes. */
maxLobbies?: number;
};
export type SeatTicket = { lobbyId: string; seat: Seat; token: string };
const NAME = /^[\p{L}\p{N} _.\-]{1,24}$/u;
const SECRET = /^[A-Za-z0-9_-]{22,128}$/;
const LOBBY_ID = /^[a-f0-9]{24}$/;
export class ModeHost {
readonly identity: HostIdentity;
private readonly engine: EnginePort<any, any, any, any>;
private readonly store: MatchStore;
private readonly hosted = new Map<string, HostedMode>();
private readonly lobbies = new Map<string, Lobby>();
private readonly liveData?: HostOptions['liveData'];
private readonly now: () => number;
private readonly maxLobbies: number;
constructor(options: HostOptions) {
this.identity = options.identity;
this.engine = options.engine;
this.store = options.store;
this.liveData = options.liveData;
this.now = options.now ?? Date.now;
this.maxLobbies = options.maxLobbies ?? 512;
for (const mode of options.modes) {
if (this.hosted.has(mode.id)) throw new Error(`Duplicate mode id ${mode.id}`);
// Validate rules once at startup with the engine's own parser: a bad mode fails loudly.
const rules = resolveRuleset(this.engine.defaultRuleset, mode.rules, v => this.engine.parseRuleset(v));
if (mode.decks.kind === 'draft' && mode.decks.poolSize < 2 * this.engine.deckSize(rules)) {
throw new Error(`Mode ${mode.id}: draft poolSize must be at least 2 × deck size`);
}
this.hosted.set(mode.id, { mode, rules });
}
}
/** Body of GET /api/game/modes. */
list(): ModeList {
return { schema: MODE_SCHEMA_VERSION, host: this.identity, matchesHosted: this.store.total,
modes: [...this.hosted.values()].map(h => ({ mode: h.mode, stats: this.stats(h.mode.id) })) };
}
stats(modeId: string): ModeStats {
let online = 0, open = 0, live = 0;
for (const l of this.lobbies.values()) {
if (l.mode.id !== modeId) continue;
if (l.phase === 'waiting') open++;
if (l.phase === 'drafting' || l.phase === 'playing') live++;
if (l.phase === 'waiting' || l.phase === 'drafting' || l.phase === 'playing') online += l.players.length;
}
return { playersOnline: online, openLobbies: open, liveMatches: live,
matchesPlayed: this.store.modeMatches(modeId), distinctPlayers: this.store.modePlayers(modeId) };
}
leaderboard(modeId: string) {
const h = this.mode(modeId);
return { host: this.identity, mode: { id: h.mode.id, version: h.mode.version, name: h.mode.name },
key: modeKey(this.identity.origin, h.mode), entries: this.store.leaderboard(modeId) };
}
openLobbies(modeId: string) {
this.mode(modeId);
return [...this.lobbies.values()].filter(l => l.mode.id === modeId && l.phase === 'waiting')
.slice(0, 50).map(l => ({ lobbyId: l.id, host: l.players[0]!.name, createdAt: l.createdAt }));
}
createLobby(modeId: string, player: { name: unknown; secret: unknown }): SeatTicket {
const h = this.mode(modeId);
this.sweep();
const active = [...this.lobbies.values()].filter(l => l.phase !== 'finished' && l.phase !== 'expired');
if (active.length >= this.maxLobbies) throw new GameError(503, 'This host is full; try again later.');
if (active.filter(l => l.mode.id === modeId).length >= h.mode.limits.maxConcurrentMatches) {
throw new GameError(503, 'This mode is at its match limit on this host; try again later.');
}
const p = this.player(player);
if (active.filter(l => l.players.some(x => x.id === p.player.id)).length >= 3) {
throw new GameError(429, 'Too many open lobbies or matches for this player.');
}
const id = randomBytes(12).toString('hex');
const now = this.now();
this.lobbies.set(id, { id, mode: h.mode, rules: h.rules, seed: randomBytes(16).toString('hex'), createdAt: now,
players: [p.player], phase: 'waiting', actions: [], lastMove: now });
return { lobbyId: id, seat: 0, token: p.token };
}
async join(lobbyId: string, player: { name: unknown; secret: unknown }): Promise<SeatTicket> {
const l = this.lobby(lobbyId);
this.sweep();
if (l.phase !== 'waiting') throw new GameError(409, 'This lobby is no longer open.');
const p = this.player(player);
if (l.players[0]!.id === p.player.id) throw new GameError(409, 'You cannot play against yourself.');
l.players.push(p.player);
l.lastMove = this.now();
if (l.mode.decks.kind === 'draft') this.startDraft(l);
else await this.startMatch(l, [this.engine.starterDeck(l.rules, `${l.seed}:0`), this.engine.starterDeck(l.rules, `${l.seed}:1`)]);
return { lobbyId: l.id, seat: 1, token: p.token };
}
/** Public status, plus the seat's private view when a valid token is given. */
view(lobbyId: string, token?: string) {
const l = this.lobby(lobbyId);
this.sweep();
const seat = token ? this.seatFor(l, token) : null;
const base = { lobbyId: l.id, phase: l.phase, host: this.identity,
mode: { id: l.mode.id, version: l.mode.version, name: l.mode.name },
players: l.players.map(p => ({ id: p.id, name: p.name })), seat, matchId: l.matchId ?? null,
outcome: l.outcome ?? null };
if (l.phase === 'drafting' && l.draft) {
const d = l.draft;
return { ...base, draft: { pool: d.pool.map((c, i) => ({ index: i, card: this.engine.cardSummary(c), takenBy: d.taken[i] })),
toPick: d.order[d.turn] ?? null, deadline: d.deadline } };
}
if ((l.phase === 'playing' || l.phase === 'finished') && l.state !== undefined && seat !== null) {
return { ...base, state: this.engine.viewFor(l.state, seat),
legalActions: l.phase === 'playing' ? this.engine.legalActions(l.state, seat) : [] };
}
return base;
}
async pick(lobbyId: string, token: string, index: unknown) {
const l = this.lobby(lobbyId);
const seat = this.requireSeat(l, token);
this.sweep();
if (l.phase !== 'drafting' || !l.draft) throw new GameError(409, 'Not drafting.');
if (l.draft.order[l.draft.turn] !== seat) throw new GameError(409, 'Not your pick.');
if (typeof index !== 'number' || !Number.isInteger(index) || index < 0 || index >= l.draft.pool.length ||
l.draft.taken[index] !== null) throw new GameError(400, 'Invalid pick.');
await this.takePick(l, seat, index);
return this.view(lobbyId, token);
}
async act(lobbyId: string, token: string, action: unknown) {
const l = this.lobby(lobbyId);
const seat = this.requireSeat(l, token);
this.sweep();
if (l.phase !== 'playing' || l.state === undefined) throw new GameError(409, 'No match in progress.');
// The host never trusts a client action: it must be one of the engine's legal actions.
const legal = this.engine.legalActions(l.state, seat);
const chosen = legal.find(a => isDeepStrictEqual(a, action));
if (chosen === undefined) throw new GameError(400, 'Illegal action.');
l.state = this.engine.applyAction(l.state, seat, chosen);
l.actions.push({ seat, action: chosen });
l.lastMove = this.now();
l.players[seat]!.seen = l.lastMove;
if (this.engine.isOver(l.state)) {
const r = this.engine.result(l.state);
this.finish(l, r.winner, r.reason ?? 'complete');
} else if (l.actions.length >= 2000) this.finish(l, null, 'action-limit');
return this.view(lobbyId, token);
}
resign(lobbyId: string, token: string) {
const l = this.lobby(lobbyId);
const seat = this.requireSeat(l, token);
if (l.phase === 'waiting') { l.phase = 'expired'; return this.view(lobbyId, token); }
if (l.phase !== 'playing' && l.phase !== 'drafting') throw new GameError(409, 'Nothing to resign.');
if (l.phase === 'playing' && l.state !== undefined && this.engine.concedeAction) {
const action = this.engine.concedeAction(seat);
l.state = this.engine.applyAction(l.state, seat, action);
l.actions.push({ seat, action });
if (this.engine.isOver(l.state)) { const r = this.engine.result(l.state); this.finish(l, r.winner, 'resign'); return this.view(lobbyId, token); }
}
this.finish(l, seat === 0 ? 1 : 0, 'resign');
return this.view(lobbyId, token);
}
matchRecord(matchId: string): MatchRecord {
if (!/^[a-f0-9]{32}$/.test(matchId)) throw new GameError(400, 'Invalid match id.');
const r = this.store.get(matchId);
if (!r) throw new GameError(404, 'Match not found on this host.');
return r;
}
/** Expire idle lobbies, auto-pick stalled drafts, forfeit stalled matches, drop old lobbies. */
sweep(): void {
const now = this.now();
for (const l of this.lobbies.values()) {
const turnMs = l.mode.limits.turnSeconds * 1000;
if (l.phase === 'waiting' && now - l.createdAt > l.mode.limits.lobbyMinutes * 60_000) l.phase = 'expired';
else if (l.phase === 'drafting' && l.draft && now > l.draft.deadline) {
// Auto-pick the first free card for whoever is stalling; synchronous, no live data.
const idx = l.draft.taken.indexOf(null);
if (idx >= 0) void this.takePick(l, l.draft.order[l.draft.turn]!, idx).catch(() => { l.phase = 'expired'; });
} else if (l.phase === 'playing' && l.state !== undefined && now - l.lastMove > turnMs) {
const waiting = ([0, 1] as Seat[]).filter(s => this.engine.legalActions(l.state, s).length > 0);
// Whoever still owes an action forfeits. If both do, it's a draw (abandoned).
if (waiting.length === 1) this.finish(l, waiting[0] === 0 ? 1 : 0, 'timeout');
else this.finish(l, null, 'abandoned');
}
if ((l.phase === 'finished' || l.phase === 'expired') && now - l.lastMove > 10 * 60_000) this.lobbies.delete(l.id);
}
}
private startDraft(l: Lobby) {
if (l.mode.decks.kind !== 'draft') return;
const size = this.engine.deckSize(l.rules);
const pool = this.engine.previewPool(l.rules, `${l.seed}:pool`, l.mode.decks.poolSize);
if (pool.length < 2 * size) throw new GameError(500, 'Engine returned a short draft pool.');
// Snake order 0,1,1,0,0,1,... with a seed-chosen first picker.
const first: Seat = parseInt(l.seed.slice(0, 2), 16) % 2 === 0 ? 0 : 1;
const order: Seat[] = [];
for (let i = 0; i < 2 * size; i++) order.push(((Math.floor((i + 1) / 2) % 2 === 0 ? first : 1 - first)) as Seat);
l.draft = { pool, taken: pool.map(() => null), order, turn: 0, deadline: this.now() + l.mode.decks.pickSeconds * 1000 };
l.phase = 'drafting';
}
private async takePick(l: Lobby, seat: Seat, index: number) {
const d = l.draft!;
d.taken[index] = seat;
d.turn++;
l.lastMove = this.now();
if (l.mode.decks.kind === 'draft') d.deadline = this.now() + l.mode.decks.pickSeconds * 1000;
if (d.turn >= d.order.length) {
const decks: [unknown[], unknown[]] = [[], []];
d.taken.forEach((s, i) => { if (s !== null) decks[s].push(d.pool[i]); });
await this.startMatch(l, decks);
}
}
private async startMatch(l: Lobby, decks: [unknown[], unknown[]]) {
const mapped = await Promise.all(decks.map(d => this.mapDeck(l.mode, d))) as [unknown[], unknown[]];
for (const d of mapped) {
try { this.engine.validateDeck(l.rules, d); }
catch (e) { l.phase = 'expired'; throw new GameError(400, `Deck rejected by the engine: ${(e as Error).message}`.slice(0, 200)); }
}
l.decks = mapped;
l.state = this.engine.createMatch(l.rules, mapped, l.seed);
l.phase = 'playing';
l.startedAt = l.lastMove = this.now();
delete l.draft;
if (this.engine.isOver(l.state)) { const r = this.engine.result(l.state); this.finish(l, r.winner, r.reason ?? 'complete'); }
}
/** Apply the mode's card-mapping preset. Bonus data is looked up once, before the match. */
private async mapDeck(mode: ModeDocument, deck: unknown[]): Promise<unknown[]> {
const mapping = mode.cards;
if (mapping.preset !== 'trending' || !this.liveData) return deck;
return Promise.all(deck.map(async card => {
const pageId = this.engine.cardPageId(card);
if (pageId === null) return card;
const live = await this.liveData!(pageId).catch(() => null);
const bonus = trendBonus(mapping, live?.trendPercent ?? null);
return bonus === 0 ? card : this.engine.withPower(card, clampPower(this.engine.cardPower(card) + bonus));
}));
}
private finish(l: Lobby, winner: Seat | null, reason: string) {
if (l.phase === 'finished' || l.phase === 'expired') return;
l.phase = 'finished';
l.outcome = { winner, reason };
l.lastMove = this.now();
if (!l.decks || l.players.length !== 2) return; // Resigned during draft: no match record.
const matchId = randomBytes(16).toString('hex');
l.matchId = matchId;
this.store.add({ matchId, modeId: l.mode.id, modeVersion: l.mode.version, seed: l.seed, rules: l.rules,
players: l.players.map(p => ({ id: p.id, name: p.name })), winner, reason: reason.slice(0, 40),
startedAt: l.startedAt ?? l.createdAt, endedAt: l.lastMove, decks: l.decks, actions: l.actions });
}
private mode(modeId: string): HostedMode {
const h = typeof modeId === 'string' ? this.hosted.get(modeId) : undefined;
if (!h) throw new GameError(404, 'Mode not hosted here.');
return h;
}
private lobby(lobbyId: string): Lobby {
const l = typeof lobbyId === 'string' && LOBBY_ID.test(lobbyId) ? this.lobbies.get(lobbyId) : undefined;
if (!l) throw new GameError(404, 'Lobby not found.');
return l;
}
private player(input: { name: unknown; secret: unknown }): { player: Player; token: string } {
const name = typeof input.name === 'string' ? input.name.trim() : '';
if (!NAME.test(name)) throw new GameError(400, 'Name must be 1-24 letters, digits, spaces, _ . or -');
if (typeof input.secret !== 'string' || !SECRET.test(input.secret)) throw new GameError(400, 'Invalid player secret.');
const id = createHash('sha256').update(`wikideck-player:${input.secret}`).digest('hex');
const token = randomBytes(24).toString('base64url');
return { player: { id, name, tokenHash: hashToken(token), seen: this.now() }, token };
}
private seatFor(l: Lobby, token: string): Seat | null {
const h = hashToken(token);
const i = l.players.findIndex(p => timingSafeEqual(p.tokenHash, h));
return i === 0 || i === 1 ? i : null;
}
private requireSeat(l: Lobby, token: string): Seat {
const s = typeof token === 'string' ? this.seatFor(l, token) : null;
if (s === null) throw new GameError(403, 'Not a player in this lobby.');
return s;
}
}
function hashToken(token: string): Buffer { return createHash('sha256').update(token).digest(); }
+42
View File
@@ -0,0 +1,42 @@
/**
* Entry point for the game-modes API. server/testnet/http.ts mounts it with one line:
* app.use('/api/game', await (await import('../game/index.ts')).gameRouter({ dataDir, enrichment: wikipediaEnrichment }));
*/
import { join } from 'node:path';
import type express from 'express';
import { loadModes, hostIdentity, gamePeers } from './config.ts';
import { ModeDiscovery } from './discovery.ts';
import { ModeHost } from './host.ts';
import { createGameRouter } from './router.ts';
import { MatchStore } from './store.ts';
import type { EnginePort } from './engine-port.ts';
import { TrendCache } from './trends.ts';
type Enrichment = { get(pageId: number): Promise<{ pageviews: { trendPercent: number | null } }> };
export async function gameRouter(options: { dataDir: string | null; enrichment?: Enrichment;
engine?: EnginePort<any, any, any, any>; env?: NodeJS.ProcessEnv; warmTrends?: boolean }): Promise<express.Router> {
const env = options.env ?? process.env;
const engine = options.engine ?? (await import('./engine-binding.ts')).engineBinding;
const modes = loadModes(env);
// Trends come from a slowly warmed, cache-only store: never a Wikipedia call per match.
let trends: TrendCache | undefined;
if (options.enrichment && modes.some(m => m.cards.preset === 'trending')) {
const enrichment = options.enrichment;
trends = new TrendCache(pageId => enrichment.get(pageId));
for (const card of engine.starterDeck(engine.defaultRuleset, 'trend-warmup')) {
const id = engine.cardPageId(card); if (id !== null) trends.enqueue(id);
}
for (const card of engine.previewPool(engine.defaultRuleset, 'trend-warmup', 64)) {
const id = engine.cardPageId(card); if (id !== null) trends.enqueue(id);
}
if (options.warmTrends !== false) trends.start();
}
const host = new ModeHost({ identity: hostIdentity(env), modes, engine,
store: new MatchStore(options.dataDir ? join(options.dataDir, 'game') : null),
liveData: trends ? async pageId => trends!.get(pageId) : undefined });
const discovery = new ModeDiscovery({ peers: gamePeers(env) });
const timer = setInterval(() => host.sweep(), 5_000);
timer.unref();
return createGameRouter(host, discovery);
}
+12
View File
@@ -0,0 +1,12 @@
{
"schema": "wikideck.mode/1",
"id": "classic",
"version": 1,
"name": "Classic",
"description": "The base WikiDeck rules with starter decks. Cards use their at-mint snapshot stats.",
"tags": ["base", "starter"],
"rules": {},
"cards": { "preset": "standard" },
"decks": { "kind": "starter" },
"limits": { "maxConcurrentMatches": 32, "turnSeconds": 90, "lobbyMinutes": 15 }
}
+36
View File
@@ -0,0 +1,36 @@
{
"schema": "wikideck.mode/1",
"id": "draft",
"version": 1,
"name": "Snake Draft",
"description": "Both players snake-draft 10-card decks from one shared, host-seeded pool of 30 preview cards, then play the base rules with a 4-card opening hand. Nobody brings cards, so everyone starts even.",
"tags": [
"draft",
"no-collection"
],
"rules": {
"deck": {
"min": 10,
"max": 10,
"maxCopiesPerPage": 2
},
"hand": {
"start": 4,
"max": 7,
"drawPerTurn": 1
}
},
"cards": {
"preset": "standard"
},
"decks": {
"kind": "draft",
"poolSize": 30,
"pickSeconds": 30
},
"limits": {
"maxConcurrentMatches": 16,
"turnSeconds": 90,
"lobbyMinutes": 15
}
}
+12
View File
@@ -0,0 +1,12 @@
{
"schema": "wikideck.mode/1",
"id": "trending",
"version": 1,
"name": "Trending",
"description": "Base rules, but live Wikipedia pageview trends power cards up or down: +1 power for every 25% rise in monthly views, -1 for every 25% fall, capped at 3 either way.",
"tags": ["live-data", "starter"],
"rules": {},
"cards": { "preset": "trending", "percentPerPoint": 25, "maxBonus": 3, "penalise": true },
"decks": { "kind": "starter" },
"limits": { "maxConcurrentMatches": 32, "turnSeconds": 90, "lobbyMinutes": 15 }
}
+70
View File
@@ -0,0 +1,70 @@
/**
* /api/game routes: publish, discover and host modes. Additive; nothing here reads or writes
* the ledger. Mounted by server/testnet/http.ts via server/game/index.ts.
*/
import express, { type Request, type Response, type NextFunction } from 'express';
import rateLimit from 'express-rate-limit';
import type { ModeHost } from './host.ts';
import { GameError } from './host.ts';
import type { ModeDiscovery } from './discovery.ts';
const limiter = (limit: number) => rateLimit({ windowMs: 60_000, limit, standardHeaders: 'draft-8', legacyHeaders: false });
export function createGameRouter(host: ModeHost, discovery: ModeDiscovery): express.Router {
const r = express.Router();
const reads = limiter(240), writes = limiter(60), plays = limiter(240), network = limiter(30);
const wrap = (fn: (req: Request, res: Response) => unknown) => async (req: Request, res: Response, next: NextFunction) => {
try { const out = await fn(req, res); if (!res.headersSent) res.json(out); } catch (e) { next(e); }
};
const bearer = (req: Request) => {
const h = req.get('authorization') ?? '';
return /^Bearer [A-Za-z0-9_-]{16,64}$/.test(h) ? h.slice(7) : '';
};
const body = (req: Request) => (req.body && typeof req.body === 'object' && !Array.isArray(req.body) ? req.body : {}) as Record<string, unknown>;
// Publish: this node's modes, host identity, stats.
r.get('/modes', reads, wrap(() => host.list()));
// Discover: this node plus every configured peer, as data. The browser opens a peer's own
// site to play there (CSP keeps API calls same-origin).
r.get('/network/modes', network, wrap(async () => {
const peers = await discovery.all();
return { self: host.list(), peers: peers.map(p => ({ origin: p.origin, ok: p.ok, error: p.error ?? null,
fetchedAt: p.fetchedAt, rejectedModes: p.rejected ?? 0, list: p.list ?? null })) };
}));
// Host leaderboard: matches hosted per node (self-reported by peers; see HOSTING.md).
r.get('/hosts/leaderboard', network, wrap(async () => {
const self = host.list();
const rows = [{ ...summary(self), self: true, reachable: true }];
for (const p of await discovery.all()) if (p.list) rows.push({ ...summary(p.list), self: false, reachable: p.ok });
rows.sort((a, b) => b.matchesHosted - a.matchesHosted || a.origin.localeCompare(b.origin));
return { hosts: rows };
}));
r.get('/modes/:modeId/leaderboard', reads, wrap(req => host.leaderboard(String(req.params.modeId))));
r.get('/modes/:modeId/lobbies', reads, wrap(req => ({ lobbies: host.openLobbies(String(req.params.modeId)) })));
r.post('/modes/:modeId/lobbies', writes, wrap((req, res) => {
const b = body(req);
res.status(201);
return host.createLobby(String(req.params.modeId), { name: b.name, secret: b.secret });
}));
r.post('/lobbies/:lobbyId/join', writes, wrap(req => {
const b = body(req);
return host.join(String(req.params.lobbyId), { name: b.name, secret: b.secret });
}));
r.get('/lobbies/:lobbyId', plays, wrap(req => host.view(String(req.params.lobbyId), bearer(req) || undefined)));
r.post('/lobbies/:lobbyId/pick', plays, wrap(req => host.pick(String(req.params.lobbyId), bearer(req), body(req).index)));
r.post('/lobbies/:lobbyId/actions', plays, wrap(req => host.act(String(req.params.lobbyId), bearer(req), body(req).action)));
r.post('/lobbies/:lobbyId/resign', writes, wrap(req => host.resign(String(req.params.lobbyId), bearer(req))));
// Finished match records: seed, decks and action log, so anyone can replay and audit them.
r.get('/matches/:matchId', reads, wrap(req => host.matchRecord(String(req.params.matchId))));
r.use((err: unknown, _req: Request, res: Response, next: NextFunction) => {
if (err instanceof GameError) { res.status(err.status).json({ error: err.message }); return; }
next(err);
});
return r;
}
function summary(list: { host: { origin: string; operator: string }; matchesHosted: number; modes: { stats: { playersOnline: number; distinctPlayers: number } }[] }) {
return { origin: list.host.origin, operator: list.host.operator, matchesHosted: list.matchesHosted,
modes: list.modes.length, playersOnline: list.modes.reduce((n, m) => n + m.stats.playersOnline, 0) };
}
+87
View File
@@ -0,0 +1,87 @@
/**
* Off-chain match records for this node: an append-only JSON-lines file plus in-memory
* aggregates (leaderboards, host totals). Nothing here touches the ledger.
*/
import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import { z } from 'zod';
export const MatchRecordSchema = z.object({
matchId: z.string().regex(/^[a-f0-9]{32}$/),
modeId: z.string().max(40),
modeVersion: z.number().int(),
/** Host-chosen seed. Together with decks and actions it lets anyone replay the match. */
seed: z.string().max(128),
/** The resolved ruleset the match ran under (mode overrides already applied). */
rules: z.unknown(),
players: z.array(z.object({ id: z.string().regex(/^[a-f0-9]{64}$/), name: z.string().max(24) }).strict()).length(2),
winner: z.union([z.literal(0), z.literal(1), z.null()]),
reason: z.string().max(40),
startedAt: z.number().int(),
endedAt: z.number().int(),
decks: z.array(z.array(z.unknown()).max(64)).length(2),
actions: z.array(z.object({ seat: z.union([z.literal(0), z.literal(1)]), action: z.unknown() }).strict()).max(2000),
}).strict();
export type MatchRecord = z.infer<typeof MatchRecordSchema>;
export type LeaderboardEntry = { playerId: string; name: string; wins: number; losses: number; draws: number; played: number };
type ModeAgg = { matches: number; players: Map<string, LeaderboardEntry> };
const KEEP_RECENT = 500;
export class MatchStore {
private readonly file: string | null;
private readonly modes = new Map<string, ModeAgg>();
private readonly recent = new Map<string, MatchRecord>();
private readonly allPlayers = new Set<string>();
total = 0;
/** `directory` null keeps records in memory only (tests). */
constructor(directory: string | null) {
this.file = directory ? join(directory, 'matches.jsonl') : null;
if (!directory || !this.file) return;
mkdirSync(directory, { recursive: true, mode: 0o700 });
if (!existsSync(this.file)) return;
for (const line of readFileSync(this.file, 'utf8').split('\n')) {
if (!line.trim()) continue;
const parsed = MatchRecordSchema.safeParse(safeJson(line));
if (parsed.success) this.index(parsed.data); // A torn last line after a crash is skipped.
}
}
add(record: MatchRecord): void {
const valid = MatchRecordSchema.parse(record);
if (this.file) appendFileSync(this.file, JSON.stringify(valid) + '\n', { mode: 0o600 });
this.index(valid);
}
get(matchId: string): MatchRecord | undefined { return this.recent.get(matchId); }
modeMatches(modeId: string): number { return this.modes.get(modeId)?.matches ?? 0; }
modePlayers(modeId: string): number { return this.modes.get(modeId)?.players.size ?? 0; }
distinctPlayers(): number { return this.allPlayers.size; }
leaderboard(modeId: string, limit = 20): LeaderboardEntry[] {
const players = [...(this.modes.get(modeId)?.players.values() ?? [])];
return players.sort((a, b) => b.wins - a.wins || a.losses - b.losses || b.played - a.played ||
a.playerId.localeCompare(b.playerId)).slice(0, limit).map(p => ({ ...p }));
}
private index(r: MatchRecord): void {
this.total++;
const agg = this.modes.get(r.modeId) ?? { matches: 0, players: new Map() };
this.modes.set(r.modeId, agg);
agg.matches++;
r.players.forEach((p, seat) => {
this.allPlayers.add(p.id);
const e = agg.players.get(p.id) ?? { playerId: p.id, name: p.name, wins: 0, losses: 0, draws: 0, played: 0 };
e.name = p.name; e.played++;
if (r.winner === null) e.draws++; else if (r.winner === seat) e.wins++; else e.losses++;
agg.players.set(p.id, e);
});
this.recent.set(r.matchId, r);
if (this.recent.size > KEEP_RECENT) this.recent.delete(this.recent.keys().next().value!);
}
}
function safeJson(line: string): unknown { try { return JSON.parse(line); } catch { return null; } }
+58
View File
@@ -0,0 +1,58 @@
/**
* Live pageview trends for `trending` modes, read from cache only at match time.
* Wikipedia egress is shared and rate-limited, so lookups never happen in a request path:
* unknown pages are queued and fetched one at a time, slowly, through the node's existing
* enrichment cache. Until a page is warm, its cards simply get no trend bonus.
*/
import type { LiveCardData } from '../../shared/game/modes.ts';
type Source = (pageId: number) => Promise<{ pageviews: { trendPercent: number | null } }>;
export class TrendCache {
private readonly values = new Map<number, { trend: number | null; at: number }>();
private readonly queue: number[] = [];
private readonly queued = new Set<number>();
private timer: ReturnType<typeof setInterval> | undefined;
private busy = false;
private readonly source: Source;
private readonly options: { intervalMs?: number; ttlMs?: number; maxEntries?: number; now?: () => number };
constructor(source: Source, options: { intervalMs?: number; ttlMs?: number; maxEntries?: number; now?: () => number } = {}) {
this.source = source; this.options = options;
}
/** Cache-only lookup; schedules a background fetch when missing or stale. */
get(pageId: number): LiveCardData | null {
const v = this.values.get(pageId);
const now = (this.options.now ?? Date.now)();
if (!v || now - v.at > (this.options.ttlMs ?? 6 * 3600_000)) this.enqueue(pageId);
return v ? { trendPercent: v.trend } : null;
}
enqueue(pageId: number): void {
if (!Number.isSafeInteger(pageId) || pageId <= 0 || this.queued.has(pageId) || this.queue.length >= 256) return;
this.queued.add(pageId); this.queue.push(pageId);
}
start(): void {
if (this.timer) return;
this.timer = setInterval(() => void this.step(), this.options.intervalMs ?? 3_000);
this.timer.unref();
}
stop(): void { if (this.timer) clearInterval(this.timer); this.timer = undefined; }
/** Fetch at most one page. Exposed for tests. */
async step(): Promise<void> {
if (this.busy) return;
const pageId = this.queue.shift();
if (pageId === undefined) return;
this.busy = true;
try {
const data = await this.source(pageId);
const trend = data.pageviews.trendPercent;
this.values.set(pageId, { trend: typeof trend === 'number' && Number.isFinite(trend) ? trend : null, at: (this.options.now ?? Date.now)() });
while (this.values.size > (this.options.maxEntries ?? 512)) this.values.delete(this.values.keys().next().value!);
} catch { /* Leave it cold; it is re-queued on a later lookup. */ }
finally { this.queued.delete(pageId); this.busy = false; }
}
}
+1
View File
@@ -149,6 +149,7 @@ app.post('/p2p/transaction',workLimit,async(req,res)=>{
const id=await ledger.submitTransaction(transaction);
res.status(202).json({id,status:'pending'});
});
app.use('/api/game',await (await import('../game/index.ts')).gameRouter({dataDir,enrichment:wikipediaEnrichment}));
app.use(['/api','/p2p'],(_req,res)=>{res.status(404).json({error:'Unknown testnet endpoint'});});
app.use(express.static(resolve(root,'dist')));
app.get('/{*path}',(_req,res)=>res.sendFile(resolve(root,'dist/index.html')));
+230
View File
@@ -0,0 +1,230 @@
/**
* Peer-hosted game modes: a mode is DATA, never code.
*
* A mode is a small JSON document: base-rule overrides (applied on top of the engine's
* default `Ruleset` and re-validated by the engine's own ruleset parser), a card-mapping
* preset chosen from a fixed list, a deck policy, limits, and display text.
* A peer never executes, evals or imports anything another peer sends; it only parses
* this schema with hard size limits. See docs/game/HOSTING.md.
*
* No I/O here: shared by the server (host + discovery) and the browser (lobby).
*/
import { z } from 'zod';
export const MODE_SCHEMA_VERSION = 'wikideck.mode/1' as const;
/** Upper bound on the JSON size of one mode document, before parsing. */
export const MAX_MODE_BYTES = 8 * 1024;
/** Upper bound on modes one node may publish (and that discovery accepts from one peer). */
export const MAX_MODES_PER_NODE = 16;
/** Upper bound on the JSON size of a whole /api/game/modes response read from a peer. */
export const MAX_MODE_LIST_BYTES = 192 * 1024;
const slug = z.string().regex(/^[a-z0-9](?:[a-z0-9-]{1,38}[a-z0-9])$/, 'lowercase slug, 3-40 chars');
/** Plain display text: no control characters, no angle brackets (rendered as text anyway). */
const text = (max: number) => z.string().trim().min(1).max(max)
.refine(s => !/[\u0000-\u001f\u007f<>]/.test(s), 'plain text only');
/**
* Rule overrides: a shallow-ish, bounded JSON object of numbers, booleans, short strings and
* short arrays of those. Its *meaning* is decided by the engine's ruleset schema, which runs
* after the merge (see `resolveRuleset`). This schema only guarantees it is small and inert.
*/
const scalar = z.union([z.number().finite(), z.boolean(), z.string().max(64)]);
const leaf = z.union([scalar, z.array(scalar).max(32)]);
const level2 = z.record(z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,39}$/), leaf)
.refine(o => Object.keys(o).length <= 32, 'too many keys');
export const RuleOverridesSchema = z.record(z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,39}$/),
z.union([leaf, level2])).refine(o => Object.keys(o).length <= 48, 'too many rule overrides');
export type RuleOverrides = z.infer<typeof RuleOverridesSchema>;
/**
* How Wikipedia data becomes card numbers in this mode. A fixed list of presets implemented
* in this file; a mode only picks one and tunes bounded parameters.
* - `standard`: the engine's default mapping from the immutable at-mint snapshot.
* - `live`: the same mapping, but from live current values when available.
* - `trending`: standard, plus a power bonus/penalty from live `pageviews.trendPercent`.
*/
export const CardMappingSchema = z.discriminatedUnion('preset', [
z.object({ preset: z.literal('standard') }).strict(),
z.object({ preset: z.literal('live') }).strict(),
z.object({ preset: z.literal('trending'),
/** Trend percent per +1 power (e.g. 25 → +25% trend gives +1). */
percentPerPoint: z.number().int().min(5).max(500).default(25),
/** Clamp on the bonus, in either direction. */
maxBonus: z.number().int().min(0).max(5).default(3),
/** Whether falling trends reduce power (never below 0). */
penalise: z.boolean().default(true),
}).strict(),
]);
export type CardMapping = z.infer<typeof CardMappingSchema>;
/** Where match decks come from. Matches never move or burn NFTs, whatever the policy. */
export const DeckPolicySchema = z.discriminatedUnion('kind', [
/** Each player brings a deck (starter deck or own cards, validated by the engine). */
z.object({ kind: z.literal('constructed'), allowStarter: z.boolean().default(true) }).strict(),
/** Host-seeded starter decks only: everyone gets the engine's `starterDeck(seed)`. */
z.object({ kind: z.literal('starter') }).strict(),
/** Snake draft from a host-seeded pool of non-NFT preview cards. */
z.object({ kind: z.literal('draft'),
/** Cards in the shared pool; must be at least 2 × the ruleset's deck size. */
poolSize: z.number().int().min(8).max(64).default(30),
/** Seconds per pick before the host auto-picks the first card. */
pickSeconds: z.number().int().min(5).max(120).default(30),
}).strict(),
]);
export type DeckPolicy = z.infer<typeof DeckPolicySchema>;
export const ModeLimitsSchema = z.object({
/** Concurrent open lobbies + live matches this mode may hold on the host. */
maxConcurrentMatches: z.number().int().min(1).max(256).default(32),
/** Seconds a player may take for one action before forfeiting the turn/match. */
turnSeconds: z.number().int().min(10).max(600).default(90),
/** Lobbies with no opponent expire after this many minutes. */
lobbyMinutes: z.number().int().min(1).max(120).default(15),
}).strict();
export type ModeLimits = z.infer<typeof ModeLimitsSchema>;
/** The mode document an operator writes (and peers publish). */
export const ModeSchema = z.object({
schema: z.literal(MODE_SCHEMA_VERSION),
id: slug,
/** Monotonic integer; bump when the rules change so old match records stay attributable. */
version: z.number().int().min(1).max(1_000_000),
name: text(48),
description: text(400),
tags: z.array(slug).max(5).default([]),
/** Overrides on top of the engine's DEFAULT_RULESET. */
rules: RuleOverridesSchema.default({}),
cards: CardMappingSchema.default({ preset: 'standard' }),
decks: DeckPolicySchema.default({ kind: 'constructed', allowStarter: true }),
limits: ModeLimitsSchema.default({ maxConcurrentMatches: 32, turnSeconds: 90, lobbyMinutes: 15 }),
}).strict();
export type ModeDocument = z.infer<typeof ModeSchema>;
export type ModeInput = z.input<typeof ModeSchema>;
/**
* The host's identity, configured by the node operator (never taken from a mode file).
* Discovery overwrites `origin` with the URL it actually fetched, so a peer can't
* publish modes in another node's name.
*/
export const HostIdentitySchema = z.object({
origin: z.string().url().max(256),
operator: text(48),
/** Optional short note, e.g. "EU, best effort". */
note: text(120).optional(),
}).strict();
export type HostIdentity = z.infer<typeof HostIdentitySchema>;
export const ModeStatsSchema = z.object({
playersOnline: z.number().int().min(0).max(1_000_000),
openLobbies: z.number().int().min(0).max(1_000_000),
liveMatches: z.number().int().min(0).max(1_000_000),
matchesPlayed: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
distinctPlayers: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
}).strict();
export type ModeStats = z.infer<typeof ModeStatsSchema>;
/** One entry of GET /api/game/modes. */
export const PublishedModeSchema = z.object({ mode: ModeSchema, stats: ModeStatsSchema }).strict();
export type PublishedMode = z.infer<typeof PublishedModeSchema>;
/** Body of GET /api/game/modes. */
export const ModeListSchema = z.object({
schema: z.literal(MODE_SCHEMA_VERSION),
host: HostIdentitySchema,
/** Total matches this node has hosted, across all its modes and versions. */
matchesHosted: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
modes: z.array(PublishedModeSchema).max(MAX_MODES_PER_NODE),
}).strict();
export type ModeList = z.infer<typeof ModeListSchema>;
/** Parse untrusted mode JSON text with a byte limit before JSON.parse. */
export function parseModeJson(json: string): ModeDocument {
if (byteLength(json) > MAX_MODE_BYTES) throw new Error(`Mode document exceeds ${MAX_MODE_BYTES} bytes`);
return parseMode(JSON.parse(json));
}
export function parseMode(value: unknown): ModeDocument {
assertInertKeys(value);
const mode = ModeSchema.parse(value);
if (byteLength(JSON.stringify(mode)) > MAX_MODE_BYTES) throw new Error(`Mode document exceeds ${MAX_MODE_BYTES} bytes`);
return mode;
}
/** Parse an untrusted peer's mode list. Invalid individual modes are dropped, not fatal. */
export function parseModeList(json: string): { list: ModeList; rejected: number } {
if (byteLength(json) > MAX_MODE_LIST_BYTES) throw new Error('Mode list too large');
const raw = z.object({ modes: z.array(z.unknown()).max(MAX_MODES_PER_NODE) }).passthrough().parse(JSON.parse(json));
let rejected = 0;
const modes: PublishedMode[] = [];
for (const entry of raw.modes) {
const parsed = hasForbiddenKeys(entry) ? null : PublishedModeSchema.safeParse(entry);
if (parsed?.success && byteLength(JSON.stringify(parsed.data.mode)) <= MAX_MODE_BYTES) modes.push(parsed.data);
else rejected++;
}
return { list: ModeListSchema.parse({ ...raw, modes }), rejected };
}
/** Stable key for a mode on a host: `<origin>#<id>@<version>`. */
export function modeKey(origin: string, mode: Pick<ModeDocument, 'id' | 'version'>): string {
return `${origin}#${mode.id}@${mode.version}`;
}
const BLOCKED_KEYS = new Set(['__proto__', 'prototype', 'constructor']);
/**
* Merge overrides onto the engine's base ruleset, then validate with the engine's parser.
* Objects merge one level deep; arrays and scalars replace. Unknown keys are left for the
* engine parser to reject (it is strict), so a mode can never smuggle in unchecked rules.
*/
export function resolveRuleset<R>(base: R, overrides: RuleOverrides, parse: (value: unknown) => R): R {
const merged: Record<string, unknown> = structuredClone(base) as Record<string, unknown>;
for (const [key, value] of Object.entries(overrides)) {
if (BLOCKED_KEYS.has(key)) throw new Error('Forbidden rule key');
const current = merged[key];
if (isPlainObject(value) && isPlainObject(current)) {
const inner: Record<string, unknown> = { ...current };
for (const [k, v] of Object.entries(value)) {
if (BLOCKED_KEYS.has(k)) throw new Error('Forbidden rule key');
inner[k] = v;
}
merged[key] = inner;
} else merged[key] = value;
}
return parse(merged);
}
/** Live Wikipedia trend data a card mapping may read (subset of PageEnrichment). */
export type LiveCardData = { trendPercent: number | null };
/**
* Apply the mode's card-mapping preset to a card's base power. Pure and bounded.
* `standard`/`live` differ only in which stats the caller fed the engine's card builder.
*/
export function mappedPower(basePower: number, mapping: CardMapping, live?: LiveCardData): number {
if (mapping.preset !== 'trending') return basePower;
return basePower + trendBonus(mapping, live?.trendPercent ?? null);
}
export function trendBonus(mapping: Extract<CardMapping, { preset: 'trending' }>, trendPercent: number | null): number {
if (trendPercent === null || !Number.isFinite(trendPercent)) return 0;
let bonus = Math.trunc(trendPercent / mapping.percentPerPoint);
if (!mapping.penalise) bonus = Math.max(0, bonus);
return Math.max(-mapping.maxBonus, Math.min(mapping.maxBonus, bonus));
}
/** Clamp a mapped power the same way regardless of preset: never negative. */
export function clampPower(power: number): number { return Math.max(0, Math.round(power)); }
/** Reject prototype-polluting keys anywhere (zod's record() does not check them reliably). */
function hasForbiddenKeys(value: unknown, depth = 0): boolean {
if (depth > 8 || typeof value !== 'object' || value === null) return depth > 8;
for (const key of Object.keys(value)) {
if (BLOCKED_KEYS.has(key)) return true;
if (hasForbiddenKeys((value as Record<string, unknown>)[key], depth + 1)) return true;
}
return false;
}
function assertInertKeys(value: unknown): void {
if (hasForbiddenKeys(value)) throw new Error('Forbidden key in mode document');
}
function isPlainObject(v: unknown): v is Record<string, unknown> {
return typeof v === 'object' && v !== null && !Array.isArray(v);
}
function byteLength(s: string): number { return new TextEncoder().encode(s).length; }
+150
View File
@@ -0,0 +1,150 @@
// End to end over HTTP with the real engine: publish, discover, host all three example modes.
import test from 'node:test';
import assert from 'node:assert/strict';
import express from 'express';
import type { AddressInfo } from 'node:net';
import { gameRouter } from '../server/game/index.ts';
import { previewPool } from '../server/game/engine-binding.ts';
import { DEFAULT_RULESET, STARTER_POOL, replay, parseRuleset } from '../shared/game/index.ts';
import { parseMode, resolveRuleset, MODE_SCHEMA_VERSION } from '../shared/game/modes.ts';
import { ModeListSchema } from '../shared/game/modes.ts';
async function serve(env: NodeJS.ProcessEnv, enrichment?: any) {
const app = express();
app.use(express.json({ limit: '68kb' }));
app.use('/api/game', await gameRouter({ dataDir: null, env, enrichment }));
app.use((err: Error, _q: express.Request, res: express.Response, _n: express.NextFunction) => res.status(400).json({ error: err.message }));
const server = app.listen(0, '127.0.0.1');
await new Promise(r => server.once('listening', r));
const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
return { base, close: () => new Promise(r => server.close(r)) };
}
const call = async (base: string, path: string, body?: unknown, token?: string) => {
const res = await fetch(base + path, { method: body === undefined ? 'GET' : 'POST',
headers: { 'content-type': 'application/json', ...(token ? { authorization: `Bearer ${token}` } : {}) },
body: body === undefined ? undefined : JSON.stringify(body) });
return { status: res.status, json: await res.json() as any };
};
const alice = { name: 'Alice', secret: 'alice-secret-0123456789abcdef' };
const bob = { name: 'Bob', secret: 'bob-secret-0123456789abcdefgh' };
async function playToEnd(base: string, lobby: string, tokens: string[]) {
for (let i = 0; i < 400; i++) {
let moved = false;
for (const t of tokens) {
const v = (await call(base, `/api/game/lobbies/${lobby}`, undefined, t)).json;
if (v.phase !== 'playing') return v;
// Play the first card if possible, else end the turn.
const a = v.legalActions.find((x: any) => x.type === 'play') ?? v.legalActions.find((x: any) => x.type === 'endTurn');
if (a) { const r = await call(base, `/api/game/lobbies/${lobby}/actions`, { action: a }, t); assert.equal(r.status, 200, JSON.stringify(r.json)); moved = true; }
}
if (!moved) break;
}
return (await call(base, `/api/game/lobbies/${lobby}`, undefined, tokens[0])).json;
}
test('modes api: three example modes over HTTP with the real engine', { timeout: 60_000 }, async () => {
const node = await serve({ WIKIDECK_MODES: 'classic,trending,draft', PUBLIC_ORIGIN: 'http://127.0.0.1:3101',
WIKIDECK_GAME_OPERATOR: 'Node A', WIKIDECK_GAME_PEERS: '' },
{ get: async (pageId: number) => ({ pageviews: { trendPercent: pageId % 3 === 0 ? 80 : -30 } }) });
try {
const list = (await call(node.base, '/api/game/modes')).json;
ModeListSchema.parse(list);
assert.deepEqual(list.modes.map((m: any) => m.mode.id), ['classic', 'trending', 'draft']);
assert.equal(list.host.operator, 'Node A');
for (const id of ['classic', 'trending']) {
const a = await call(node.base, `/api/game/modes/${id}/lobbies`, alice);
assert.equal(a.status, 201);
const b = await call(node.base, `/api/game/lobbies/${a.json.lobbyId}/join`, bob);
assert.equal(b.status, 200, JSON.stringify(b.json));
const peek = (await call(node.base, `/api/game/lobbies/${a.json.lobbyId}`)).json;
assert.equal(peek.state, undefined);
const wrongSeat = (await call(node.base, `/api/game/lobbies/${a.json.lobbyId}`, undefined, a.json.token)).json.legalActions[0];
const cheat = await call(node.base, `/api/game/lobbies/${a.json.lobbyId}/actions`, { action: { ...wrongSeat, player: 1 } }, a.json.token);
assert.equal(cheat.status, 400, 'cannot act for the other seat');
const end = await playToEnd(node.base, a.json.lobbyId, [a.json.token, b.json.token]);
assert.equal(end.phase, 'finished', JSON.stringify(end).slice(0, 300));
const rec = (await call(node.base, `/api/game/matches/${end.matchId}`)).json;
assert.equal(rec.modeId, id);
assert.equal(rec.decks[0].length, 12);
}
// Draft: 20 snake picks, 10-card decks.
const a = (await call(node.base, '/api/game/modes/draft/lobbies', alice)).json;
const b = (await call(node.base, `/api/game/lobbies/${a.lobbyId}/join`, bob)).json;
const tokens = [a.token, b.token];
let picks = 0;
for (;;) {
const v = (await call(node.base, `/api/game/lobbies/${a.lobbyId}`, undefined, a.token)).json;
if (v.phase !== 'drafting') { assert.equal(v.phase, 'playing'); break; }
const free = v.draft.pool.find((c: any) => c.takenBy === null);
const r = await call(node.base, `/api/game/lobbies/${a.lobbyId}/pick`, { index: free.index }, tokens[v.draft.toPick]);
assert.equal(r.status, 200, JSON.stringify(r.json));
picks++;
}
assert.equal(picks, 20);
const end = await playToEnd(node.base, a.lobbyId, tokens);
assert.equal(end.phase, 'finished');
const record = (await call(node.base, `/api/game/matches/${end.matchId}`)).json;
assert.equal(record.decks[1].length, 10);
// Anyone can audit a match: replaying the published record reproduces the result.
const replayed = replay(record.rules, record.decks, record.seed, record.actions.map((a: any) => a.action));
assert.equal(replayed.phase, 'over');
assert.equal(replayed.result?.winner ?? null, record.winner);
const after = (await call(node.base, '/api/game/modes')).json;
assert.equal(after.matchesHosted, 3);
const board = (await call(node.base, '/api/game/modes/draft/leaderboard')).json;
assert.equal(board.entries.length, 2);
assert.equal((await call(node.base, '/api/game/modes/nope/leaderboard')).status, 404);
assert.equal((await call(node.base, '/api/game/lobbies/zzz')).status, 404);
} finally { await node.close(); }
});
test('modes api: a node lists its peers\' modes and ranks hosts by matches hosted', { timeout: 30_000 }, async () => {
const peerB = await serve({ WIKIDECK_MODES: 'draft,classic', PUBLIC_ORIGIN: 'http://b.invalid', WIKIDECK_GAME_OPERATOR: 'Node B' });
const nodeA = await serve({ WIKIDECK_MODES: 'classic', PUBLIC_ORIGIN: 'http://a.invalid', WIKIDECK_GAME_OPERATOR: 'Node A',
WIKIDECK_GAME_PEERS: `${peerB.base},http://127.0.0.1:1`, WIKIDECK_ALLOW_PRIVATE_PEERS: '1' });
try {
// One match on B so it leads the host leaderboard.
const a = (await call(peerB.base, '/api/game/modes/draft/lobbies', alice)).json;
const b = (await call(peerB.base, `/api/game/lobbies/${a.lobbyId}/join`, bob)).json;
await call(peerB.base, `/api/game/lobbies/${a.lobbyId}/resign`, {}, b.token); // during the draft: not a match
const c = (await call(peerB.base, '/api/game/modes/classic/lobbies', alice)).json;
const d = (await call(peerB.base, `/api/game/lobbies/${c.lobbyId}/join`, bob)).json;
assert.equal((await call(peerB.base, `/api/game/lobbies/${c.lobbyId}/resign`, {}, d.token)).json.outcome.winner, 0);
const resigned = (await call(peerB.base, `/api/game/lobbies/${c.lobbyId}`, undefined, c.token)).json;
const rec = (await call(peerB.base, `/api/game/matches/${resigned.matchId}`)).json;
assert.equal(replay(rec.rules, rec.decks, rec.seed, rec.actions.map((x: any) => x.action)).result?.winner, 0, 'resign replays as concede');
const net = (await call(nodeA.base, '/api/game/network/modes')).json;
assert.equal(net.self.host.operator, 'Node A');
assert.equal(net.peers.length, 2);
assert.equal(net.peers[0].ok, true);
assert.equal(net.peers[0].list.host.origin, peerB.base, 'origin pinned to the fetched peer');
assert.equal(net.peers[0].list.modes[0].mode.id, 'draft');
assert.equal(net.peers[1].ok, false);
const hosts = (await call(nodeA.base, '/api/game/hosts/leaderboard')).json.hosts;
assert.deepEqual(hosts.map((h: any) => [h.operator, h.matchesHosted]), [['Node B', 1], ['Node A', 0]]);
} finally { await nodeA.close(); await peerB.close(); }
});
test('modes api: draft preview pool is deterministic and deck-legal', () => {
const p1 = previewPool(DEFAULT_RULESET, 'seed', 30), p2 = previewPool(DEFAULT_RULESET, 'seed', 30);
assert.deepEqual(p1, p2);
assert.equal(p1.length, 30);
assert.equal(new Set(p1.map(c => c.id)).size, 30);
assert.equal(previewPool(DEFAULT_RULESET, 'x', 100).length, STARTER_POOL.length * DEFAULT_RULESET.deck.maxCopiesPerPage);
});
test('modes api: the rule examples in HOSTING.md are valid modes', () => {
for (const rules of [
{ maxTurns: 4, energy: { start: 3, perTurn: 1, max: 6 } },
{ lanes: 4, laneModifiers: { pool: ['plain', 'portal', 'narrow', 'plain'], revealTurns: [1, 2, 3, 4] } },
{ deck: { min: 16, max: 16, maxCopiesPerPage: 2 } },
{ maxTurns: 6, energy: { max: 7 } },
]) {
const m = parseMode({ schema: MODE_SCHEMA_VERSION, id: 'doc-example', version: 1, name: 'x', description: 'x', rules });
assert.doesNotThrow(() => resolveRuleset(DEFAULT_RULESET, m.rules, parseRuleset), JSON.stringify(rules));
}
});
+186
View File
@@ -0,0 +1,186 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { mkdtempSync, rmSync, readFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { parseMode, MODE_SCHEMA_VERSION } from '../shared/game/modes.ts';
import { ModeHost, GameError } from '../server/game/host.ts';
import { MatchStore } from '../server/game/store.ts';
import { ModeDiscovery } from '../server/game/discovery.ts';
import { stubEngine } from './modes-stub-engine.ts';
const mode = (over: object = {}) => parseMode({ schema: MODE_SCHEMA_VERSION, id: 'stub', version: 1, name: 'Stub',
description: 'Stub mode.', decks: { kind: 'starter' }, ...over });
const identity = { origin: 'http://node-a.test', operator: 'Alice' };
const alice = { name: 'Alice', secret: 'alice-secret-0123456789abcdef' };
const bob = { name: 'Bob', secret: 'bob-secret-0123456789abcdefgh' };
function playOut(host: ModeHost, lobbyId: string, tokens: string[]) {
for (let guard = 0; guard < 50; guard++) {
const v0 = host.view(lobbyId, tokens[0]) as any;
if (v0.phase !== 'playing') return v0;
for (const t of tokens) {
const v = host.view(lobbyId, t) as any;
if (v.legalActions?.length) void host.act(lobbyId, t, v.legalActions[0]);
}
}
throw new Error('did not finish');
}
test('modes host: lobby → match → record → leaderboard and host credit', async () => {
let now = 1_000_000;
const store = new MatchStore(null);
const host = new ModeHost({ identity, modes: [mode()], engine: stubEngine, store, now: () => now });
const a = host.createLobby('stub', alice);
assert.equal(host.list().modes[0]!.stats.openLobbies, 1);
assert.deepEqual(host.openLobbies('stub').map(l => l.host), ['Alice']);
const b = await host.join(a.lobbyId, bob);
assert.equal(b.seat, 1);
assert.equal((host.view(a.lobbyId) as any).state, undefined, 'spectators see no private state');
const end = playOut(host, a.lobbyId, [a.token, b.token]);
assert.equal(end.phase, 'finished');
const list = host.list();
assert.equal(list.matchesHosted, 1);
assert.equal(list.host.operator, 'Alice');
assert.equal(list.modes[0]!.stats.matchesPlayed, 1);
assert.equal(list.modes[0]!.stats.distinctPlayers, 2);
const board = host.leaderboard('stub');
assert.equal(board.entries.length, 2);
assert.equal(board.key, 'http://node-a.test#stub@1');
const rec = host.matchRecord(end.matchId);
assert.equal(rec.actions.length, 6);
assert.equal(rec.players[0]!.name, 'Alice');
assert.ok(!JSON.stringify(rec).includes(alice.secret), 'secrets are never stored');
});
test('modes host: actions must be legal and from the right seat', async () => {
const host = new ModeHost({ identity, modes: [mode()], engine: stubEngine, store: new MatchStore(null) });
const a = host.createLobby('stub', alice);
const b = await host.join(a.lobbyId, bob);
await assert.rejects(host.act(a.lobbyId, a.token, { type: 'play', card: 99 }), /Illegal/);
await assert.rejects(host.act(a.lobbyId, 'not-a-token-xxxxxxxxxxxx', { type: 'play', card: 0 }), /Not a player/);
await host.act(a.lobbyId, a.token, { type: 'play', card: 0 });
await assert.rejects(host.act(a.lobbyId, a.token, { type: 'play', card: 0 }), /Illegal/, 'no double play');
await host.act(a.lobbyId, b.token, { card: 1, type: 'play' }); // key order doesn't matter
await assert.rejects(host.join(a.lobbyId, { name: 'Eve', secret: 'eve-secret-0123456789abcdefgh' }), /no longer open/);
assert.throws(() => host.createLobby('stub', { name: '<script>', secret: alice.secret }), GameError);
assert.throws(() => host.createLobby('stub', { name: 'Al', secret: 'short' }), GameError);
assert.throws(() => host.createLobby('nope', alice), /not hosted/);
});
test('modes host: limits, expiry and turn timeouts', async () => {
let now = 0;
const host = new ModeHost({ identity, modes: [mode({ limits: { maxConcurrentMatches: 2, turnSeconds: 10, lobbyMinutes: 1 } })],
engine: stubEngine, store: new MatchStore(null), now: () => now });
const l1 = host.createLobby('stub', alice);
host.createLobby('stub', bob);
assert.throws(() => host.createLobby('stub', { name: 'Cy', secret: 'cy-secret-0123456789abcdefghij' }), /match limit/);
now += 61_000; host.sweep();
assert.equal((host.view(l1.lobbyId) as any).phase, 'expired');
const l3 = host.createLobby('stub', alice);
const t3 = await host.join(l3.lobbyId, bob);
await host.act(l3.lobbyId, l3.token, { type: 'play', card: 0 }); // Bob now owes a move
now += 11_000; host.sweep();
const v = host.view(l3.lobbyId, t3.token) as any;
assert.deepEqual(v.outcome, { winner: 0, reason: 'timeout' });
assert.equal(host.list().matchesHosted, 1);
});
test('modes host: snake draft builds both decks from one pool', async () => {
const host = new ModeHost({ identity, modes: [mode({ decks: { kind: 'draft', poolSize: 8, pickSeconds: 10 } })],
engine: stubEngine, store: new MatchStore(null) });
const a = host.createLobby('stub', alice);
const b = await host.join(a.lobbyId, bob);
const tok = [a.token, b.token];
const order: number[] = [];
for (;;) {
const v = host.view(a.lobbyId, a.token) as any;
if (v.phase !== 'drafting') break;
order.push(v.draft.toPick);
const free = v.draft.pool.find((c: any) => c.takenBy === null).index;
await assert.rejects(host.pick(a.lobbyId, tok[1 - v.draft.toPick]!, free), /Not your pick/);
await host.pick(a.lobbyId, tok[v.draft.toPick]!, free);
}
assert.equal(order.length, 8);
assert.deepEqual(order.slice(0, 4), [order[0], 1 - order[0]!, 1 - order[0]!, order[0]], 'snake order');
assert.equal((host.view(a.lobbyId, a.token) as any).phase, 'playing');
assert.throws(() => new ModeHost({ identity, modes: [mode({ decks: { kind: 'draft', poolSize: 8 }, rules: { deckSize: 5 } })],
engine: stubEngine, store: new MatchStore(null) }), /poolSize/);
});
test('modes host: trending mapping adjusts power from live trends, once, bounded', async () => {
const seen: number[] = [];
const host = new ModeHost({ identity, modes: [mode({ cards: { preset: 'trending', percentPerPoint: 10, maxBonus: 2 } })],
engine: stubEngine, store: new MatchStore(null),
liveData: async pageId => { seen.push(pageId); return { trendPercent: pageId % 2 ? 1000 : -1000 }; } });
const a = host.createLobby('stub', alice);
const b = await host.join(a.lobbyId, bob);
const base = stubEngine.starterDeck(stubEngine.defaultRuleset, 'x');
const hand = (host.view(a.lobbyId, a.token) as any).state.hand;
assert.equal(seen.length, 8);
for (const c of hand) assert.ok(c.power >= 0 && c.power <= 11);
void b; void base;
});
test('modes host: bad rules fail at startup, via the engine parser', () => {
assert.throws(() => new ModeHost({ identity, modes: [mode({ rules: { turns: 99 } })], engine: stubEngine, store: new MatchStore(null) }));
assert.throws(() => new ModeHost({ identity, modes: [mode(), mode()], engine: stubEngine, store: new MatchStore(null) }), /Duplicate/);
});
test('modes store: records persist and rebuild aggregates; torn lines are skipped', async () => {
const dir = mkdtempSync(join(tmpdir(), 'modes-store-'));
try {
const host = new ModeHost({ identity, modes: [mode()], engine: stubEngine, store: new MatchStore(dir) });
const a = host.createLobby('stub', alice);
const b = await host.join(a.lobbyId, bob);
playOut(host, a.lobbyId, [a.token, b.token]);
const file = join(dir, 'matches.jsonl');
const { appendFileSync } = await import('node:fs');
appendFileSync(file, '{"torn":');
const reopened = new MatchStore(dir);
assert.equal(reopened.total, 1);
assert.equal(reopened.leaderboard('stub').length, 2);
assert.ok(readFileSync(file, 'utf8').includes('"modeId":"stub"'));
} finally { rmSync(dir, { recursive: true, force: true }); }
});
test('modes discovery: peers are fetched as data, origin is pinned, failures are contained', async () => {
const good = { schema: MODE_SCHEMA_VERSION, host: { origin: 'https://evil.example', operator: 'Bob' }, matchesHosted: 7,
modes: [{ mode: mode(), stats: { playersOnline: 1, openLobbies: 1, liveMatches: 0, matchesPlayed: 7, distinctPlayers: 3 } }] };
let calls = 0, now = 0;
const fetcher = async (url: string) => {
calls++;
if (url.startsWith('http://b.test')) return new Response(JSON.stringify(good), { status: 200 });
if (url.startsWith('http://c.test')) return new Response('x'.repeat(400_000), { status: 200 });
throw new Error('connect ECONNREFUSED');
};
const d = new ModeDiscovery({ peers: ['http://b.test', 'http://c.test', 'http://d.test'], fetcher, now: () => now, ttlMs: 1000 });
const peers = await d.all();
assert.equal(peers[0]!.ok, true);
assert.equal(peers[0]!.list!.host.origin, 'http://b.test', 'claimed origin replaced by the fetched one');
assert.equal(peers[1]!.ok, false);
assert.equal(peers[1]!.error, 'response too large');
assert.equal(peers[2]!.error, 'invalid or unreachable');
await d.all();
assert.equal(calls, 3, 'cached within ttl');
now = 5000; await d.all();
assert.equal(calls, 6);
});
test('modes trends: cache-only at match time, warmed one page at a time', async () => {
const { TrendCache } = await import('../server/game/trends.ts');
const calls: number[] = [];
let now = 0;
const t = new TrendCache(async id => { calls.push(id); if (id === 2) throw new Error('rate limited'); return { pageviews: { trendPercent: id * 10 } }; },
{ now: () => now, ttlMs: 1000 });
assert.equal(t.get(1), null, 'cold page: no bonus, no fetch in the request path');
assert.equal(t.get(2), null);
t.get(1);
assert.deepEqual(calls, []);
await t.step(); await t.step();
assert.deepEqual(calls, [1, 2], 'one fetch per step, deduplicated');
assert.deepEqual(t.get(1), { trendPercent: 10 });
assert.equal(t.get(2), null, 'failure stays cold');
now = 5000; t.get(1); await t.step(); await t.step();
assert.deepEqual(calls, [1, 2, 2, 1], 'stale entries are refreshed in the background');
});
+85
View File
@@ -0,0 +1,85 @@
import test from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync } from 'node:fs';
import { parseMode, parseModeJson, parseModeList, resolveRuleset, trendBonus, mappedPower,
MAX_MODE_BYTES, MODE_SCHEMA_VERSION } from '../shared/game/modes.ts';
import { BUILTIN_MODES_DIR, BUILTIN_MODE_IDS, loadModes } from '../server/game/config.ts';
import { parsePeerOrigins } from '../server/game/discovery.ts';
import { stubEngine } from './modes-stub-engine.ts';
import { engineBinding } from '../server/game/engine-binding.ts';
const base = { schema: MODE_SCHEMA_VERSION, id: 'my-mode', version: 1, name: 'My mode', description: 'A test mode.' };
test('modes: minimal document gets safe defaults', () => {
const m = parseMode(base);
assert.deepEqual(m.cards, { preset: 'standard' });
assert.equal(m.decks.kind, 'constructed');
assert.equal(m.limits.maxConcurrentMatches, 32);
assert.deepEqual(m.rules, {});
});
test('modes: built-in example modes parse and resolve against the engine ruleset', () => {
for (const id of BUILTIN_MODE_IDS) {
const m = parseModeJson(readFileSync(`${BUILTIN_MODES_DIR}${id}.json`, 'utf8'));
assert.equal(m.id, id);
assert.doesNotThrow(() => resolveRuleset(engineBinding.defaultRuleset, m.rules, engineBinding.parseRuleset));
}
assert.deepEqual(loadModes({ WIKIDECK_MODES: 'classic,draft' }).map(m => m.id), ['classic', 'draft']);
assert.deepEqual(loadModes({ WIKIDECK_MODES: 'none' }), []);
assert.throws(() => loadModes({ WIKIDECK_MODES: 'classic,classic' }), /Duplicate/);
assert.throws(() => loadModes({ WIKIDECK_MODES: '../../etc/passwd' }), /unknown built-in/);
});
test('modes: schema rejects code, markup, unknown fields and oversize documents', () => {
assert.throws(() => parseMode({ ...base, script: 'alert(1)' }));
assert.throws(() => parseMode({ ...base, name: '<img src=x onerror=alert(1)>' }));
assert.throws(() => parseMode({ ...base, id: 'Bad Id' }));
assert.throws(() => parseMode({ ...base, cards: { preset: 'eval', code: 'x' } }));
assert.throws(() => parseMode({ ...base, cards: { preset: 'trending', maxBonus: 99 } }));
assert.throws(() => parseMode({ ...base, limits: { maxConcurrentMatches: 100000 } }));
assert.throws(() => parseMode({ ...base, rules: { deep: { deeper: { deepest: 1 } } } }));
assert.throws(() => parseModeJson(JSON.stringify(base).replace('}', ',"rules":{"__proto__":{"turns":1}}}')));
assert.throws(() => resolveRuleset(stubEngine.defaultRuleset, JSON.parse('{"__proto__":{"turns":1}}'), stubEngine.parseRuleset));
assert.throws(() => parseModeJson(JSON.stringify({ ...base, description: 'x'.repeat(MAX_MODE_BYTES) })), /exceeds|too_big|400/);
const many = Object.fromEntries(Array.from({ length: 60 }, (_, i) => [`k${i}`, i]));
assert.throws(() => parseMode({ ...base, rules: many }));
});
test('modes: rule overrides merge one level deep and the engine parser has the final say', () => {
const r = resolveRuleset(stubEngine.defaultRuleset, { turns: 5, scoring: { tieBreak: 'first' } }, stubEngine.parseRuleset);
assert.deepEqual(r, { deckSize: 4, turns: 5, scoring: { tieBreak: 'first' } });
assert.throws(() => resolveRuleset(stubEngine.defaultRuleset, { turns: 500 }, stubEngine.parseRuleset));
assert.throws(() => resolveRuleset(stubEngine.defaultRuleset, { unknownRule: 1 }, stubEngine.parseRuleset));
assert.deepEqual(stubEngine.defaultRuleset.scoring, { tieBreak: 'draw' }, 'base ruleset is not mutated');
});
test('modes: trending bonus is bounded, optional and symmetric', () => {
const t = parseMode({ ...base, cards: { preset: 'trending' } }).cards;
assert.equal(t.preset, 'trending');
if (t.preset !== 'trending') return;
assert.equal(trendBonus(t, 60), 2);
assert.equal(trendBonus(t, 1000), 3);
assert.equal(trendBonus(t, -1000), -3);
assert.equal(trendBonus(t, null), 0);
assert.equal(trendBonus(t, Number.NaN), 0);
assert.equal(trendBonus({ ...t, penalise: false }, -80), 0);
assert.equal(mappedPower(4, { preset: 'standard' }, { trendPercent: 500 }), 4);
});
test('modes: peer lists drop invalid modes instead of failing, and are size capped', () => {
const good = { mode: parseMode(base), stats: { playersOnline: 0, openLobbies: 0, liveMatches: 0, matchesPlayed: 3, distinctPlayers: 2 } };
const body = { schema: MODE_SCHEMA_VERSION, host: { origin: 'http://a.example', operator: 'A' }, matchesHosted: 3,
modes: [good, { mode: { ...base, id: 'X' }, stats: good.stats }] };
const { list, rejected } = parseModeList(JSON.stringify(body));
assert.equal(list.modes.length, 1);
assert.equal(rejected, 1);
assert.throws(() => parseModeList(' '.repeat(300 * 1024)), /too large/);
});
test('modes: game peers are operator-configured origins only', () => {
assert.deepEqual(parsePeerOrigins('https://a.example, https://a.example/,https://b.example', false), ['https://a.example', 'https://b.example']);
assert.throws(() => parsePeerOrigins('http://a.example', false));
assert.deepEqual(parsePeerOrigins('http://node-b:3001', true), ['http://node-b:3001']);
assert.throws(() => parsePeerOrigins('https://a.example/api', false));
assert.throws(() => parsePeerOrigins('https://user@a.example', false));
});
+44
View File
@@ -0,0 +1,44 @@
// A tiny deterministic stand-in for the real engine, implementing the EnginePort used by
// server/game. Each turn both seats play one card; after `turns` turns, higher total power wins.
import { z } from 'zod';
import type { EnginePort, Seat } from '../server/game/engine-port.ts';
export type StubCard = { id: string; pageId: number | null; power: number };
type Rules = { deckSize: number; turns: number; scoring: { tieBreak: 'draw' | 'first' } };
type State = { rules: Rules; turn: number; hands: StubCard[][]; staged: (number | null)[]; totals: number[] };
const RulesSchema = z.object({ deckSize: z.number().int().min(2).max(20), turns: z.number().int().min(1).max(10),
scoring: z.object({ tieBreak: z.enum(['draw', 'first']) }).strict() }).strict();
function rng(seed: string) { let h = 2166136261; for (const c of seed) h = Math.imul(h ^ c.charCodeAt(0), 16777619);
return () => { h ^= h << 13; h ^= h >>> 17; h ^= h << 5; return (h >>> 0) / 2 ** 32; }; }
const pool = (seed: string, n: number) => { const r = rng(seed);
return Array.from({ length: n }, (_, i) => ({ id: `${seed}-${i}`, pageId: 1000 + i, power: 1 + Math.floor(r() * 9) })); };
export const stubEngine: EnginePort<Rules, StubCard, State, { type: 'play'; card: number }> = {
defaultRuleset: { deckSize: 4, turns: 3, scoring: { tieBreak: 'draw' } },
parseRuleset: v => RulesSchema.parse(v),
deckSize: r => r.deckSize,
starterDeck: (r, seed) => pool(seed, r.deckSize),
previewPool: (_r, seed, n) => pool(seed, n),
validateDeck: (r, cards) => { if (cards.length !== r.deckSize) throw new Error('wrong deck size');
for (const c of cards) if (!Number.isInteger(c.power) || c.power < 0 || c.power > 20) throw new Error('bad card'); },
cardPower: c => c.power,
withPower: (c, power) => ({ ...c, power }),
cardPageId: c => c.pageId,
cardSummary: c => ({ id: c.id, power: c.power }),
createMatch: (rules, decks) => ({ rules, turn: 0, hands: decks.map(d => d.map(c => ({ ...c }))), staged: [null, null], totals: [0, 0] }),
legalActions: (s, seat) => s.turn >= s.rules.turns || s.staged[seat] !== null ? [] :
s.hands[seat]!.map((_, card) => ({ type: 'play' as const, card })),
applyAction: (s, seat, a) => {
const n: State = structuredClone(s);
n.staged[seat] = a.card;
if (n.staged[0] !== null && n.staged[1] !== null) {
for (const p of [0, 1] as Seat[]) { const [c] = n.hands[p]!.splice(n.staged[p]!, 1); n.totals[p]! += c!.power; }
n.staged = [null, null]; n.turn++;
}
return n;
},
isOver: s => s.turn >= s.rules.turns,
result: s => ({ winner: s.totals[0]! > s.totals[1]! ? 0 : s.totals[1]! > s.totals[0]! ? 1 : s.rules.scoring.tieBreak === 'first' ? 0 : null }),
viewFor: (s, seat) => ({ turn: s.turn, hand: s.hands[seat], opponentCards: s.hands[1 - seat]!.length, totals: s.totals, staged: s.staged[seat] }),
};