Files
wikideck/shared/game/keywords.ts
T
claudeandClaude Opus 5.5 b5c90d2dc1 Night 1: game engine core and ENGINE_API.md, DESIGN v1 (#25)
Deterministic, off-chain rules engine in shared/game: createMatch, legalActions, applyAction, isOver, result, viewFor, serialisation, Ruleset as data.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 04:22:10 +00:00

96 lines
4.9 KiB
TypeScript

/**
* Keyword and Portal registry (DESIGN §10.2, §10.3). Effects are code here; which
* ones a card/topic uses and their numbers are data (GameCard.keyword,
* TopicDef.portal, Ruleset.keywordsEnabled / keywordParams / portalParams).
* Owner of the effects: engine-b (claude/wikideck#3). engine-a owns the hook contract:
*
* - Hooks get an EffectContext over the engine's *working copy* of the state and may
* mutate it (e.g. `bonus` on cards). Safe: applyAction already cloned.
* Any randomness must come from ctx.rng (match RNG, resolution order, §4.2.5).
* - A keyword's hooks run only if its id is in ruleset.keywordsEnabled.
* - onReveal(ctx, self): right after `self` is pushed into its lane (§5.4). Cards revealed
* earlier (any seat, any turn) are on the board; later ones are not. self.seq is its global
* reveal number; cards revealed this turn have `turn === ctx.state.turn`.
* - endOfTurn(ctx, self): §5.5 order: initiative seat's cards first, then lanes 1→N, then seq.
* Also runs on the last turn, before scoring (§7).
* - ongoing(ctx, self, target) → delta: PURE. Called for every (self, target) pair in play,
* including self === target. ctx.rng is a throwaway copy. Don't call ctx.power on a card from
* inside ongoing (infinite recursion); read base fields instead.
* - Portals: same, plus onPortalReveal(ctx), canPlay(ctx, card, seat), capacity(ctx) → number
* (lane capacity override), allOnTopic (Disambiguation) and atScoring(ctx) → [delta0, delta1]
* (Topic power added at scoring, §7). All Portal hooks apply only once the Portal is revealed.
* Params: ruleset.portalParams[topic.id], falling back to portalParams[portal id].
* - Hooks must not throw and must not move or remove cards (§10, v1).
*/
import type { Rng } from './rng.ts';
import type { CardInPlay, GameCard, MatchState, PlayerId } from './types.ts';
/** The 9 implemented keyword ids (§10.2; edition, obscure and wildcard are disabled by default). */
export const KEYWORD_IDS = ['viral', 'rising', 'local', 'encyclopedic', 'nostalgic', 'translated', 'edition', 'obscure', 'wildcard'] as const;
/** The 6 Portal kinds (§10.3), named after their default Topic. */
export const PORTAL_IDS = ['main-page', 'trending', 'featured-article', 'stub', 'interwiki', 'disambiguation'] as const;
export interface EffectContext {
state: MatchState;
rng: Rng;
/** Tunable numbers for this keyword/portal from the ruleset. */
params: Record<string, number>;
/** Lane the effect lives in. */
lane: number;
/** Add a line to the match log (attributed to this keyword/portal). */
log(text: string): void;
/** Current lane power of a card in play (the engine's cardPower). Not for use inside `ongoing`. */
power(card: CardInPlay): number;
}
export interface KeywordDef {
id: string;
name: string;
/** One short line of reminder text with {param} placeholders. */
text: string;
onReveal?(ctx: EffectContext, self: CardInPlay): void;
endOfTurn?(ctx: EffectContext, self: CardInPlay): void;
ongoing?(ctx: EffectContext, self: CardInPlay, target: CardInPlay): number;
}
export interface PortalDef {
id: string;
name: string;
text: string;
onPortalReveal?(ctx: EffectContext): void;
/** Runs when any card is revealed in this Topic (after the card's own onReveal). */
onReveal?(ctx: EffectContext, card: CardInPlay): void;
ongoing?(ctx: EffectContext, target: CardInPlay): number;
/** Lets a Topic reject a card; checked when queuing and again at reveal. */
canPlay?(ctx: EffectContext, card: GameCard, player: PlayerId): boolean;
/** Per-player lane capacity in this Topic (replaces ruleset.laneCapacity). */
capacity?(ctx: EffectContext): number;
/** Every card here counts as on-topic. */
allOnTopic?: boolean;
/** Topic power added to [seat 0, seat 1] here at scoring. */
atScoring?(ctx: EffectContext): [number, number];
}
/** Cards on the same side of the same lane, excluding `self`. */
export function allies(state: MatchState, self: CardInPlay): CardInPlay[] {
return state.lanes[self.lane].cards[self.owner].filter(card => card !== self);
}
/** The lane's Portal, if it has one and it is revealed. */
export function activePortal(state: MatchState, lane: number): PortalDef | undefined {
const l = state.lanes[lane];
return l?.portalRevealed && l.topic.portal ? PORTALS[l.topic.portal] : undefined;
}
/** §1.4/§6 on-topic: home stat matches the Topic's stat, or an active Disambiguation-style Portal. */
export function isOnTopic(state: MatchState, card: CardInPlay): boolean {
const lane = state.lanes[card.lane];
return lane.topic.stat === card.card.home || activePortal(state, card.lane)?.allOnTopic === true;
}
/** Filled in by engine-b (§10.2). Ids must be in KEYWORD_IDS. */
export const KEYWORDS: Record<string, KeywordDef> = {};
/** Filled in by engine-b (§10.3). Ids must be in PORTAL_IDS. */
export const PORTALS: Record<string, PortalDef> = {};