Files
wikideck/shared/bots/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: WikiDeck/wikideck#22

Co-authored-by: Claude <claude@eom.dev>
2026-11-17 17:40:58 +00:00

85 lines
3.7 KiB
TypeScript

// Bot and simulation types. Engine-agnostic: bots talk to the rules engine only
// through EngineAdapter, so the same bots run against shared/game (see adapter.ts)
// and against the toy engine used by the self-tests. Pure: no I/O.
export type Seat = 0 | 1;
export type Rng = () => number;
export interface DeckSpec {
id: string;
/** Free-form tags for win-rate breakdowns: archetype, faction, keywords. */
tags: string[];
/** Whatever the engine needs to build the deck (card list, starter seed, ...). */
payload: unknown;
}
export interface MatchOutcome {
winner: Seat | null; // null = draw
reason?: string;
}
export interface EngineAdapter<S = unknown, A = unknown> {
name: string;
/** Ruleset ids this adapter knows (e.g. "v1", "v1.1"). */
rulesets(): string[];
/** Decks available for matchmaking under a ruleset. */
decks(ruleset: string): DeckSpec[];
createMatch(ruleset: string, decks: [DeckSpec, DeckSpec], seed: number): S;
/** Seat that must act now. */
toAct(state: S): Seat;
legalActions(state: S, seat: Seat): A[];
/** Must not mutate `state`. */
applyAction(state: S, action: A): S;
isOver(state: S): boolean;
result(state: S): MatchOutcome;
/** Turn counter (1-based, counts both players' turns). */
turn(state: S): number;
/** Heuristic value of the state for `seat`, roughly in [-1, 1]. */
evaluate(state: S, seat: Seat): number;
/** Card ids touched by an action (played, deployed...), for per-card stats. */
cardsOf(state: S, action: A): string[];
/** Short stable label for an action kind ("play", "pass", ...). */
actionKind(action: A): string;
/** Optional card metadata (numeric stats, keywords, faction) for per-stat balance analysis. */
cardMeta?(cardId: string): Record<string, number | string | string[]> | undefined;
/** Printed power an action puts on the board (-1 for non-plays). Used by the naive maxpower bot. */
actionPower?(state: S, action: A): number;
/**
* Counterfactual keyword value for a finished match: for each (seat, keyword) on cards that seat played,
* replay the same actions with that keyword removed from that seat's cards. `power` = own final total power
* lost, `flip` = 1 if the result got worse for that seat (win->draw/loss, draw->loss), `cards` = cards played.
*/
keywordValues?(final: S, decks: [DeckSpec, DeckSpec]): { seat: Seat; keyword: string; power: number; flip: number; cards: number }[];
/** Seat with the first-player advantage (defaults to toAct at match start). */
firstSeat?(state: S): Seat;
/** What `seat` may see (e.g. shared/game viewFor). Bots receive only this. Default: the state itself. */
observe?(state: S, seat: Seat): unknown;
/** A full state consistent with an observation, hidden parts sampled with `rng` (determinization). */
assume?(observation: unknown, seat: Seat, rng: Rng): S;
}
/** A bot is a pure function of what its seat can see (EngineAdapter.observe). ui-b reuses it as the browser AI. */
export type BotFn<O = unknown, A = unknown> = (observation: O, player: Seat, rng: Rng) => A;
export interface MatchRecord {
ruleset: string;
seed: number;
decks: [string, string];
deckTags: [string[], string[]];
bots: [string, string];
firstSeat: Seat; // seat that acted first
winner: Seat | null;
reason?: string;
turns: number;
actions: number;
truncated: boolean;
/** Eval for seat 0 at the start of each turn. */
evalTrace: number[];
/** Turn from which the eventual winner led on eval until the end (null for draws). */
decidedTurn: number | null;
cardsPlayed: [string[], string[]];
keywordValues?: { seat: Seat; keyword: string; power: number; flip: number; cards: number }[];
actionKinds: Record<string, number>;
ms: number;
}