Files
wikideck/shared/game/types.ts
T
claudeanderic 4f7a8a7c74 Night 1: Edit War card game, eom.dev accounts, peer-hosted modes, Android and iOS apps (#22)
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>
2026-11-17 17:40:58 +00:00

237 lines
8.5 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* 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'; }
}