@rpgm-tools/neo-angband-core 1.2.1 → 1.8.0

package/src/mod/hooks.ts

@@ -114,6 +114,24 @@ export interface HistoryDisplayEntry {
   readonly expandUserInput?: true;
 }
 
+/** A newly available player ability, named without exposing a mutable game object. */
+export type AbilityGained =
+  | {
+      readonly kind: "spell";
+      readonly spellIndex: number;
+      readonly name: string;
+      readonly realm: string;
+      /** The host command that opens this spell's casting picker. */
+      readonly command: "cast";
+    }
+  | {
+      readonly kind: "activation";
+      readonly kindIndex: number;
+      readonly name: string;
+      /** The host command that opens the activation picker. */
+      readonly command: "activate";
+    };
+
 /**
  * A mod's behaviour contributions. Every member is optional; an absent member
  * means "this mod does not touch that point" and core takes its faithful path.
@@ -387,6 +405,16 @@ export interface ModHooks {
    * choices past the character they were made on).
    */
   optionsChanged?: (options: OptionStateData) => void;
+
+  /**
+   * The player learned a spell or gained a known activatable item
+   * (spell-cmd.ts, pickup.ts, and obj-cmd.ts). This is a notification: core has already
+   * committed the knowledge and does not read a return value. `command` is the
+   * semantic command a host turns into its current keyset's activation input;
+   * a mod may use it when offering a keymap without guessing which command the
+   * player uses.
+   */
+  abilityGained?: (ability: AbilityGained) => void;
 }
 
 /**
@@ -415,7 +443,7 @@ export interface ModHooks {
  *  - 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
+ *  - NOTIFICATION hooks (optionsChanged, levelRevisited, abilityGained) 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
@@ -478,6 +506,7 @@ export const MOD_HOOK_FOLDS: Readonly<Record<keyof ModHooks, ModHookFold>> = {
   levelRevisited: "all-observe",
   messageText: "chained",
   optionsChanged: "all-observe",
+  abilityGained: "all-observe",
 };
 
 /**
@@ -658,6 +687,13 @@ export function guardModHooks(
     };
   }
 
+  const ability = hooks.abilityGained;
+  if (ability) {
+    out.abilityGained = (gained): void => {
+      guard("abilityGained", () => ability({ ...gained }), undefined);
+    };
+  }
+
   return out;
 }
 
@@ -814,6 +850,13 @@ export function composeModHooks(
     };
   }
 
+  const abilityGained = list.map((c) => c.abilityGained).filter(isFn);
+  if (abilityGained.length > 0) {
+    out.abilityGained = (gained): void => {
+      for (const fn of abilityGained) fn({ ...gained });
+    };
+  }
+
   return out;
 }
 

package/src/mod/registry-host.ts

@@ -328,10 +328,15 @@ export type MenuTransformer = (
   rows: readonly MenuTransformRow[],
 ) => readonly MenuTransformRow[];
 
+/** Code to run after the player selects a mod-owned menu action. */
+export type MenuActionHandler = () => void | Promise<void>;
+
 /** Structural target implemented by the web front end, not by headless core. */
 export interface MenuRegistryTarget {
   register(id: string, transformer: MenuTransformer, owner?: string): void;
   handlerFor(id: string): MenuTransformer | null;
+  /** Add one owned, runnable row to an existing menu. */
+  addAction?(id: string, action: string, label: string, handler: MenuActionHandler, owner?: string): void;
 }
 
 /**
@@ -680,6 +685,16 @@ export interface MenuFacade {
   register(id: string, transformer: MenuTransformer): void;
   /** The currently installed transformer, for layering/wrapping an earlier mod. */
   handlerFor(id: string): MenuTransformer | null;
+  /**
+   * Add a row the host can actually run, rather than merely transforming the
+   * presentation of a row whose action core already knows. `action` is scoped
+   * to this mod, so two mods may both call theirs "backup" without colliding.
+   *
+   * The first supported location is `core:game-menu`, the Escape game menu.
+   * The callback starts directly from the selection gesture, so a browser-only
+   * action such as `ctx.backupFolder.choose()` may still open its folder picker.
+   */
+  addAction(id: "core:game-menu", action: string, label: string, handler: MenuActionHandler): void;
 }
 
 /**
@@ -1608,6 +1623,14 @@ export function createModRegistryHost(
         requireCap(capabilities, "menu");
         return requireTarget(targets.menus, "menu").handlerFor(id);
       },
+      addAction(id, action, label, handler): void {
+        requireCap(capabilities, "menu");
+        const menus = requireTarget(targets.menus, "menu");
+        if (!menus.addAction) {
+          throw new Error("mod registry: menu actions are not available in this game (host did not wire them)");
+        }
+        menus.addAction(id, action, label, handler);
+      },
     },
     tiles: {
       register(filler): void {

package/src/version.ts

@@ -24,4 +24,4 @@ export const PARITY_BASELINE = "4.2.6";
  * warrants, because a published tag is pinned by digest in a catalogue and
  * must never be moved.
  */
-export const ENGINE_VERSION = "1.2.1";
+export const ENGINE_VERSION = "1.8.0";