@rpgm-tools/neo-angband-core 0.10.0

package/src/game/effect-env.ts

@@ -0,0 +1,252 @@
+/**
+ * The effect-interpreter environment adapters: build a live EffectContext
+ * (effects/interpreter.ts) from the GameState so the already-ported general
+ * effect handlers (effects/handlers.ts: EF_HEAL_HP, EF_CURE, the EF_TIMED_*
+ * family, EF_NOURISH, EF_DAMAGE, ...) run end to end against a real player
+ * instead of no-opping on an absent slot.
+ *
+ * These are the concrete backing for the narrow capability interfaces the
+ * interpreter defines:
+ * - TimedHost is backed by the player-timed runtime (player/timed.ts) over the
+ *   bound timed-effect table, so grade transitions, messages, disturbance and
+ *   the NONSTACKING guard behave identically to every other status change.
+ * - EffectPlayer.hp is a live view of the player's hitpoints; takeHit and
+ *   applyDamageReduction route through the shared player-damage primitive
+ *   (player/take-hit.ts), the same one the projection player driver uses.
+ *
+ * The bound timed table (player/bind.ts) is passed in because GameState does
+ * not carry it; the same is true of the food value, depth, damage reduction
+ * and player_inc_check queries (all calc_bonuses / pack state that lives
+ * outside the turn-loop state). A caller that supplies no incQueries lets every
+ * timed increase through, matching a bare resistance-less player.
+ */
+
+import type { GameEvents } from "../events.js";
+import type {
+  EffectContext,
+  EffectMessages,
+  EffectPlayer,
+  HasHp,
+  HasMana,
+  TimedHost,
+} from "../effects/interpreter.js";
+import {
+  playerClearTimed,
+  playerDecTimed,
+  playerIncCheck,
+  playerIncTimed,
+  playerSetTimed,
+} from "../player/timed.js";
+import type {
+  PlayerIncCheckHooks,
+  PlayerIncCheckQueries,
+  PlayerTimedHooks,
+} from "../player/timed.js";
+import {
+  playerApplyDamageReduction,
+  takeHit,
+} from "../player/take-hit.js";
+import type {
+  DamageReduction,
+  TakeHitHooks,
+  TakeHitTarget,
+} from "../player/take-hit.js";
+import type { TimedEffect } from "../player/types.js";
+import { DEFAULT_HITPOINT_WARN } from "./project-cast.js";
+import type { GameState } from "./context.js";
+import type { Effect } from "../effects/effect.js";
+
+/** What the effect-environment adapters need beyond the GameState. */
+export interface EffectEnvDeps {
+  /** The bound player timed-effect table (player/bind.ts), any order. */
+  timedTable: readonly TimedEffect[];
+  /** msg(): status / damage messages. */
+  onMessage?: (text: string, msgt?: string) => void;
+  /** GameEvents bus, if the caller wires effect events. */
+  events?: GameEvents;
+  /** z_info->food_value; defaults to state.z.foodValue. */
+  foodValue?: number;
+  /** Dungeon depth, for handlers/expressions that read it. */
+  level?: number;
+  /** OPT(player, show_damage). */
+  showDamage?: boolean;
+  /** Renderer-neutral EF_SELECT chooser; -1 cancels, -2 chooses random. */
+  chooseEffect?: (first: Effect | null, count: number) => number;
+  /** player_inc_check resolvers; when absent every increase is allowed. */
+  incQueries?: PlayerIncCheckQueries;
+  /** player_inc_check side hooks (equip-learn + monster-source smart-learn);
+   * threaded for monster-source casts (mon-cast.ts) so update_smart_learn runs
+   * on the no-save branch. Absent for player-side effects. */
+  incHooks?: PlayerIncCheckHooks;
+  /** Extra player-timed hooks (onNotify / onTransition). */
+  timedHooks?: PlayerTimedHooks;
+  /** take_hit consequences (onDeath, combatRegen, ...). */
+  takeHitHooks?: TakeHitHooks;
+  /** state.dam_red / perc_dam_red (calc_bonuses); default zero. */
+  reduction?: DamageReduction;
+}
+
+/** A TakeHitTarget view whose chp / is_dead mutations write back to the state. */
+function takeHitTarget(state: GameState): TakeHitTarget {
+  const p = state.actor.player;
+  return {
+    get chp(): number {
+      return p.chp;
+    },
+    set chp(v: number) {
+      p.chp = v;
+    },
+    mhp: p.mhp,
+    lev: p.lev,
+    get isDead(): boolean {
+      return state.isDead;
+    },
+    set isDead(v: boolean) {
+      state.isDead = v;
+    },
+    timed: p.timed,
+    hitpointWarn: DEFAULT_HITPOINT_WARN,
+  };
+}
+
+/**
+ * buildTimedHost: the interpreter's TimedHost over the live player, dispatching
+ * through the player-timed runtime with the bound effect table (looked up by
+ * the effect's index, so the table may be in any order).
+ */
+export function buildTimedHost(
+  state: GameState,
+  deps: EffectEnvDeps,
+): TimedHost {
+  const p = state.actor.player;
+  const byIndex = new Map<number, TimedEffect>();
+  for (const e of deps.timedTable) byIndex.set(e.index, e);
+
+  const effect = (idx: number): TimedEffect => {
+    const e = byIndex.get(idx);
+    if (!e) throw new Error(`no bound timed effect for index ${idx}`);
+    return e;
+  };
+
+  const hooks: PlayerTimedHooks = {
+    ...(deps.onMessage
+      ? { onMessage: (t: string, msgt: string) => deps.onMessage!(t, msgt) }
+      : {}),
+    ...(deps.timedHooks ?? {}),
+    ...(deps.incQueries
+      ? {
+          incCheck: (idx: number) =>
+            playerIncCheck(effect(idx), deps.incQueries!, deps.incHooks),
+        }
+      : {}),
+  };
+
+  return {
+    timed: (idx) => p.timed[idx] ?? 0,
+    setTimed: (idx, v, notify, canDisturb) =>
+      playerSetTimed(p, effect(idx), v, notify, canDisturb, hooks),
+    incTimed: (idx, v, notify, canDisturb, check) =>
+      playerIncTimed(p, effect(idx), v, notify, canDisturb, check, hooks),
+    decTimed: (idx, v, notify, canDisturb) =>
+      playerDecTimed(p, effect(idx), v, notify, canDisturb, hooks),
+    clearTimed: (idx, notify, canDisturb) =>
+      playerClearTimed(p, effect(idx), notify, canDisturb, hooks),
+  };
+}
+
+/**
+ * buildEffectPlayer: the interpreter's EffectPlayer slot over the live player -
+ * a live hitpoint view, the timed host, and take_hit / damage-reduction routed
+ * through the shared player-damage primitive.
+ */
+export function buildEffectPlayer(
+  state: GameState,
+  deps: EffectEnvDeps,
+): EffectPlayer {
+  const p = state.actor.player;
+  const target = takeHitTarget(state);
+  const reduction = deps.reduction ?? { damRed: 0, percDamRed: 0 };
+
+  const hp: HasHp = {
+    get chp(): number {
+      return p.chp;
+    },
+    set chp(v: number) {
+      p.chp = v;
+    },
+    get mhp(): number {
+      return p.mhp;
+    },
+    set mhp(v: number) {
+      p.mhp = v;
+    },
+    get chpFrac(): number {
+      return p.chpFrac;
+    },
+    set chpFrac(v: number) {
+      p.chpFrac = v;
+    },
+  };
+
+  const mana: HasMana = {
+    get csp(): number {
+      return p.csp;
+    },
+    set csp(v: number) {
+      p.csp = v;
+    },
+    get msp(): number {
+      return p.msp;
+    },
+    set msp(v: number) {
+      p.msp = v;
+    },
+    get cspFrac(): number {
+      return p.cspFrac;
+    },
+    set cspFrac(v: number) {
+      p.cspFrac = v;
+    },
+  };
+
+  return {
+    hp,
+    mana,
+    timed: buildTimedHost(state, deps),
+    applyDamageReduction: (dam) =>
+      playerApplyDamageReduction(target, reduction, dam),
+    takeHit: (dam, killer) => takeHit(target, dam, killer, deps.takeHitHooks),
+  };
+}
+
+/**
+ * buildEffectContext: a full EffectContext for effect_do / effect_simple, built
+ * from the live GameState. rng comes from the state; the player slot and food
+ * value are populated so the general handlers act for real.
+ */
+export function buildEffectContext(
+  state: GameState,
+  deps: EffectEnvDeps,
+): EffectContext {
+  const messages: EffectMessages | undefined = deps.onMessage
+    ? { msg: deps.onMessage }
+    : undefined;
+
+  /* OPT(player, show_damage): the injected dep wins, else the wired option
+   * store. Absent (worldless tests), it stays undefined (falsey), preserving
+   * the prior seam-absent behaviour and the shipped default (off). */
+  const showDamage = deps.showDamage ?? state.options?.get("show_damage");
+
+  return {
+    rng: state.rng,
+    ...(messages ? { messages } : {}),
+    ...(deps.events ? { events: deps.events } : {}),
+    player: buildEffectPlayer(state, deps),
+    foodValue: deps.foodValue ?? state.z.foodValue,
+    ...(deps.level !== undefined ? { level: deps.level } : {}),
+    ...(showDamage !== undefined ? { showDamage } : {}),
+    ...((deps.chooseEffect ?? state.effectChooser)
+      ? { chooseEffect: deps.chooseEffect ?? state.effectChooser }
+      : {}),
+  };
+}

package/src/game/effect-game-env.ts

@@ -0,0 +1,86 @@
+/**
+ * The shared game-layer effect environment. Game effect handlers (the attack
+ * projections in effect-attack.ts, the monster effects in effect-monster.ts,
+ * and later batches) need access to the live GameState, which the effects/
+ * layer's EffectContext deliberately keeps opaque (the layering rule keeps
+ * effects/ below game/). This module owns the concrete environment those
+ * handlers read and the plumbing that attaches it to an EffectContext.
+ *
+ * A handler reads the environment from context.env.game (an opaque slot on
+ * EffectContext) via gameEnv(); when it is absent the handler no-ops (the
+ * worldless rule the effects/ handlers already follow). The caller attaches it
+ * with attachGameEnv after building the base context (game/effect-env.ts
+ * buildEffectContext).
+ */
+
+import type { Loc } from "../loc.js";
+import type { EffectContext, EffectHandlerContext } from "../effects/interpreter.js";
+import type { TakeHitHooks } from "../player/take-hit.js";
+import type { GameState } from "./context.js";
+import type { CastContext } from "./project-cast.js";
+import type { TeleportEnv } from "./effect-teleport.js";
+import type { GeneralEffectEnv } from "./effect-general.js";
+import type { ItemEffectEnv } from "./effect-item.js";
+import type { SummonEffectEnv } from "./effect-summon.js";
+
+/** Everything the game-layer effect handlers need beyond the EffectContext. */
+export interface GameEffectEnv {
+  /** The live game state (monsters, chunk, player actor, rng). */
+  state: GameState;
+  /** The projection casting context (bound projections, range, player actor). */
+  cast: CastContext;
+  /**
+   * target_get for a DIR_TARGET player cast. The command layers back it
+   * with a live getter over game/target.ts (targetOkay + targetGet), so a
+   * target that moves or dies mid-chain is re-read per handler exactly as
+   * upstream's per-handler target_get; tests may pass a plain grid.
+   */
+  aimed?: Loc | undefined;
+  /** cave->mon_current: the acting monster, excluded by PROJECT_LOS. */
+  monCurrent?: number;
+  /** player_has(PF_CHARM). */
+  charm?: boolean;
+  /** take_hit consequences for effects that damage the player (BANISH, ...). */
+  takeHitHooks?: TakeHitHooks;
+  /**
+   * get_com symbol chooser for EF_BANISH: return the chosen monster glyph, or
+   * null to abort. Absent means the effect aborts (no UI wired).
+   */
+  banishSymbol?: () => string | null;
+  /** Teleport-family hooks and unmodelled-subsystem seams (effect-teleport.ts). */
+  teleport?: TeleportEnv;
+  /** General-handler seams: trap access for glyphs/webs (effect-general.ts). */
+  general?: GeneralEffectEnv;
+  /** Item-targeting seams: get_item and the ego/curse tables (effect-item.ts). */
+  item?: ItemEffectEnv;
+  /**
+   * Per-game flavor knowledge, so an item-identifying effect (EF_IDENTIFY ->
+   * object_learn_unknown_rune -> player_know_object) can fire the
+   * object_flavor_aware side effect. Absent, awareness is left unchanged (the
+   * worldless rule); the ignore/notice consequences ride flavorDeps.
+   */
+  flavor?: import("../obj/knowledge.js").FlavorKnowledge;
+  /** object_flavor_aware's ignore/notice side effects, used with `flavor`. */
+  flavorDeps?: import("../obj/knowledge.js").FlavorAwareDeps;
+  /** Summoning seams: the summon table and live placement (effect-summon.ts). */
+  summon?: SummonEffectEnv;
+  /**
+   * monster_change_shape / monster_revert_shape (game/mon-shape.ts), for
+   * the MON_TMD_CHANGED timer (the SHAPECHANGE monster spell). Built by
+   * wireGame; absent, the timer stands and the form is unchanged.
+   */
+  monShape?: import("../mon/timed.js").MonShapeHooks;
+}
+
+/** Attach a game environment to an effect context for the game handlers. */
+export function attachGameEnv(
+  env: EffectContext,
+  game: GameEffectEnv,
+): EffectContext {
+  return { ...env, game };
+}
+
+/** Read the game env off the context, or null for a worldless interpreter. */
+export function gameEnv(ctx: EffectHandlerContext): GameEffectEnv | null {
+  return (ctx.env.game as GameEffectEnv | undefined) ?? null;
+}