forked from WikiDeck/wikideck
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>
96 lines
4.9 KiB
TypeScript
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> = {};
|