Overnight build by 17 Claude agents (2026-11-16 22:45 → 01:30 EST), coordinated in [claude/wikideck milestone 63](https://gitea.eom.dev/claude/wikideck/milestone/63). **For Eric's review. Do not merge without it.** The full write-up is in `docs/night/REPORT.md`. **What's in it** (38 reviewed PRs, squash-merged into `night/2026-11-16`): - **Edit War:** - a 3-lane, 6-turn card game built on what WikiDeck cards actually hold - a pure, deterministic, off-chain rules engine (`shared/game/`, with the API in `docs/game/ENGINE_API.md`); rules are data and v1.1 is the default - a mobile-first Play UI with a lobby, deck builder, four loaner starter decks, a match against the AI, results and a tutorial - a landing page (fixes #3) - **Design and balance:** `docs/game/DESIGN.md`, `CARD_DATA.md` (236 sampled articles) and `BALANCE.md` (bot simulations). Starter pairings went from 23–77% on v1 to roughly even on v1.1. - **eom.dev accounts:** Dex OIDC with PKCE, plus off-chain wallet linking, where the client builds the message it signs (`server/account/`, `src/auth/`). - **Peer-hosted game modes:** modes are JSON data, never code. Node API at `/api/game/*`, with host credit and leaderboards. Three example modes (`shared/game/modes.ts`, `server/game/`, `docs/game/HOSTING.md`). - **Mobile:** Capacitor 7 Android app (a debug APK played a full match against the AI in the emulator), and an iOS project waiting on Xcode (`docs/night/ANDROID.md`, `docs/night/IOS.md`). - **Testnet tooling:** `deploy/night/` (LAN-only, 3 nodes) and an optional `WIKIDECK_USER_AGENT` (the default is unchanged). **Not touched:** consensus and protocol (`server/chain.ts`, `shared/protocol.ts`, `server/testnet/{consensus,ledger,…}.ts`, `native/`), the live deployment and mainnet. Matches run off-chain and never move or burn NFTs. **Checks:** the final integration gate passed in `node:24-alpine`: `npm test` 241/242 with 0 fail (1 skipped), and `npm run build` passes. The repo needs Node 24, because Node 20 fails 12 tests falsely. **Decisions for Eric** (see REPORT.md, Known issues and Next steps): 1. whether the live node should set `WIKIDECK_USER_AGENT` 2. the Xcode licence, which you should accept yourself 3. #49 in the fork, a bot change held after the freeze 4. on-chain host rewards (proposal only, in HOSTING.md) 🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: #22 Co-authored-by: Claude <claude@eom.dev>
237 lines
8.5 KiB
TypeScript
237 lines
8.5 KiB
TypeScript
/**
|
||
* WikiDeck game engine types (off-chain). Implements docs/game/DESIGN.md ("Edit War").
|
||
* Everything here is plain JSON data: MatchState round-trips through
|
||
* JSON.stringify/parse with no loss (no Maps, classes or functions).
|
||
* Contract: docs/game/ENGINE_API.md. Announce changes on claude/wikideck#3.
|
||
*/
|
||
import type { RngState } from './rng.ts';
|
||
|
||
export type PlayerId = 0 | 1;
|
||
export const PLAYERS: readonly PlayerId[] = [0, 1];
|
||
|
||
/** Category buckets from server/wiki.ts; a card's faction (DESIGN §1.5). */
|
||
export type Faction = 'Space' | 'Nature' | 'People' | 'Science' | 'History' | 'Culture';
|
||
export const FACTIONS: readonly Faction[] = ['Space', 'Nature', 'People', 'Science', 'History', 'Culture'];
|
||
export type Stat = 'attention' | 'depth' | 'reach';
|
||
export const STATS: readonly Stat[] = ['attention', 'depth', 'reach'];
|
||
export type Rarity = 'Common' | 'Rare' | 'Epic' | 'Legendary';
|
||
|
||
/**
|
||
* A card as the engine sees it: already derived (DESIGN §1) by cards.ts from a
|
||
* host-frozen CardInput. The engine never reads raw snapshot stats. Hosts/modes
|
||
* may adjust fields (e.g. power) before createMatch; the engine does not re-derive.
|
||
*/
|
||
export interface GameCard {
|
||
/** Unique within one deck (the NFT card hash, or `loaner:<pageId>:<n>`). */
|
||
cardId: string;
|
||
/** null for unpinned loaners (DESIGN §2.1): copies then count per cardId. */
|
||
pageId: number | null;
|
||
title: string;
|
||
faction: Faction;
|
||
/** Cosmetic in v1 (§1.7). */
|
||
rarity: Rarity;
|
||
cost: number;
|
||
power: number;
|
||
home: Stat;
|
||
/** Live trend arrow, frozen at match start (§1.6). Adds to power in every Topic. */
|
||
trend: -1 | 0 | 1;
|
||
keyword: string | null;
|
||
/** 'owned' = an NFT the player holds (never moved or burned by a match). */
|
||
source: 'owned' | 'loaner';
|
||
/** Host plausibility result (§1.10). Derivation already applied uncheckedCostCap. Default: 'loaner' for loaners, 'verified' for owned. */
|
||
check?: 'verified' | 'unverified' | 'unchecked' | 'loaner';
|
||
}
|
||
|
||
/** A Topic (lane) definition in a ruleset's topic pool (§3). */
|
||
export interface TopicDef {
|
||
id: string;
|
||
name: string;
|
||
stat: Stat;
|
||
/** Portal kind id in PORTALS (§10.3), or null for a plain Topic. Numbers: Ruleset.portalParams[topic id] (falls back to [portal id]). */
|
||
portal: string | null;
|
||
}
|
||
|
||
/**
|
||
* DESIGN §9 RulesConfig: every rule number as flat data so peer-hosted modes can
|
||
* override it. Use parseRuleset() for untrusted input.
|
||
*/
|
||
export interface Ruleset {
|
||
version: string;
|
||
deckSize: number;
|
||
maxCopiesPerPage: number;
|
||
maxLoaners: number;
|
||
openingHand: number;
|
||
handLimit: number;
|
||
mulligan: boolean;
|
||
turns: number;
|
||
turnSeconds: number;
|
||
afkTurns: number;
|
||
/** energyByTurn[t-1] is the base energy on turn t. Length must be ≥ turns. */
|
||
energyByTurn: number[];
|
||
/** Unspent energy carried to next turn, capped at this. */
|
||
energyCarryMax: number;
|
||
bonusEnergy: number;
|
||
underdog: boolean;
|
||
topicCount: number;
|
||
distinctStats: boolean;
|
||
/** portalReveal[i] = turn on which Topic i's Portal is revealed (stats are always visible). Length = topicCount. */
|
||
portalReveal: number[];
|
||
laneCapacity: number;
|
||
topicPool: TopicDef[];
|
||
/** Per-keyword numbers, keyed by keyword id. */
|
||
keywordParams: Record<string, Record<string, number>>;
|
||
/** Per-Portal numbers, keyed by Topic id (or Portal kind id as a fallback). */
|
||
portalParams: Record<string, Record<string, number>>;
|
||
costThresholds: number[];
|
||
/** Index = cost (0–6). */
|
||
powerByCost: number[];
|
||
/** Index = cost (0–6): on-topic bonus. */
|
||
onTopicBonus: number[];
|
||
vanillaBonus: number;
|
||
/** Keyword ids whose hooks run. Cards with a disabled keyword are vanilla (derivation handles power). */
|
||
keywordsEnabled: string[];
|
||
ownedCards: boolean;
|
||
/** v1.1 hook (derive.ts): 'home' gives Culture cards a home-stat keyword. v1: 'faction'. */
|
||
cultureKeyword: 'faction' | 'home';
|
||
trendUp: number;
|
||
trendDown: number;
|
||
trendMinDaily: number;
|
||
uncheckedCostCap: number;
|
||
factionSynergyCap: number;
|
||
verifyStats: boolean;
|
||
/** Id of the percentile reference table used by derive.ts. */
|
||
percentiles: string;
|
||
/** Id of the starter deck list. */
|
||
starterDecks: string;
|
||
}
|
||
|
||
export interface CardInPlay {
|
||
card: GameCard;
|
||
owner: PlayerId;
|
||
lane: number;
|
||
/** Turn the card was revealed. */
|
||
turn: number;
|
||
/** Global reveal sequence number (1, 2, 3 … across both seats and all turns). */
|
||
seq: number;
|
||
/** Permanent power changes from effects (on-reveal buffs etc.). */
|
||
bonus: number;
|
||
}
|
||
|
||
export interface QueuedPlay { cardId: string; lane: number }
|
||
|
||
export interface PlayerState {
|
||
deck: GameCard[];
|
||
hand: GameCard[];
|
||
/** Energy available this turn (before queued plays). */
|
||
energy: number;
|
||
/** Plays chosen this turn, hidden from the opponent until reveal. Order matters. */
|
||
queue: QueuedPlay[];
|
||
committed: boolean;
|
||
/** Consecutive timeouts with nothing queued (§7 afkTurns). */
|
||
afk: number;
|
||
/** Energy carried into this turn (already included in `energy`). */
|
||
carry: number;
|
||
}
|
||
|
||
export interface LaneState {
|
||
/** Stat and name are always visible; the Portal only once portalRevealed. */
|
||
topic: TopicDef;
|
||
portalRevealed: boolean;
|
||
cards: [CardInPlay[], CardInPlay[]];
|
||
}
|
||
|
||
export type MatchPhase = 'planning' | 'over';
|
||
|
||
export type LogEvent =
|
||
| { t: 'turnStart'; turn: number; energy: [number, number]; initiative: PlayerId }
|
||
| { t: 'portalRevealed'; lane: number; topic: TopicDef }
|
||
| { t: 'underdog'; player: PlayerId }
|
||
| { t: 'draw'; player: PlayerId; cardId: string }
|
||
| { t: 'reveal'; player: PlayerId; cardId: string; lane: number }
|
||
| { t: 'fizzle'; player: PlayerId; cardId: string; lane: number }
|
||
| { t: 'effect'; source: string; player: PlayerId; text: string }
|
||
| { t: 'concede'; player: PlayerId; afk: boolean }
|
||
| { t: 'matchOver'; result: MatchResult };
|
||
|
||
export interface MatchState {
|
||
schema: 'wikideck-match/1';
|
||
engineVersion: number;
|
||
ruleset: Ruleset;
|
||
seed: number;
|
||
rng: RngState;
|
||
/** 1-based current turn. */
|
||
turn: number;
|
||
phase: MatchPhase;
|
||
/** Player who reveals first this turn (§5.4). Alternates every turn. */
|
||
initiative: PlayerId;
|
||
/** Last reveal sequence number handed out (CardInPlay.seq). */
|
||
revealSeq: number;
|
||
players: [PlayerState, PlayerState];
|
||
lanes: LaneState[];
|
||
log: LogEvent[];
|
||
/** Every action applied so far: (ruleset, decks, seed, actions) replays the match exactly. */
|
||
actions: Action[];
|
||
result: MatchResult | null;
|
||
}
|
||
|
||
export type Action =
|
||
/** Queue a card from hand into a lane (§5.3). */
|
||
| { type: 'play'; player: PlayerId; cardId: string; lane: number }
|
||
/** Take back a queued play this turn (refunds its energy). */
|
||
| { type: 'undo'; player: PlayerId; cardId: string }
|
||
/** Commit the queue (empty = pass). When both have committed, the turn resolves. */
|
||
| { type: 'commit'; player: PlayerId }
|
||
/** The host's turn timer expired for this player: commits what's queued, counts toward afkTurns if empty. */
|
||
| { type: 'timeout'; player: PlayerId }
|
||
| { type: 'concede'; player: PlayerId };
|
||
|
||
export interface MatchResult {
|
||
/** null = draw. */
|
||
winner: PlayerId | null;
|
||
reason: 'topics' | 'totalPower' | 'draw' | 'concede' | 'afk';
|
||
topicsLed: [number, number];
|
||
/** lanePower[lane][player] at the end, including "at scoring" Portals. */
|
||
lanePower: [number, number][];
|
||
totalPower: [number, number];
|
||
turns: number;
|
||
}
|
||
|
||
/** What one player is allowed to see. UI and AI read only this, never raw MatchState. */
|
||
export interface PlayerView {
|
||
you: PlayerId;
|
||
ruleset: Ruleset;
|
||
turn: number;
|
||
phase: MatchPhase;
|
||
initiative: PlayerId;
|
||
energy: number;
|
||
/** Energy left after your queued plays. */
|
||
energyLeft: number;
|
||
hand: GameCard[];
|
||
queue: QueuedPlay[];
|
||
committed: boolean;
|
||
deckCount: number;
|
||
/**
|
||
* DESIGN §5.3: planning is hidden. handCount still counts queued cards and no
|
||
* opponent energy is exposed, so nothing changes while they queue; only `committed` does.
|
||
*/
|
||
opponent: { handCount: number; deckCount: number; committed: boolean };
|
||
lanes: {
|
||
/** Always visible; `portal` is null until the Portal is revealed. */
|
||
topic: TopicDef;
|
||
portalRevealed: boolean;
|
||
/** cards[0] = yours, cards[1] = opponent's (revealed cards only). */
|
||
cards: [CardInPlay[], CardInPlay[]];
|
||
/** Lane power of each card in `cards`, same shape. */
|
||
cardPower: [number[], number[]];
|
||
/** power[0] = yours, power[1] = opponent's. */
|
||
power: [number, number];
|
||
/** Who leads this Topic from your point of view. */
|
||
leader: 'you' | 'opponent' | null;
|
||
}[];
|
||
result: MatchResult | null;
|
||
}
|
||
|
||
export class IllegalActionError extends Error {
|
||
constructor(message: string) { super(message); this.name = 'IllegalActionError'; }
|
||
}
|