@rpgm-tools/neo-angband-core 0.24.0 → 0.26.0

package/README.md

@@ -32,7 +32,7 @@ import { Rng, ENGINE_VERSION, PARITY_BASELINE } from "@rpgm-tools/neo-angband-co
 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.24.0 4.2.6
+console.log(ENGINE_VERSION, PARITY_BASELINE); // 0.26.0 4.2.6
 ```
 
 Two entry points:

package/dist/agent/entity-views.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The two plain-data view builders the perceive facade and the loadout
+ * simulation SHARE: one object as an `ItemView`, and the player as a
+ * `PlayerView`.
+ *
+ * They live in their own module rather than in perceive.ts for one reason.
+ * `agent/loadout.ts` describes a loadout the player is not wearing, and it has
+ * to describe it in the same shape and through the same builders as the live
+ * view - an `ItemView` carrying `value` in one and not the other would change
+ * what an agent decides about the same object depending on which view handed it
+ * over. Having both importers reach the same function is what makes that
+ * structural instead of a convention, and it keeps the import graph one-way
+ * (perceive and loadout both depend on this; neither depends on the other).
+ */
+import type { FlagSet } from "../bitflag.js";
+import type { GameState } from "../game/context.js";
+import type { GameObject } from "../obj/object.js";
+import type { PlayerState } from "../player/calcs.js";
+import type { PlayerCombatState } from "../combat/melee.js";
+import type { AgentViewDeps, ItemView, PlayerView } from "./types.js";
+/** OF_* codes for the set flags in an object-flag FlagSet (OF is 1-indexed). */
+export declare function ofCodes(flags: FlagSet): string[];
+/**
+ * One object as an ItemView. `handle` is 0 for anything not in the gear.
+ *
+ * `count` overrides obj->number for both the reported stack size and the value
+ * quantity. It exists for the hypothetical loadouts in agent/loadout.ts, where
+ * "three of the five potions I am carrying" and "one of the twelve on that
+ * shelf" are real cases and the object itself must not be touched to express
+ * them. Absent, the object's own number is used, which is every live read.
+ */
+export declare function itemView(handle: number, obj: GameObject, state: GameState, deps: AgentViewDeps, count?: number): ItemView;
+/**
+ * The derived facts playerViewFor reads off the live actor, supplied explicitly
+ * so a HYPOTHETICAL loadout can be described in exactly the same shape (see
+ * agent/loadout.ts). Absent, the live values are used, which is the ordinary
+ * perceive path.
+ *
+ * Only the fields a loadout can move are here. Level, experience, gold, grid,
+ * timed status and the rest are properties of the character rather than of what
+ * it is wearing, so a simulated view reports the live ones.
+ */
+export interface PlayerViewDerived {
+    playerState: PlayerState;
+    combat: PlayerCombatState;
+    speed: number;
+    light: number;
+    maxHp: number;
+    maxSp: number;
+}
+/**
+ * Build a PlayerView from the live game, or - with `over` - from a derive for a
+ * loadout the player is not wearing.
+ *
+ * NOTE on `skills`: this is p->skills, the birth-time level-based skill array
+ * (calcSkills), NOT state->skills. It is not a function of the worn loadout, so
+ * a simulated view carries the live one, exactly as the live view does. The full
+ * derived skills, equipment contributions included, are on
+ * DerivedStatsView.skills (player/loadout.ts).
+ */
+export declare function playerViewFor(state: GameState, deps: AgentViewDeps, over?: PlayerViewDerived): PlayerView;
+//# sourceMappingURL=entity-views.d.ts.map

package/dist/agent/entity-views.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-views.d.ts","sourceRoot":"","sources":["../../src/agent/entity-views.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEtE,gFAAgF;AAChF,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAOhD;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,aAAa,EACnB,KAAK,CAAC,EAAE,MAAM,GACb,QAAQ,CAyFV;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,aAAa,EACnB,IAAI,CAAC,EAAE,iBAAiB,GACvB,UAAU,CAoDZ"}

package/dist/agent/entity-views.js

@@ -0,0 +1,195 @@
+/**
+ * The two plain-data view builders the perceive facade and the loadout
+ * simulation SHARE: one object as an `ItemView`, and the player as a
+ * `PlayerView`.
+ *
+ * They live in their own module rather than in perceive.ts for one reason.
+ * `agent/loadout.ts` describes a loadout the player is not wearing, and it has
+ * to describe it in the same shape and through the same builders as the live
+ * view - an `ItemView` carrying `value` in one and not the other would change
+ * what an agent decides about the same object depending on which view handed it
+ * over. Having both importers reach the same function is what makes that
+ * structural instead of a convention, and it keeps the import graph one-way
+ * (perceive and loadout both depend on this; neither depends on the other).
+ */
+import { ELEMENT_ENTRIES, OBJECT_FLAG_ENTRIES, TMD } from "../generated/index.js";
+import { OBJ_MOD_NAMES } from "../obj/bind.js";
+import { objectValue } from "../obj/value.js";
+/** OF_* codes for the set flags in an object-flag FlagSet (OF is 1-indexed). */
+export function ofCodes(flags) {
+    const out = [];
+    for (const f of flags) {
+        const entry = OBJECT_FLAG_ENTRIES[f - 1];
+        if (entry)
+            out.push(entry.name);
+    }
+    return out;
+}
+/**
+ * One object as an ItemView. `handle` is 0 for anything not in the gear.
+ *
+ * `count` overrides obj->number for both the reported stack size and the value
+ * quantity. It exists for the hypothetical loadouts in agent/loadout.ts, where
+ * "three of the five potions I am carrying" and "one of the twelve on that
+ * shelf" are real cases and the object itself must not be touched to express
+ * them. Absent, the object's own number is used, which is every live read.
+ */
+export function itemView(handle, obj, state, deps, count) {
+    const number = count ?? obj.number;
+    const modifiers = [];
+    for (let i = 0; i < obj.modifiers.length; i++) {
+        const value = obj.modifiers[i] ?? 0;
+        if (value === 0)
+            continue;
+        const code = OBJ_MOD_NAMES[i];
+        if (code)
+            modifiers.push({ code, value });
+    }
+    const brands = [];
+    if (obj.brands) {
+        for (let i = 0; i < obj.brands.length; i++) {
+            if (!obj.brands[i])
+                continue;
+            const code = state.brands[i]?.code;
+            if (code)
+                brands.push(code);
+        }
+    }
+    const slays = [];
+    if (obj.slays) {
+        for (let i = 0; i < obj.slays.length; i++) {
+            if (!obj.slays[i])
+                continue;
+            const code = state.slays[i]?.code;
+            if (code)
+                slays.push(code);
+        }
+    }
+    const resists = [];
+    for (let i = 0; i < obj.elInfo.length; i++) {
+        const level = obj.elInfo[i]?.resLevel ?? 0;
+        if (level === 0)
+            continue;
+        const name = ELEMENT_ENTRIES[i]?.name;
+        if (name)
+            resists.push({ element: name, level });
+    }
+    const curses = [];
+    if (obj.curses) {
+        for (let i = 0; i < obj.curses.length; i++) {
+            const power = obj.curses[i]?.power ?? 0;
+            if (power <= 0)
+                continue;
+            /* Curse names resolve from the always-present RuneEnv curse table (real
+             * in production, inert [null] in the worldless harness), then the
+             * optional registry dep, then the numeric index as a last resort. */
+            curses.push(state.runeEnv.curses[i]?.name ??
+                deps.reg?.curses[i]?.name ??
+                String(i));
+        }
+    }
+    const view = {
+        handle,
+        label: obj.kind.name,
+        tval: obj.tval,
+        sval: obj.sval,
+        pval: obj.pval,
+        number,
+        weight: obj.weight,
+        ac: obj.ac,
+        toA: obj.toA,
+        toH: obj.toH,
+        toD: obj.toD,
+        dd: obj.dd,
+        ds: obj.ds,
+        ego: obj.ego !== null,
+        artifact: obj.artifact !== null,
+        flags: ofCodes(obj.flags),
+        modifiers,
+        brands,
+        slays,
+        resists,
+        curses,
+        egoName: obj.ego?.name ?? null,
+        artifactName: obj.artifact?.name ?? null,
+        activation: obj.activation !== null,
+        timeout: obj.timeout,
+        inscription: obj.note ?? null,
+    };
+    if (deps.resolver) {
+        const kindId = deps.resolver.kindIdOrNull(obj.kind.kidx);
+        if (kindId !== null)
+            view.kindId = kindId;
+    }
+    if (deps.reg) {
+        const aware = deps.aware ?? (() => true);
+        view.value = objectValue(deps.reg, obj, number, aware(obj.kind));
+    }
+    return view;
+}
+/**
+ * Build a PlayerView from the live game, or - with `over` - from a derive for a
+ * loadout the player is not wearing.
+ *
+ * NOTE on `skills`: this is p->skills, the birth-time level-based skill array
+ * (calcSkills), NOT state->skills. It is not a function of the worn loadout, so
+ * a simulated view carries the live one, exactly as the live view does. The full
+ * derived skills, equipment contributions included, are on
+ * DerivedStatsView.skills (player/loadout.ts).
+ */
+export function playerViewFor(state, deps, over) {
+    const p = state.actor.player;
+    const combat = over ? over.combat : state.actor.combat;
+    const playerState = over ? over.playerState : state.playerState;
+    const view = {
+        race: p.race.name,
+        cls: p.cls.name,
+        level: p.lev,
+        maxLevel: p.maxLev,
+        exp: p.exp,
+        maxExp: p.maxExp,
+        gold: p.au,
+        depth: state.chunk.depth,
+        maxDepth: p.maxDepth,
+        hp: p.chp,
+        maxHp: over ? over.maxHp : p.mhp,
+        sp: p.csp,
+        maxSp: over ? over.maxSp : p.msp,
+        speed: over ? over.speed : state.actor.speed,
+        /* Displayed AC is state->ac + state->to_a. */
+        ac: combat.ac + combat.toA,
+        toHit: combat.toH,
+        toDam: combat.toD,
+        stats: [...p.statCur],
+        light: over ? over.light : state.actor.light,
+        grid: { x: state.actor.grid.x, y: state.actor.grid.y },
+        status: {
+            blind: p.timed[TMD.BLIND] ?? 0,
+            confused: p.timed[TMD.CONFUSED] ?? 0,
+            afraid: p.timed[TMD.AFRAID] ?? 0,
+            poisoned: p.timed[TMD.POISONED] ?? 0,
+            cut: p.timed[TMD.CUT] ?? 0,
+            stun: p.timed[TMD.STUN] ?? 0,
+            paralyzed: p.timed[TMD.PARALYZED] ?? 0,
+            food: p.timed[TMD.FOOD] ?? 0,
+        },
+        dead: state.isDead,
+        winner: p.totalWinner,
+        skills: [...p.skills],
+        shape: p.shape?.name ?? null,
+        objectFlags: playerState ? ofCodes(playerState.flags) : [],
+        seeInfra: playerState?.seeInfra ?? p.race.infravision,
+        blows: combat.numBlows,
+        shots: combat.numShots,
+    };
+    if (deps.resolver) {
+        const raceId = deps.resolver.playerRaceIdOrNull(p.race.ridx);
+        if (raceId !== null)
+            view.playerRaceId = raceId;
+        const classId = deps.resolver.playerClassIdOrNull(p.cls.cidx);
+        if (classId !== null)
+            view.playerClassId = classId;
+    }
+    return view;
+}
+//# sourceMappingURL=entity-views.js.map

package/dist/agent/entity-views.js.map

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

package/dist/agent/index.d.ts

@@ -8,8 +8,12 @@
  * from here (see types.ts freeze note).
  */
 export { AGENT_API_VERSION, AGENT_STATE_DOMAINS } from "./types.js";
-export type { AgentCapabilities, AgentCommand, AgentActions, AgentGlyphSource, AgentController, AgentSession, AgentView, AgentViewDeps, CellView, ControllerOptions, ItemView, MonsterView, PlayerStatusView, PlayerView, SpellbookView, SpellView, StoreItemView, StoreView, TargetView, } from "./types.js";
+export type { AgentCapabilities, AgentCommand, AgentActions, AgentGlyphSource, AgentController, AgentSession, AgentView, AgentViewDeps, CellView, ControllerOptions, ItemView, LoadoutChange, LoadoutItemRef, LoadoutPlacement, LoadoutSimulation, LoadoutView, MonsterView, PlayerStatusView, PlayerView, SpellbookView, SpellView, StoreItemView, StoreView, TargetView, } from "./types.js";
 export { createAgentView } from "./perceive.js";
+export { itemView, playerViewFor } from "./entity-views.js";
+export type { PlayerViewDerived } from "./entity-views.js";
+export { simulateLoadout } from "./loadout.js";
+export type { LoadoutDerive, LoadoutSimOptions } from "./loadout.js";
 export { createAgentActions } from "./act.js";
 export { AgentCapabilityError, installController } from "./controller.js";
 export { subscribeEvents } from "./events.js";

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

@@ -1 +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,gBAAgB,EAChB,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"}
+{"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,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,SAAS,EACT,aAAa,EACb,QAAQ,EACR,iBAAiB,EACjB,QAAQ,EACR,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,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,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC5D,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACrE,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

@@ -9,6 +9,8 @@
  */
 export { AGENT_API_VERSION, AGENT_STATE_DOMAINS } from "./types.js";
 export { createAgentView } from "./perceive.js";
+export { itemView, playerViewFor } from "./entity-views.js";
+export { simulateLoadout } from "./loadout.js";
 export { createAgentActions } from "./act.js";
 export { AgentCapabilityError, installController } from "./controller.js";
 export { subscribeEvents } from "./events.js";

package/dist/agent/index.js.map

@@ -1 +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;AAsBpE,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"}
+{"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;AA2BpE,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,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/loadout.d.ts

@@ -0,0 +1,97 @@
+/**
+ * What the character would BE, wearing something else.
+ *
+ * ------------------------------------------------------------------
+ * WHY THIS EXISTS
+ * ------------------------------------------------------------------
+ *
+ * `calc_bonuses` (player/calcs.ts) answers "what is this character, in this
+ * gear". Two consumers need the same answer for gear the character is not in:
+ *
+ *  1. An autoplayer deciding whether to wear, buy or sell a thing. Upstream's
+ *     borg does exactly this by WIELDING the candidate, recomputing, and
+ *     reverting (borg-power.c / borg_notice).
+ *  2. A player asking what an item would do for them, which wants the whole
+ *     difference and not a score - which resist went, what happened to mana,
+ *     whether the weapon is now too heavy to swing properly.
+ *
+ * The trap either one falls into alone is summing the item's own bonuses. That
+ * is a second implementation of calc_bonuses, it cannot see the interactions
+ * (the STR ring that changes the blow count, the cuirass that costs a caster
+ * mana, the weight that costs speed), and it drifts from the real derive with
+ * nothing to notice. So this module runs the REAL derive, `update: false`, over
+ * a hypothetical equipment array, and nothing in the live game is written.
+ *
+ * ------------------------------------------------------------------
+ * WHERE THE DERIVE COMES FROM, AND WHY IT IS NOT BUILT HERE
+ * ------------------------------------------------------------------
+ *
+ * `state.derivedFor` is installed by the session (session/game.ts wireGame),
+ * which is the only place that holds the whole calc_bonuses options bag: the
+ * bound timed-effect table and the curse registry travel with it. A derive
+ * assembled here would have to guess at both, and a hypothetical loadout
+ * measured with a thinner bag than the live one is worse than no answer - it
+ * looks like an answer. So an absent `derivedFor` produces null.
+ *
+ * ------------------------------------------------------------------
+ * WHAT IS AND IS NOT MODELLED
+ * ------------------------------------------------------------------
+ *
+ * Modelled: the worn set, per body slot, through the engine's own wield_slot; the
+ * carried weight, because the STR encumbrance penalty reads it and buying heavy
+ * armour is exactly where that bites; max hitpoints (a CON change moves them) and
+ * max mana with the armour encumbrance (a caster's real cost of plate).
+ *
+ * NOT modelled: anything that happens as a CONSEQUENCE of the change rather than
+ * being the change - the gold a purchase costs, an inscription, learning a rune
+ * by wearing the thing. Those are outcomes of the action, not of the loadout, and
+ * a comparison that folded them in would be answering a different question.
+ */
+import type { PlayerState } from "../player/calcs.js";
+import type { GameObject } from "../obj/object.js";
+import type { GameState } from "../game/context.js";
+import type { AgentViewDeps, LoadoutChange, LoadoutSimulation } from "./types.js";
+/** calc_bonuses for a loadout, as GameState.derivedFor supplies it. */
+export type LoadoutDerive = (equipment: readonly (GameObject | null)[], totalWeight?: number) => PlayerState;
+/** What simulateLoadout may be told rather than reading off the state. */
+export interface LoadoutSimOptions {
+    /**
+     * The same AgentViewDeps the live view was built with, so the ItemViews in the
+     * result carry the same `value` / `kindId` fields the live ones do. Omitted
+     * fields degrade exactly as they do in perceive.
+     */
+    viewDeps?: AgentViewDeps;
+    /**
+     * The derive to use. Defaults to `state.derivedFor`, which the session
+     * installs; supply it directly only in a test that has no session.
+     */
+    derive?: LoadoutDerive;
+}
+/**
+ * Derive the character both as it stands and with `change` applied, and diff the
+ * two. Returns null when the state has no `derivedFor` installed (a worldless
+ * harness), because an approximate answer here is indistinguishable from a real
+ * one at every call site.
+ *
+ * PURE: nothing on the GameState, the player, the gear or any object is written.
+ * The derive runs with `update: false`, which is what keeps calc_bonuses' own
+ * faithful side effects (zeroing TMD_FASTCAST on a stun grade) out of it.
+ *
+ * COMPARE AN `after` AGAINST THIS `before`, NEVER AGAINST THE LIVE CHARACTER'S
+ * OWN NUMBERS. Both sides here come out of the same `update: false` derive, and
+ * upstream's calc_bonuses does not answer identically in both modes: its
+ * town-daylight shortcut in calc_light is gated on `update`
+ * (player-calcs.c:1607), so in a daytime town a shadow derive reports the light
+ * radius of the equipment and the live derive reports zero. That is upstream's
+ * asymmetry and the port keeps it.
+ *
+ * MEASURED, 2026-08-21, which is why this paragraph exists: an autoplayer scored
+ * a candidate loadout through this function and compared the result against the
+ * score it had computed from the LIVE view. In a daytime town the two derives
+ * differed by 14000 points of the Borg's own power metric, so every wearable item
+ * looked like an upgrade and it spent 3964 of 4000 decisions swapping one wooden
+ * torch for an identical one. `delta` - or the difference between an `after` and
+ * this `before` - is the quantity a decision wants; an absolute `after` is not.
+ */
+export declare function simulateLoadout(state: GameState, change: LoadoutChange, opts?: LoadoutSimOptions): LoadoutSimulation | null;
+//# sourceMappingURL=loadout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"loadout.d.ts","sourceRoot":"","sources":["../../src/agent/loadout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAOtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,KAAK,EACV,aAAa,EAEb,aAAa,EAGb,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAEpB,uEAAuE;AACvE,MAAM,MAAM,aAAa,GAAG,CAC1B,SAAS,EAAE,SAAS,CAAC,UAAU,GAAG,IAAI,CAAC,EAAE,EACzC,WAAW,CAAC,EAAE,MAAM,KACjB,WAAW,CAAC;AAEjB,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;CACxB;AAqQD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,aAAa,EACrB,IAAI,GAAE,iBAAsB,GAC3B,iBAAiB,GAAG,IAAI,CAkB1B"}