@rpgm-tools/neo-angband-core 0.10.0

package/LICENSE.md

@@ -0,0 +1,43 @@
+# License
+
+Neo Angband is a derivative work of Angband and retains upstream's dual
+license, as the Angband project asks of its variants (see
+`reference/docs/copying.rst`, which remains the authoritative statement for
+the original code and its assets).
+
+Copyright (c) 1997 Ben Harrison, James E. Wilson, Robert A. Koeneke, and the
+Angband contributors; port code copyright (c) 2026 the Neo Angband
+contributors.
+
+This work is free software; you can redistribute it and/or modify it under
+the terms of either:
+
+a) the GNU General Public License as published by the Free Software
+   Foundation, version 2, or
+
+b) the "Angband licence":
+   This software may be copied and distributed for educational, research,
+   and not for profit purposes provided that this copyright and statement
+   are included in all such copies. Other copyrights may also apply.
+
+## Assets
+
+Asset licenses under `reference/` vary and are NOT all dual-licensed as
+above; see `reference/docs/copying.rst` for the full statements, and
+`packages/web/public/tiles/CREDITS.md` for the four tile packs this port
+actually bundles and the terms each one is bundled under.
+
+The Adam Bolt tiles (any purpose, with or without modification) and David
+Gervais tiles (CC BY 3.0, attribution given in that CREDITS.md) are available
+to tile packs under their own terms. The Shockbolt tile set is a distinct
+case and is **not** bundled: its license grants fee-free distribution *with*
+Angband but withholds modification without the author's permission, and
+withholds use with "other games or projects" absent explicit permission —
+so whether this port may carry it turns on a question only the author can
+settle. CREDITS.md states the grants and the prohibitions in full.
+
+## Mods
+
+Declarative content packs and tile packs are independent works and may be
+licensed as their authors choose. Distributed scripted plugins are safest
+treated as GPLv2 derivatives. See `docs/MODS.md`.

package/README.md

@@ -0,0 +1,80 @@
+# @rpgm-tools/neo-angband-core
+
+The headless game engine behind [Neo Angband](https://github.com/neostryder/neo-angband) —
+a TypeScript port of [Angband](https://angband.github.io/angband/) 4.2.6.
+
+No renderer, no input, no DOM, no filesystem: rules, world, entities, effects,
+generation and the save format, as plain modules. Runs in Node and in a browser.
+
+```bash
+npm install @rpgm-tools/neo-angband-core
+```
+
+## What it is for
+
+Two audiences, and it is worth knowing which one you are:
+
+- **Writing a Neo Angband mod.** A mod's plugin receives the running engine as
+  `ctx.core`, so it never imports this package at runtime — but it wants the
+  **types**, and its tests want a real engine to run against. That is what this
+  package is for.
+- **Building something else on Angband's rules.** A bot, a solver, a simulator, a
+  different front end. The engine is headless on purpose and this is a supported
+  use.
+
+## Quick start
+
+```ts
+import { Rng, ENGINE_VERSION, PARITY_BASELINE } from "@rpgm-tools/neo-angband-core";
+
+// The RNG is upstream's WELL1024a, seeded exactly as Rand_state_init does,
+// so a seed reproduces a sequence across runs, platforms and save/load.
+const rng = new Rng(1234);
+console.log(rng.damroll(3, 6), rng.damroll(3, 6), rng.damroll(3, 6)); // 9 13 8
+
+console.log(ENGINE_VERSION, PARITY_BASELINE); // 0.10.0 4.2.6
+```
+
+Two entry points:
+
+| Import | What it holds |
+| --- | --- |
+| `@rpgm-tools/neo-angband-core` | The engine: rules, world, entities, effects, generation, saves |
+| `@rpgm-tools/neo-angband-core/host` | The `HostIo` seam — the shape of `z-file.c`, for a front end that gives the engine real file and terminal I/O |
+
+## The API is upstream's, deliberately
+
+Neo Angband is an **exact-parity** port: the engine reproduces Angband 4.2.6's
+behaviour, including its warts, and it is verified against the C rather than
+against taste. Two consequences for anyone importing this package:
+
+- **Names follow the C.** `damroll`, `mBonus`, `caveKnown`, `takeHit`,
+  `objectDesc`. If you know `angband/src`, you already know your way around; if
+  you expect a designed-from-scratch API, this is not one.
+- **Bugs are reproduced, not fixed.** Upstream's faults are in here on purpose,
+  with tests pinning them. Fixes live in a separate mod
+  ([neo-angband-mod-bug-fixes](https://github.com/neostryder/neo-angband-mod-bug-fixes)),
+  never in the engine.
+
+**Game data is a separate concern.** This package is the rules; Angband's
+gamedata (monsters, objects, dungeon profiles) is compiled into a content pack
+that the host loads. So `@rpgm-tools/neo-angband-core` on its own can roll dice, run the
+effect interpreter and read a save, but it cannot generate a populated level
+without content handed to it.
+
+## Versioning
+
+`0.9.x` is the pre-release line and the API can change inside it; `1.0.0` is
+reserved for the game's public release. `PARITY_BASELINE` is the upstream release
+the port is verified against and moves independently of `ENGINE_VERSION`.
+
+## Licence
+
+Neo Angband keeps Angband's dual licence, as the Angband project asks of its
+variants: **GNU GPL v2, or the Angband licence**, at your option. npm can only
+carry one SPDX identifier, so the manifest says `GPL-2.0-only` — the more
+restrictive of the two. The full text of both, and what it means for the bundled
+art, is in [LICENSE.md](LICENSE.md).
+
+Angband is the work of Ben Harrison, James E. Wilson, Robert A. Koeneke and the
+Angband contributors. The port is by neostryder / RPGM Tools.

package/dist/agent/act.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The act facade (P7.7): the BORG_AS_MOD section-3 semantic verbs as typed
+ * command builders over the engine's PlayerCommand model, plus set-target as a
+ * direct state action (target.c). The arg keys match what the ported actions
+ * read (game/obj-cmd.ts, spell-cmd.ts, ranged-cmd.ts, cave-cmd.ts): item verbs
+ * carry `handle`, drop adds `quantity`, cast carries `spell`, movement/terrain
+ * verbs carry `dir`.
+ *
+ * Building a command is always legal; whether a code is fully wired in the
+ * engine yet is orthogonal to the contract (several are stubs today and are
+ * completed as the Borg port, P8, drives them). Store verbs emit semantic codes
+ * that the store API binds in P8; they are here so the contract is complete.
+ *
+ * Capability: command:add - enforced per verb when an AgentCapabilities is
+ * supplied (and still at controller install, controller.ts). With no caps (a
+ * trusted in-process host) every verb is granted.
+ */
+import type { GameState } from "../game/context.js";
+import type { AgentActions, AgentCapabilities } from "./types.js";
+/** Build the act facade bound to a live state, gated by the given caps. */
+export declare function createAgentActions(state: GameState, caps?: AgentCapabilities): AgentActions;
+//# sourceMappingURL=act.d.ts.map

package/dist/agent/act.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"act.d.ts","sourceRoot":"","sources":["../../src/agent/act.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAIpD,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAgB,MAAM,YAAY,CAAC;AAgChF,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,SAAS,EAChB,IAAI,CAAC,EAAE,iBAAiB,GACvB,YAAY,CAuDd"}

package/dist/agent/act.js

@@ -0,0 +1,88 @@
+/**
+ * The act facade (P7.7): the BORG_AS_MOD section-3 semantic verbs as typed
+ * command builders over the engine's PlayerCommand model, plus set-target as a
+ * direct state action (target.c). The arg keys match what the ported actions
+ * read (game/obj-cmd.ts, spell-cmd.ts, ranged-cmd.ts, cave-cmd.ts): item verbs
+ * carry `handle`, drop adds `quantity`, cast carries `spell`, movement/terrain
+ * verbs carry `dir`.
+ *
+ * Building a command is always legal; whether a code is fully wired in the
+ * engine yet is orthogonal to the contract (several are stubs today and are
+ * completed as the Borg port, P8, drives them). Store verbs emit semantic codes
+ * that the store API binds in P8; they are here so the contract is complete.
+ *
+ * Capability: command:add - enforced per verb when an AgentCapabilities is
+ * supplied (and still at controller install, controller.ts). With no caps (a
+ * trusted in-process host) every verb is granted.
+ */
+import { targetSetLocation, targetSetMonster } from "../game/target.js";
+import { loc } from "../loc.js";
+import { AgentCapabilityError } from "./types.js";
+/**
+ * Wrap every act verb so it throws AgentCapabilityError unless the caller was
+ * granted "command:add". With no AgentCapabilities (a trusted in-process host)
+ * the facade is returned unchanged - every verb is granted.
+ */
+function gateActions(actions, caps) {
+    if (!caps)
+        return actions;
+    const guard = () => {
+        if (!caps.has("command:add")) {
+            throw new AgentCapabilityError(`agent act: capability "command:add" is not granted`);
+        }
+    };
+    const out = {};
+    for (const [key, fn] of Object.entries(actions)) {
+        out[key] = (...args) => {
+            guard();
+            return fn(...args);
+        };
+    }
+    return out;
+}
+/** Build the act facade bound to a live state, gated by the given caps. */
+export function createAgentActions(state, caps) {
+    const cmd = (code, args) => args ? { code, args } : { code };
+    const dirCmd = (code, dir) => ({ code, dir });
+    const itemCmd = (code, handle) => cmd(code, { handle });
+    const actions = {
+        move: (dir) => dirCmd("walk", dir),
+        melee: (dir) => dirCmd("walk", dir),
+        hold: () => cmd("hold"),
+        rest: () => cmd("rest"),
+        descend: () => cmd("descend"),
+        ascend: () => cmd("ascend"),
+        tunnel: (dir) => dirCmd("tunnel", dir),
+        open: (dir) => dirCmd("open", dir),
+        close: (dir) => dirCmd("close", dir),
+        disarm: (dir) => dirCmd("disarm", dir),
+        quaff: (handle) => itemCmd("quaff", handle),
+        read: (handle) => itemCmd("read", handle),
+        eat: (handle) => itemCmd("eat", handle),
+        wear: (handle) => itemCmd("wield", handle),
+        takeoff: (handle) => itemCmd("takeoff", handle),
+        drop: (handle, number) => cmd("drop", number !== undefined ? { handle, quantity: number } : { handle }),
+        pickup: () => cmd("pickup"),
+        destroy: (handle) => itemCmd("destroy", handle),
+        aimWand: (handle) => itemCmd("aim-wand", handle),
+        zapRod: (handle) => itemCmd("zap-rod", handle),
+        useStaff: (handle) => itemCmd("use-staff", handle),
+        activate: (handle) => itemCmd("activate", handle),
+        fire: (handle) => itemCmd("fire", handle),
+        throw: (handle) => itemCmd("throw", handle),
+        cast: (spell) => cmd("cast", { spell }),
+        setTargetMonster: (midx) => {
+            const mon = state.monsters[midx] ?? null;
+            return targetSetMonster(state, mon);
+        },
+        setTargetLocation: (x, y) => {
+            targetSetLocation(state, loc(x, y));
+        },
+        shopBuy: (index, number) => cmd("shop-buy", number !== undefined ? { index, quantity: number } : { index }),
+        shopSell: (handle, number) => cmd("shop-sell", number !== undefined ? { handle, quantity: number } : { handle }),
+        shopExit: () => cmd("shop-exit"),
+        raw: (code, args) => cmd(code, args),
+    };
+    return gateActions(actions, caps);
+}
+//# sourceMappingURL=act.js.map

package/dist/agent/act.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"act.js","sourceRoot":"","sources":["../../src/agent/act.ts"],"names":[],"mappings":"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"}

package/dist/agent/controller.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The controller seam (P7.7): bind an AgentController as the game's nextCommand
+ * provider. runGameLoop calls state.nextCommand() each time it needs a command
+ * and returns LOOP_STATUS.INPUT when it yields null (game/loop.ts) - that is the
+ * perceive -> think -> act boundary. installController wires a controller into
+ * exactly that seam, hands it a perceive view and the act facade, and taps the
+ * message sink so the view can report "messages since the last decision".
+ *
+ * Capability gating (MOD_LIFECYCLE section 4): a controller must be able to ACT,
+ * so command:add is required at install; when a CapabilitySet is supplied and
+ * lacks it, install throws an author-facing error. Read access is NOT required
+ * as a blanket state:*.read wildcard - that would defeat least privilege for a
+ * controller that legitimately reads only a subset of domains (the sandboxed-
+ * plugin case, W2.1). Reads are gated per domain by the perceive facade (W1.4):
+ * a controller that reads a domain it was not granted throws at read time. With
+ * no CapabilitySet (an in-process trusted host, e.g. the bundled Borg before the
+ * sandbox), everything is granted.
+ *
+ * Determinism (the core-owned one-way ratchet, save-blocks.ts): a controller
+ * that declares nondeterministic:true trips the ratchet once via
+ * onNondeterministic - the runtime flips the save's determinism mode. A
+ * deterministic controller (the procedural Borg) draws only the seeded RNG and
+ * leaves the mode untouched.
+ */
+import type { GameState } from "../game/context.js";
+import type { AgentController, AgentSession, ControllerOptions } from "./types.js";
+export { AgentCapabilityError } from "./types.js";
+/**
+ * Install `controller` as the state's command provider, returning a session with
+ * the live facades and an uninstall that restores the previous provider and
+ * message sink. The controller is invoked at each LOOP_STATUS.INPUT boundary.
+ */
+export declare function installController(state: GameState, controller: AgentController, opts?: ControllerOptions): AgentSession;
+//# sourceMappingURL=controller.d.ts.map

package/dist/agent/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/agent/controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAiB,MAAM,oBAAoB,CAAC;AAInE,OAAO,KAAK,EAEV,eAAe,EACf,YAAY,EACZ,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAkClD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,SAAS,EAChB,UAAU,EAAE,eAAe,EAC3B,IAAI,GAAE,iBAAsB,GAC3B,YAAY,CA6Bd"}

package/dist/agent/controller.js

@@ -0,0 +1,90 @@
+/**
+ * The controller seam (P7.7): bind an AgentController as the game's nextCommand
+ * provider. runGameLoop calls state.nextCommand() each time it needs a command
+ * and returns LOOP_STATUS.INPUT when it yields null (game/loop.ts) - that is the
+ * perceive -> think -> act boundary. installController wires a controller into
+ * exactly that seam, hands it a perceive view and the act facade, and taps the
+ * message sink so the view can report "messages since the last decision".
+ *
+ * Capability gating (MOD_LIFECYCLE section 4): a controller must be able to ACT,
+ * so command:add is required at install; when a CapabilitySet is supplied and
+ * lacks it, install throws an author-facing error. Read access is NOT required
+ * as a blanket state:*.read wildcard - that would defeat least privilege for a
+ * controller that legitimately reads only a subset of domains (the sandboxed-
+ * plugin case, W2.1). Reads are gated per domain by the perceive facade (W1.4):
+ * a controller that reads a domain it was not granted throws at read time. With
+ * no CapabilitySet (an in-process trusted host, e.g. the bundled Borg before the
+ * sandbox), everything is granted.
+ *
+ * Determinism (the core-owned one-way ratchet, save-blocks.ts): a controller
+ * that declares nondeterministic:true trips the ratchet once via
+ * onNondeterministic - the runtime flips the save's determinism mode. A
+ * deterministic controller (the procedural Borg) draws only the seeded RNG and
+ * leaves the mode untouched.
+ */
+import { createAgentView } from "./perceive.js";
+import { createAgentActions } from "./act.js";
+import { AgentCapabilityError } from "./types.js";
+export { AgentCapabilityError } from "./types.js";
+/**
+ * Capabilities every controller needs at install: it must be able to drive
+ * commands. Read access is enforced per domain by the perceive facade at read
+ * time, not required wholesale here (see the file header on least privilege).
+ */
+const REQUIRED_CAPABILITIES = ["command:add"];
+function requireCapabilities(caps) {
+    for (const cap of REQUIRED_CAPABILITIES) {
+        if (!caps.has(cap)) {
+            throw new AgentCapabilityError(`agent controller requires capability "${cap}" - grant it in the mod manifest`);
+        }
+    }
+}
+/** A per-decision message tap: buffer messages, drain them when perceived. */
+function makeMessageBuffer() {
+    let buffer = [];
+    return {
+        push: (text) => {
+            buffer.push(text);
+        },
+        drain: () => {
+            const out = buffer;
+            buffer = [];
+            return out;
+        },
+    };
+}
+/**
+ * Install `controller` as the state's command provider, returning a session with
+ * the live facades and an uninstall that restores the previous provider and
+ * message sink. The controller is invoked at each LOOP_STATUS.INPUT boundary.
+ */
+export function installController(state, controller, opts = {}) {
+    if (opts.capabilities)
+        requireCapabilities(opts.capabilities);
+    if (opts.nondeterministic)
+        opts.onNondeterministic?.();
+    const buffer = makeMessageBuffer();
+    const view = createAgentView(state, buffer, opts.viewDeps, opts.capabilities);
+    const act = createAgentActions(state, opts.capabilities);
+    const prevNextCommand = state.nextCommand;
+    const prevMsg = state.msg;
+    /* Tap the message sink so the view reports messages since the last decision,
+     * while still forwarding to whatever sink was installed (a shell renderer). */
+    state.msg = (text) => {
+        buffer.push(text);
+        prevMsg?.(text);
+    };
+    state.nextCommand = () => controller(view, act);
+    return {
+        view,
+        act,
+        uninstall: () => {
+            state.nextCommand = prevNextCommand;
+            if (prevMsg)
+                state.msg = prevMsg;
+            else
+                delete state.msg;
+        },
+    };
+}
+//# sourceMappingURL=controller.js.map

package/dist/agent/controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.js","sourceRoot":"","sources":["../../src/agent/controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAQlD,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD;;;;GAIG;AACH,MAAM,qBAAqB,GAAG,CAAC,aAAa,CAAU,CAAC;AAEvD,SAAS,mBAAmB,CAAC,IAAuB;IAClD,KAAK,MAAM,GAAG,IAAI,qBAAqB,EAAE,CAAC;QACxC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACnB,MAAM,IAAI,oBAAoB,CAC5B,yCAAyC,GAAG,kCAAkC,CAC/E,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,SAAS,iBAAiB;IACxB,IAAI,MAAM,GAAa,EAAE,CAAC;IAC1B,OAAO;QACL,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE;YACb,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;QACD,KAAK,EAAE,GAAG,EAAE;YACV,MAAM,GAAG,GAAG,MAAM,CAAC;YACnB,MAAM,GAAG,EAAE,CAAC;YACZ,OAAO,GAAG,CAAC;QACb,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAgB,EAChB,UAA2B,EAC3B,OAA0B,EAAE;IAE5B,IAAI,IAAI,CAAC,YAAY;QAAE,mBAAmB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC9D,IAAI,IAAI,CAAC,gBAAgB;QAAE,IAAI,CAAC,kBAAkB,EAAE,EAAE,CAAC;IAEvD,MAAM,MAAM,GAAG,iBAAiB,EAAE,CAAC;IACnC,MAAM,IAAI,GAAG,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IAC9E,MAAM,GAAG,GAAG,kBAAkB,CAAC,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IAEzD,MAAM,eAAe,GAAG,KAAK,CAAC,WAAW,CAAC;IAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC;IAE1B;mFAC+E;IAC/E,KAAK,CAAC,GAAG,GAAG,CAAC,IAAY,EAAQ,EAAE;QACjC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC,CAAC;IAEF,KAAK,CAAC,WAAW,GAAG,GAAyB,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAEtE,OAAO;QACL,IAAI;QACJ,GAAG;QACH,SAAS,EAAE,GAAS,EAAE;YACpB,KAAK,CAAC,WAAW,GAAG,eAAe,CAAC;YACpC,IAAI,OAAO;gBAAE,KAAK,CAAC,GAAG,GAAG,OAAO,CAAC;;gBAC5B,OAAO,KAAK,CAAC,GAAG,CAAC;QACxB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/agent/events.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The capability-gated event-subscription seam (W1.6): a mod subscribes to the
+ * game event bus (events.ts) to react to what happens - turn/level changes,
+ * messages, sound, monster events - the "hooks" half of behavioral modding.
+ *
+ * A subscription wraps a GameEvents bus and checks "event:<name>" (the
+ * capability-model vocabulary, capabilities.ts) before honoring an `on`; an
+ * ungranted event throws AgentCapabilityError, exactly like the perceive/act
+ * facades (W1.4). With no AgentCapabilities (a trusted in-process host) every
+ * event is granted. The bus itself is core's faithful game-event.c port; this
+ * only adds the consent gate a sandboxed plugin (W2.1) needs.
+ */
+import type { GameEventHandler, GameEvents, GameEventType } from "../events.js";
+import type { AgentCapabilities } from "./types.js";
+/** A capability-gated view of the event bus handed to a mod. */
+export interface AgentEventSubscription {
+    /** Subscribe to an event, if "event:<type>" is granted (else throws). */
+    on<K extends GameEventType>(type: K, fn: GameEventHandler<K>): void;
+    /** Unsubscribe a handler (always allowed - dropping a hook needs no grant). */
+    off<K extends GameEventType>(type: K, fn: GameEventHandler<K>): void;
+}
+/**
+ * Build a capability-gated subscription over `bus`. `on` throws
+ * AgentCapabilityError unless "event:<type>" is granted; absent caps grants all.
+ */
+export declare function subscribeEvents(bus: GameEvents, caps?: AgentCapabilities): AgentEventSubscription;
+//# sourceMappingURL=events.d.ts.map

package/dist/agent/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/agent/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAEhF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,gEAAgE;AAChE,MAAM,WAAW,sBAAsB;IACrC,yEAAyE;IACzE,EAAE,CAAC,CAAC,SAAS,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IACpE,+EAA+E;IAC/E,GAAG,CAAC,CAAC,SAAS,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CACtE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,UAAU,EACf,IAAI,CAAC,EAAE,iBAAiB,GACvB,sBAAsB,CAcxB"}

package/dist/agent/events.js

@@ -0,0 +1,31 @@
+/**
+ * The capability-gated event-subscription seam (W1.6): a mod subscribes to the
+ * game event bus (events.ts) to react to what happens - turn/level changes,
+ * messages, sound, monster events - the "hooks" half of behavioral modding.
+ *
+ * A subscription wraps a GameEvents bus and checks "event:<name>" (the
+ * capability-model vocabulary, capabilities.ts) before honoring an `on`; an
+ * ungranted event throws AgentCapabilityError, exactly like the perceive/act
+ * facades (W1.4). With no AgentCapabilities (a trusted in-process host) every
+ * event is granted. The bus itself is core's faithful game-event.c port; this
+ * only adds the consent gate a sandboxed plugin (W2.1) needs.
+ */
+import { AgentCapabilityError } from "./types.js";
+/**
+ * Build a capability-gated subscription over `bus`. `on` throws
+ * AgentCapabilityError unless "event:<type>" is granted; absent caps grants all.
+ */
+export function subscribeEvents(bus, caps) {
+    return {
+        on: (type, fn) => {
+            if (caps && !caps.has(`event:${type}`)) {
+                throw new AgentCapabilityError(`agent events: capability "event:${type}" is not granted`);
+            }
+            bus.on(type, fn);
+        },
+        off: (type, fn) => {
+            bus.off(type, fn);
+        },
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/agent/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/agent/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAWlD;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAe,EACf,IAAwB;IAExB,OAAO;QACL,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE;YACf,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,CAAC;gBACvC,MAAM,IAAI,oBAAoB,CAC5B,mCAAmC,IAAI,kBAAkB,CAC1D,CAAC;YACJ,CAAC;YACD,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACnB,CAAC;QACD,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE;YAChB,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACpB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/agent/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @rpgm-tools/neo-angband-core agent API (P7 phase 7): the frozen perceive/act/controller
+ * facade every agent mod - the bundled Borg (P8) first, third-party and AI
+ * agents after - drives the game through, with no privileged core access.
+ *
+ * See BORG_AS_MOD.md sections 3 and 5 for the contract this realizes. FROZEN at
+ * AGENT_API_VERSION 1.0.0 (ratified 2026-07-14, the P7 -> P8 gate); add-only
+ * from here (see types.ts freeze note).
+ */
+export { AGENT_API_VERSION, AGENT_STATE_DOMAINS } from "./types.js";
+export type { AgentCapabilities, AgentCommand, AgentActions, AgentController, AgentSession, AgentView, AgentViewDeps, CellView, ControllerOptions, ItemView, MonsterView, PlayerStatusView, PlayerView, SpellbookView, SpellView, StoreItemView, StoreView, TargetView, } from "./types.js";
+export { createAgentView } from "./perceive.js";
+export { createAgentActions } from "./act.js";
+export { AgentCapabilityError, installController } from "./controller.js";
+export { subscribeEvents } from "./events.js";
+export type { AgentEventSubscription } from "./events.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACpE,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,SAAS,EACT,aAAa,EACb,QAAQ,EACR,iBAAiB,EACjB,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,SAAS,EACT,aAAa,EACb,SAAS,EACT,UAAU,GACX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC"}

package/dist/agent/index.js

@@ -0,0 +1,15 @@
+/**
+ * @rpgm-tools/neo-angband-core agent API (P7 phase 7): the frozen perceive/act/controller
+ * facade every agent mod - the bundled Borg (P8) first, third-party and AI
+ * agents after - drives the game through, with no privileged core access.
+ *
+ * See BORG_AS_MOD.md sections 3 and 5 for the contract this realizes. FROZEN at
+ * AGENT_API_VERSION 1.0.0 (ratified 2026-07-14, the P7 -> P8 gate); add-only
+ * from here (see types.ts freeze note).
+ */
+export { AGENT_API_VERSION, AGENT_STATE_DOMAINS } from "./types.js";
+export { createAgentView } from "./perceive.js";
+export { createAgentActions } from "./act.js";
+export { AgentCapabilityError, installController } from "./controller.js";
+export { subscribeEvents } from "./events.js";
+//# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAqBpE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/agent/perceive.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The perceive facade (P7.7): build a read-only AgentView over a live GameState,
+ * covering the BORG_AS_MOD section-3 read surface. Every accessor returns fresh
+ * plain data (no references into live engine objects), so the view is read-only
+ * by construction and already serializable across a future sandbox boundary.
+ *
+ * This is the first faithful breadth: player vitals + status, visible monsters,
+ * map cells, carried/worn/floor items, the target, and the per-decision message
+ * stream (fed by the controller's message tap). A second breadth adds object
+ * flags/brands/slays/resists/curses detail on ItemView, store stock, the
+ * class spellbook/spell tables, and namespaced ids (raceId/kindId/featCode) -
+ * every one of the second-breadth fields is behind an optional AgentViewDeps so
+ * the worldless test harness (no resolver/registry/playerState/stores) stays
+ * total: absent deps degrade to [] / false / omission, never a throw.
+ */
+import type { GameState } from "../game/context.js";
+import type { AgentCapabilities, AgentView, AgentViewDeps } from "./types.js";
+export declare function createAgentView(state: GameState, messageBuffer?: {
+    drain(): string[];
+}, deps?: AgentViewDeps, caps?: AgentCapabilities): AgentView;
+//# sourceMappingURL=perceive.d.ts.map

package/dist/agent/perceive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"perceive.d.ts","sourceRoot":"","sources":["../../src/agent/perceive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAaH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAUpD,OAAO,KAAK,EACV,iBAAiB,EACjB,SAAS,EACT,aAAa,EAUd,MAAM,YAAY,CAAC;AAqVpB,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,EAChB,aAAa,CAAC,EAAE;IAAE,KAAK,IAAI,MAAM,EAAE,CAAA;CAAE,EACrC,IAAI,GAAE,aAAkB,EACxB,IAAI,CAAC,EAAE,iBAAiB,GACvB,SAAS,CA2CX"}