@rpgm-tools/neo-angband-core 0.33.0 → 0.34.0

package/src/mod/hooks.ts

@@ -72,6 +72,7 @@
 
 import type { GameState } from "../game/context.js";
 import type { OptionStateData } from "../player/options.js";
+import type { Chunk } from "../world/chunk.js";
 
 /**
  * A history entry offered to the write seam.
@@ -251,6 +252,52 @@ export interface ModHooks {
    */
   saveNoiseScent?: () => boolean;
 
+  /**
+   * A previously frozen level has been restored as the live level
+   * (session/game.ts' persistent-level and single-combat return paths).
+   *
+   * `frozenAt` is the game turn when the level was put aside and `now` is the
+   * game turn at which it came back.  Both are supplied rather than a rounded
+   * elapsed count: callers that model once-per-world-tick work need the same
+   * boundary calculation as the engine's `turn % 10 === 0` scheduler.
+   *
+   * This is a notification.  Core changes none of the restored level's state
+   * when it is absent, preserving 4.2.6 exactly; a mod may adjust per-level
+   * transient state such as tracking heatmaps.
+   *
+   * Serves: the upstream-catchup mod's post-4.2.6 noise clear and scent aging
+   * (upstream 5c45eb9588b8227d4f1b1998e0a627ad7ee11a75, #4605).
+   */
+  levelRevisited?: (chunk: Chunk, frozenAt: number, now: number) => void;
+
+  /**
+   * Whether a shapechange's obvious flags should be learned directly as
+   * runes (obj/knowledge.ts, shapeLearnOnAssume's per-flag loop, reached from
+   * the EF_SHAPECHANGE handler).
+   *
+   * Return true to learn them directly, ON TOP OF the existing equipment-based
+   * `equipLearnFlag` call rather than instead of it - a flag both the shape and
+   * a worn item carry still fires the worn-item message unchanged. Faithful
+   * core never does this: `shapeLearnOnAssume` only ever learns a shape's
+   * obvious flag through `equipLearnFlag`, which requires a WORN item to carry
+   * the flag too, so a flag the shape alone grants is never learned. That is
+   * the 4.2.6-era gap this mod exists to catalogue, not a bug this port
+   * introduced.
+   *
+   * Core still computes and restricts to the exact SAME obvious-flag set it
+   * always has - `shape.flags` intersected with the OFID_WIELD mask,
+   * `shapeLearnOnAssume`'s existing first two lines. This hook decides only
+   * WHETHER that already-computed set is learned directly, never WHICH flags
+   * are in it, so a mod cannot widen this seam into "learn everything the
+   * shape has" - the same shortcut this project already reverted once for
+   * runes broadly (commit 7970af462, docs/modding/BUG_FIXES.md's "port's own
+   * code" section).
+   *
+   * Serves: the upstream-catchup mod's shape-obvious-flag learning (upstream
+   * c8036c51537942a560e3d7f81749c431bbb4701f).
+   */
+  shapeLearnObviousFlagsDirectly?: () => boolean;
+
   /**
    * Player-visible message text, on its way to the message line (the host's
    * message sink).
@@ -267,9 +314,8 @@ export interface ModHooks {
   /**
    * The player finished changing their options (the '=' menu closed).
    *
-   * A NOTIFICATION, and the only one here: every other hook is asked a question
-   * and its answer changes what the engine does, whereas this one is told a
-   * thing that already happened and core does not read the return value. The
+   * A NOTIFICATION: like levelRevisited, it is told a thing that already
+   * happened and core does not read a return value. The
    * fold is "all-observe" for that reason - there is no answer to pick between,
    * so every contributor simply runs.
    *
@@ -313,8 +359,11 @@ export interface ModHooks {
  *    or over the radius the blast is built from.
  *  - VETO hooks (levelGenerated, artifactCommit, historyAdd) are conjunctive:
  *    every contributor runs and any refusal decides.
- *  - ANY hooks (saveNoiseScent) are disjunctive: one mod asking for the data is
- *    enough, because the data is additive and a second mod cannot object.
+ *  - ANY hooks (saveNoiseScent, shapeLearnObviousFlagsDirectly) are disjunctive:
+ *    one mod asking for the data is enough, because the data is additive and a
+ *    second mod cannot object.
+ *  - NOTIFICATION hooks (optionsChanged, levelRevisited) call every contributor
+ *    in load order.  There is no answer for a later mod to override.
  *
  * WHY THE LAST TWO ARE NOT EXCEPTIONS. "Later wins" answers the question "two
  * mods disagree about one thing - whose answer is used?", and a veto hook is not
@@ -370,6 +419,8 @@ export const MOD_HOOK_FOLDS: Readonly<Record<keyof ModHooks, ModHookFold>> = {
   historyAdd: "all-must-agree",
   historyDisplay: "chained",
   saveNoiseScent: "any-yes",
+  shapeLearnObviousFlagsDirectly: "any-yes",
+  levelRevisited: "all-observe",
   messageText: "chained",
   optionsChanged: "all-observe",
 };
@@ -500,6 +551,22 @@ export function guardModHooks(
     out.saveNoiseScent = (): boolean => guard("saveNoiseScent", () => noise(), false);
   }
 
+  const shapeFlags = hooks.shapeLearnObviousFlagsDirectly;
+  if (shapeFlags) {
+    /* DECLINE, the upstream 4.2.6-era gap this seam exists to let a mod close. */
+    out.shapeLearnObviousFlagsDirectly = (): boolean =>
+      guard("shapeLearnObviousFlagsDirectly", () => shapeFlags(), false);
+  }
+
+  const revisited = hooks.levelRevisited;
+  if (revisited) {
+    /* A throwing observer changes nothing: faithful core resumes the frozen
+     * level as-is, and the host receives the fault. */
+    out.levelRevisited = (chunk, frozenAt, now): void => {
+      guard("levelRevisited", () => revisited(chunk, frozenAt, now), undefined);
+    };
+  }
+
   const text = hooks.messageText;
   if (text) {
     /* The raw message, unrestated - never an empty string, which would silently
@@ -611,6 +678,23 @@ export function composeModHooks(
     out.saveNoiseScent = (): boolean => noise.some((fn) => fn());
   }
 
+  const shapeFlags = list.map((c) => c.shapeLearnObviousFlagsDirectly).filter(isFn);
+  if (shapeFlags.length > 0) {
+    /* One mod asking for direct learning is enough - two mods both wanting the
+     * 4.2.6-era gap closed are not in conflict, they are two mods agreeing. */
+    out.shapeLearnObviousFlagsDirectly = (): boolean => shapeFlags.some((fn) => fn());
+  }
+
+  const revisited = list.map((c) => c.levelRevisited).filter(isFn);
+  if (revisited.length > 0) {
+    /* Like optionsChanged, every contributor observes the same resume event.
+     * The chunk is intentionally live: this seam exists for a mod to update
+     * transient, level-owned state before monsters receive another turn. */
+    out.levelRevisited = (chunk, frozenAt, now): void => {
+      for (const fn of revisited) fn(chunk, frozenAt, now);
+    };
+  }
+
   const text = list.map((c) => c.messageText).filter(isFn);
   if (text.length > 0) {
     out.messageText = (raw): string => text.reduce((s, fn) => fn(s), raw);

package/src/obj/knowledge.ts

@@ -798,11 +798,26 @@ export function equipLearnElement(p: Player, env: RuneEnv, element: number): voi
  * shape_learn_on_assume (L1892): on taking a shape, learn its obvious
  * (OFID_WIELD) flags and its resists, through the same equipment learn
  * calls upstream uses.
+ *
+ * `learnObviousFlagsDirectly` is the ModHooks.shapeLearnObviousFlagsDirectly
+ * seam's resolved answer, threaded in by the caller (effect-general.ts'
+ * EF_SHAPECHANGE handler, the only one with a GameState to read a mod hook
+ * from - this module stays state-free, like the rest of obj/knowledge.ts).
+ * Faithful core passes `false`: a shape's obvious flag is then learned only
+ * through `equipLearnFlag`, which requires a WORN item to also carry the
+ * flag, so a flag the shape alone grants is never learned - the 4.2.6-era
+ * gap upstream's own `c8036c51537942a560e3d7f81749c431bbb4701f` fixed by
+ * learning the same already-computed set directly as runes instead. When
+ * true, this does exactly that IN ADDITION to the existing equipment call
+ * per flag: `playerLearnFlagRune` is a no-op for a flag already learned by
+ * the equipment path, so a flag the shape and a worn item both carry still
+ * fires the worn-item's own message and nothing here duplicates it.
  */
 export function shapeLearnOnAssume(
   p: Player,
   env: RuneEnv,
   shape: import("../player/types.js").Shape,
+  learnObviousFlagsDirectly = false,
 ): void {
   /* Get the shape's obvious flags. */
   const f = shape.flags.clone();
@@ -811,6 +826,7 @@ export function shapeLearnOnAssume(
   /* Learn flags. */
   for (let flag = f.next(FLAG_START); flag !== NO_FLAG; flag = f.next(flag + 1)) {
     equipLearnFlag(p, env, flag);
+    if (learnObviousFlagsDirectly) playerLearnFlagRune(p, env, flag);
   }
 
   /* Learn elements. */

package/src/session/game.ts

@@ -2659,6 +2659,11 @@ function makeChangeLevel(
         state.traps = stash.traps;
         state.known = stash.known;
         if (stash.decoy) state.decoy = stash.decoy;
+        /* A level restored after single combat is the same kind of revisit as
+         * one recovered from birth_levels_persist.  Faithful core leaves every
+         * field untouched; an opt-in mod can update transient per-level state
+         * before the player and its monsters resume. */
+        state.modHooks?.levelRevisited?.(state.chunk, stash.turn, state.turn);
         const back = state.oldGrid ?? state.actor.grid;
         state.actor.grid = back;
         state.chunk.setMon(back, -1);
@@ -2788,6 +2793,12 @@ function makeChangeLevel(
          * the turns the level was frozen (turn - chunk->freeze-turn). */
         restoreMonsters(state, state.turn - stored.turn);
 
+        /* A restored persistent level is live again.  Core deliberately does
+         * nothing here, matching 4.2.6; a mod may observe the exact freeze and
+         * resume turns to update level-owned transient state before any monster
+         * can receive a turn. */
+        state.modHooks?.levelRevisited?.(state.chunk, stored.turn, state.turn);
+
         /* Place the player (prepare_next_level non-arena, L1497-1501): sanitize
          * the retained grid into a legal arrival square, then player_place.
          * DEFERRAL: exact stair-connector matching (dun->persist / one_off_*

package/src/version.ts

@@ -23,4 +23,4 @@ export const PARITY_BASELINE = "4.2.6";
  * released tag is iterated takes a MINOR bump, because a published tag is pinned
  * by digest in a catalogue and must never be moved.
  */
-export const ENGINE_VERSION = "0.33.0";
+export const ENGINE_VERSION = "0.34.0";