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

package/src/agent/perceive.ts

@@ -15,28 +15,25 @@
  */
 
 import {
-  ELEMENT_ENTRIES,
   FEAT,
   MON_RACE_FLAG_ENTRIES,
   MON_SPELL_ENTRIES,
   MON_TMD,
-  OBJECT_FLAG_ENTRIES,
   SQUARE,
-  TMD,
   TRF,
 } from "../generated/index.js";
 import type { FlagSet } from "../bitflag.js";
 import { useFlavorGlyph } from "../visuals/object-glyph.js";
 import type { GameState } from "../game/context.js";
 import { gearGet } from "../game/gear.js";
-import type { GameObject } from "../obj/object.js";
 import { LIGHTING } from "../visuals/tile-prefs.js";
-import { OBJ_MOD_NAMES } from "../obj/bind.js";
-import { objectValue } from "../obj/value.js";
 import { monsterIsVisible } from "../mon/predicate.js";
 import { PY_SPELL, spellChance } from "../player/spell.js";
 import { makeSpellChanceEnv } from "../game/spell-cmd.js";
 import { priceItem } from "../store/price.js";
+import { squareIsDisarmableTrap } from "../game/trap.js";
+import { itemView, playerViewFor } from "./entity-views.js";
+import { simulateLoadout } from "./loadout.js";
 import { AGENT_API_VERSION, AGENT_STATE_DOMAINS, AgentCapabilityError } from "./types.js";
 import type {
   AgentCapabilities,
@@ -45,8 +42,9 @@ import type {
   AgentViewDeps,
   CellView,
   ItemView,
+  LoadoutChange,
+  LoadoutSimulation,
   MonsterView,
-  PlayerView,
   SpellbookView,
   SpellView,
   StoreItemView,
@@ -54,16 +52,6 @@ import type {
   TargetView,
 } from "./types.js";
 
-/** OF_* codes for the set flags in an object-flag FlagSet (OF is 1-indexed). */
-function ofCodes(flags: FlagSet): string[] {
-  const out: string[] = [];
-  for (const f of flags) {
-    const entry = OBJECT_FLAG_ENTRIES[f - 1];
-    if (entry) out.push(entry.name);
-  }
-  return out;
-}
-
 /** RF_* codes for the set flags in a race-flag FlagSet (entry index == RF value). */
 function raceFlagCodes(flags: FlagSet): string[] {
   const out: string[] = [];
@@ -84,155 +72,6 @@ function spellFlagCodes(flags: FlagSet): string[] {
   return out;
 }
 
-function itemView(
-  handle: number,
-  obj: GameObject,
-  state: GameState,
-  deps: AgentViewDeps,
-): ItemView {
-  const modifiers: Array<{ code: string; value: number }> = [];
-  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: string[] = [];
-  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: string[] = [];
-  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: Array<{ element: string; level: number }> = [];
-  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: string[] = [];
-  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: ItemView = {
-    handle,
-    label: obj.kind.name,
-    tval: obj.tval,
-    sval: obj.sval,
-    pval: obj.pval,
-    number: obj.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 ?? ((): boolean => true);
-    view.value = objectValue(deps.reg, obj, obj.number, aware(obj.kind));
-  }
-  return view;
-}
-
-function playerView(state: GameState, deps: AgentViewDeps): PlayerView {
-  const p = state.actor.player;
-  const combat = state.actor.combat;
-  const playerState = state.playerState;
-  const view: PlayerView = {
-    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: p.mhp,
-    sp: p.csp,
-    maxSp: p.msp,
-    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: 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;
-}
-
 function monsterViews(state: GameState, deps: AgentViewDeps): MonsterView[] {
   const out: MonsterView[] = [];
   for (let i = 1; i < state.monsters.length; i++) {
@@ -291,7 +130,11 @@ function cellView(
     monster: c.mon(grid),
     objectCount: (state.floor.get(idx) ?? []).length,
     glow: c.sqinfoHas(grid, SQUARE["GLOW"]),
-    trap: (state.traps.get(idx)?.length ?? 0) > 0,
+    /* square_isdisarmabletrap, not "the trap list is non-empty": a closed door's
+     * lock, a glyph of warding, a web and a decoy are all trap records, and none
+     * of them is a trap the player sees or the disarm command will act on. See
+     * CellView.trap. */
+    trap: squareIsDisarmableTrap(state, grid),
   };
   if (deps.resolver) {
     const code = deps.resolver.featIdOrNull(feat);
@@ -463,7 +306,7 @@ export function createAgentView(
   return {
     apiVersion: AGENT_API_VERSION,
     turn: gateRead(caps, D.turn, () => state.turn),
-    player: gateRead(caps, D.player, () => playerView(state, deps)),
+    player: gateRead(caps, D.player, () => playerViewFor(state, deps)),
     monsters: gateRead(caps, D.monsters, () => monsterViews(state, deps)),
     cell: gateRead(caps, D.map, (x: number, y: number) =>
       cellView(state, x, y, deps),
@@ -500,5 +343,16 @@ export function createAgentView(
     stores: gateRead(caps, D.stores, () => storeViews(state, deps)),
     spellbooks: gateRead(caps, D.spells, () => spellbookViews(state)),
     constants: gateRead(caps, D.constants, () => ({ ...state.z })),
+    /* The same deps as every accessor above, on purpose: an ItemView from a
+     * simulated loadout has to be interchangeable with one from the live pack,
+     * or an agent's decision would depend on which read produced the object.
+     * Gated on the player domain, since what it answers is a question about the
+     * player. */
+    simulateLoadout: gateRead(
+      caps,
+      D.player,
+      (change: LoadoutChange): LoadoutSimulation | null =>
+        simulateLoadout(state, change, { viewDeps: deps }),
+    ),
   };
 }

package/src/agent/types.ts

@@ -48,8 +48,17 @@ import type { ObjectKind } from "../obj/types.js";
  * an agent could not see the map the player sees, and the invented table would
  * drift from the gamedata with nothing to notice. Purely additive - every
  * field is absent without the dep, exactly as `featCode` is without a resolver.
+ *
+ * 1.2.0 (2026-08-21): `AgentView.simulateLoadout` and the `LoadoutChange` /
+ * `LoadoutSimulation` shapes it speaks in. Added because the view could describe
+ * the character it HAS and nothing else, so every decision of the form "would
+ * this item be better than the one I am wearing" had to be answered by summing
+ * the item's own bonuses - a second implementation of calc_bonuses, guaranteed to
+ * drift from the first. The accessor runs the engine's own derive over a
+ * hypothetical set of worn objects. Purely additive, and optional: a view that
+ * cannot derive omits it rather than answering approximately.
  */
-export const AGENT_API_VERSION = "1.1.0";
+export const AGENT_API_VERSION = "1.2.0";
 
 /**
  * A command an agent emits - identical to the engine's PlayerCommand (codes 1:1
@@ -231,7 +240,21 @@ export interface CellView {
   objectCount: number;
   /** SQUARE_GLOW: the square is self-illuminating. */
   glow: boolean;
-  /** A live trap pile occupies this square. */
+  /**
+   * `square_isdisarmabletrap` (cave-square.c:832): the square holds a VISIBLE
+   * player trap that is not already disabled - the same predicate the `disarm`
+   * command tests before it will spend a turn, and the same one the trap layer
+   * draws from.
+   *
+   * NOT "any trap record exists", which is what this reported until 0.25.1. The
+   * trap list is also where a closed door's lock lives (`square_set_door_lock`
+   * stores a "door lock" trap, flagged LOCK | INVISIBLE) and where a glyph of
+   * warding, a web and a decoy live. None of those is a trap a player can see or
+   * disarm, so reporting them here contradicted this view's own rule that an
+   * invisible trap is not in the view (see `trapGlyph`) - and it put a locked
+   * door in front of an agent as something to disarm, which `disarm` then
+   * refuses for free.
+   */
   trap: boolean;
   /** Namespaced terrain-feature id, when a ContentIdResolver dep is supplied
    * and the feature index is bound (never present for an unset sentinel). */
@@ -372,6 +395,130 @@ export interface TargetView {
  * The perceive facade: a read-only view of the world. Every accessor returns
  * fresh plain data (no live engine references). Capability: state:*.read.
  */
+/* ------------------------------------------------------------------ *
+ * PERCEIVE - a loadout the player is NOT wearing.
+ * ------------------------------------------------------------------ */
+
+/**
+ * Where one item in a hypothetical loadout comes from.
+ *
+ * Three arms because the three questions have three different answers to "which
+ * object is this". Something the character already has is a gear handle, which
+ * is what every other item verb takes. A ware in a shop is NOT in the gear at
+ * all, so it has no handle - `StoreItemView.index` inside `view.stores()[n]` is
+ * its only address, and pricing a purchase is one of the two decisions this
+ * whole capability exists for. The third arm is for a caller INSIDE the engine
+ * that is holding the object itself (a floor pile, a freshly rolled drop, a
+ * character-sheet comparison); an agent driving the frozen view has no
+ * GameObject and will never use it.
+ */
+export type LoadoutItemRef =
+  /** Something already in the gear, worn or packed. */
+  | { readonly from: "gear"; readonly handle: number }
+  /** Store stock: `store` indexes view.stores(), `index` the ware in it. */
+  | { readonly from: "store"; readonly store: number; readonly index: number }
+  /** An object in hand (engine-internal callers only). */
+  | { readonly from: "object"; readonly object: import("../obj/object.js").GameObject };
+
+/**
+ * A hypothetical change to what the character carries and wears.
+ *
+ * Every field is optional and they compose, applied in the order
+ * release -> remove -> wield -> carry, so "sell the ring I am wearing and put on
+ * this one instead" is one change rather than two simulations. An empty change
+ * derives the loadout the character is already in, which is what makes `before`
+ * and `after` comparable rather than two different derives.
+ */
+export interface LoadoutChange {
+  /**
+   * Wear or wield these, each routed to the body slot wield_slot picks for its
+   * tval (a ring goes to the first EMPTY ring slot, else the first ring slot).
+   * Whatever was in the slot moves to the pack. An item from `store` or
+   * `object` is being ACQUIRED, so its weight joins the carried total.
+   */
+  readonly wield?: readonly LoadoutItemRef[];
+  /**
+   * Take these into the pack without wearing them - a purchase of something the
+   * character will carry rather than wield. `number` defaults to the whole
+   * stack the reference names.
+   */
+  readonly carry?: readonly {
+    readonly item: LoadoutItemRef;
+    readonly number?: number;
+  }[];
+  /**
+   * Empty these body slots. What is worn there goes into the pack, so the
+   * carried weight does not change - this is taking something off, not
+   * getting rid of it.
+   */
+  readonly remove?: readonly number[];
+  /**
+   * Give these up entirely: a sale, or a drop. `number` defaults to the whole
+   * stack. A handle that names WORN gear empties its slot on the way out, so a
+   * caller pricing "sell the amulet I have on" does not have to remove it first.
+   */
+  readonly release?: readonly {
+    readonly handle: number;
+    readonly number?: number;
+  }[];
+}
+
+/** Where one wielded item landed, and what it pushed out of that slot. */
+export interface LoadoutPlacement {
+  /** The body slot index, as `equipment()` is indexed. */
+  readonly slot: number;
+  /** The item now in the slot. */
+  readonly worn: ItemView;
+  /** What was in the slot before, or null when it was empty. */
+  readonly displaced: ItemView | null;
+}
+
+/** One complete loadout: what is worn and carried, and what it derives to. */
+export interface LoadoutView {
+  /**
+   * The player as `player()` would report them wearing this loadout. Every
+   * derived field (speed, ac, toHit, toDam, blows, shots, light, seeInfra,
+   * objectFlags, maxHp, maxSp) is this loadout's; the rest of the character is
+   * unchanged.
+   */
+  readonly player: PlayerView;
+  /** Worn equipment by body slot; null for an empty slot. */
+  readonly equipment: readonly (ItemView | null)[];
+  /** The pack this loadout leaves behind, in pack order. */
+  readonly inventory: readonly ItemView[];
+  /**
+   * The WHOLE derived surface for this loadout - every field of upstream's
+   * player_state, plus max hitpoints, max mana, armour encumbrance and the
+   * carried weight. This is the deep answer; `player` is the frozen-contract
+   * projection of the same derive.
+   */
+  readonly stats: import("../player/loadout.js").DerivedStatsView;
+}
+
+/**
+ * The answer to "what would this loadout do for me": the character as it stands,
+ * the character with the change applied, and the difference between them.
+ *
+ * A BEFORE/AFTER/DELTA TRIPLE rather than a score, and deliberately. An
+ * autoplayer reduces it to one number and a player wants to see which resist was
+ * traded for which; a scalar can serve the first and never the second, and the
+ * two must not be allowed to disagree about the underlying derive.
+ */
+export interface LoadoutSimulation {
+  readonly before: LoadoutView;
+  readonly after: LoadoutView;
+  readonly delta: import("../player/loadout.js").DerivedStatsDelta;
+  /** Where each wielded item landed (empty when the change wields nothing). */
+  readonly placements: readonly LoadoutPlacement[];
+  /**
+   * References the change named that resolved to no object: a stale handle, a
+   * store index past the end of the stock, a shop number with no shop. They are
+   * SKIPPED rather than thrown for, and reported here, because a decision ladder
+   * evaluating a hundred candidates must not die on one stale handle.
+   */
+  readonly unresolved: readonly LoadoutItemRef[];
+}
+
 export interface AgentView {
   readonly apiVersion: string;
   /** The int32 game-turn counter. */
@@ -398,6 +545,23 @@ export interface AgentView {
   spellbooks(): SpellbookView[];
   /** A plain clone of the bound game constants (z_info). */
   constants(): GameConstants;
+  /**
+   * What the character would derive to wearing a DIFFERENT loadout: the same
+   * calc_bonuses the engine runs for the real one, over a hypothetical set of
+   * worn objects, with nothing in the live game touched.
+   *
+   * This is the read that had no answer at all. Every other accessor here
+   * reports the character as it is, so an agent deciding whether to wear, buy or
+   * sell something had to sum the item's own bonuses itself - which is a second
+   * implementation of calc_bonuses, and one that would drift from the first.
+   *
+   * OPTIONAL, and null-returning, for the honest reason: the derive needs the
+   * session's own calc_bonuses options (the bound timed table, the curse
+   * registry), so a view over a worldless harness cannot answer and says so
+   * rather than deriving a thinner state that would look like an answer.
+   * Capability: `state:player.read`.
+   */
+  simulateLoadout?(change: LoadoutChange): LoadoutSimulation | null;
 }
 
 /**

package/src/game/context.ts

@@ -407,6 +407,24 @@ export interface GameState {
    * "nothing is known", exactly as an absent playerState does.
    */
   knownPlayerState?: import("../player/calcs.js").PlayerState;
+  /**
+   * calc_bonuses for a loadout the player is NOT wearing: the derive behind
+   * "what would this item do for me". Installed by wireGame, which is the only
+   * place holding the whole options bag the live refresh uses (the bound timed
+   * table and the curse registry), so a caller cannot end up measuring a
+   * hypothetical loadout with a thinner derive than the real one.
+   *
+   * `equipment` is indexed by body slot, exactly as CalcBonusesOptions.equipment
+   * is; `totalWeight` is the burden that loadout would carry (omit to keep the
+   * player's current one). Runs with update=false, so it has no side effects.
+   *
+   * Absent in the worldless harness, and simulateLoadout (agent/loadout.ts)
+   * answers null rather than deriving a thinner state of its own.
+   */
+  derivedFor?: (
+    equipment: readonly (import("../obj/object.js").GameObject | null)[],
+    totalWeight?: number,
+  ) => import("../player/calcs.js").PlayerState;
   /**
    * player->upkeep->health_who (health_track reduced to the tracked
    * monster; the health-bar redraw rides presentation, #25).

package/src/index.ts

@@ -84,6 +84,7 @@ export * from "./player/options-file.js";
 export * from "./player/bind.js";
 export * from "./player/player.js";
 export * from "./player/calcs.js";
+export * from "./player/loadout.js";
 export * from "./player/timed.js";
 export * from "./player/take-hit.js";
 export * from "./player/spell.js";

package/src/mod/registry-host.ts

@@ -374,6 +374,11 @@ export interface TileFillPack {
  * atlas has no spare cell to put a variant in, and even a loose pack cannot
  * recolour a donor it does not own the asset for - so a filler that wants a
  * plain copy instead has to say so.
+ *
+ * `transform` is the second, on the same terms: give me a tile that draws
+ * `donor`'s asset mirrored, or with its colours replaced from a ramp I hand
+ * over, or both. Which donor, which way round and which colours are all the
+ * caller's - see TileTransform.
  */
 export interface TileFill {
   /** The pack being filled. */
@@ -388,8 +393,96 @@ export interface TileFill {
   fillObject(kidx: number, tile: TileAtlas): boolean;
   /** A tile drawing `donor`'s asset with its hue rotated, or null if impossible. */
   derive(donor: TileAtlas, hue: number): TileAtlas | null;
+  /**
+   * A tile drawing `donor`'s asset mirrored and/or palette-swapped, or null if
+   * impossible - the same three refusals `derive` has, for the same reasons.
+   */
+  transform(donor: TileAtlas, spec: TileTransform): TileAtlas | null;
+}
+
+/** One replacement colour in a palette remap: red, green, blue, each 0-255. */
+export type TileRampColour = readonly [number, number, number];
+
+/**
+ * How a transformed tile differs from the donor whose picture it draws.
+ *
+ * A PALETTE REMAP RATHER THAN A HUE ROTATION, and the two are not variants of
+ * one idea. `derive`'s rotation asks "the same picture, turned": it keeps the
+ * donor's own colours and moves them around the wheel, which is why it is a
+ * no-op on grey. A ramp remap asks for a DIFFERENT palette: every pixel is
+ * indexed into the ramp by its luminance and replaced by the colour that index
+ * names, so the result is in the caller's colours whatever the donor's were,
+ * grey donors included. Alpha is carried through untouched, so the silhouette
+ * is the donor's exactly.
+ *
+ * Fewer ramp entries read as flatter and more stylised; more preserve the
+ * donor's shading. Two is a hard duotone. The caller picks, because how
+ * stylised somebody's art should look is taste and the engine has none.
+ *
+ * A ramp of nothing (or of one colour) is not a palette, so it is treated as
+ * "no colour change" and only `mirror` applies. A transform that asks for
+ * neither is refused, the same way a rotation of nothing is: it would allocate
+ * a tile indistinguishable from its donor.
+ */
+export interface TileTransform {
+  /** Mirror the picture horizontally. */
+  readonly mirror: boolean;
+  /**
+   * Replacement colours, DARKEST FIRST.
+   *
+   * There is a cap on how many, and it lives with the DOOR rather than here
+   * (`TILE_RAMP_MAX`, the front end's tile-registry) because the reason for it is
+   * the front end's: it caches one image per distinct spec, so what bounds a ramp
+   * is what bounds that cache. Core describes the shape; the front end that pays
+   * for it sets the limit.
+   */
+  readonly ramp: readonly TileRampColour[];
 }
 
+/**
+ * What a player-tile provider is told about the character it is drawing.
+ *
+ * DELIBERATELY NOT THE PLAYER RECORD. A provider decides what picture to show,
+ * and the five facts below are what any such decision can be made from; handing
+ * over the live `Player` would make every field of it part of this contract and
+ * let a render-time hook mutate the character. Names rather than indices,
+ * because a mod's rule is written against "Druid", not against cidx 2, and an
+ * index moves when a content mod inserts a class.
+ */
+export interface PlayerTileView {
+  /**
+   * The current shape's name ("fox", "werewolf", ...), or null in the normal
+   * shape. Exactly player_is_shapechanged's question, answered with which shape.
+   */
+  readonly shape: string | null;
+  /** player->lev, 1 to PY_MAX_LEVEL. */
+  readonly level: number;
+  /** The character's class name (player.cls.name). */
+  readonly cls: string;
+  /** The character's race name (player.race.name). */
+  readonly race: string;
+}
+
+/**
+ * A mod's player-tile provider: which tile the PLAYER's own cell draws.
+ *
+ * WHY THIS IS NOT A FILL. The player is race 0 in the monster tile table
+ * (grid_data_as_text's is_player branch reads that slot for both the colour and
+ * the character), and every tile set the game ships assigns it - so there is no
+ * blank for `fillMonster` to write into, and there should not be: the pack's
+ * player picture is the pack author's work. This asks a different question,
+ * once per frame rather than once per map build: given who the character is
+ * right now, is there a tile that fits better than the standing one? Null means
+ * no, and the pack's own player tile is drawn, which is what happens with no
+ * provider installed at all.
+ *
+ * It runs inside the render path, so it must be a lookup and not a computation:
+ * allocate whatever tiles the answers need during the fill (where `transform`
+ * lives) and read the table here. A provider that throws loses its answer for
+ * that frame and nothing else.
+ */
+export type PlayerTileProvider = (view: PlayerTileView) => TileAtlas | null;
+
 /**
  * A mod's tile filler: supply tiles for content this pack does not draw.
  *
@@ -407,6 +500,7 @@ export type TileFiller = (fill: TileFill) => void;
 /** Structural target implemented by the web front end, not by headless core. */
 export interface TileRegistryTarget {
   register(filler: TileFiller, owner?: string): void;
+  player(provider: PlayerTileProvider, owner?: string): void;
 }
 
 /** The effect-override facade (gated by registry:effect). */
@@ -573,6 +667,13 @@ export interface MenuFacade {
 export interface TilesFacade {
   /** Install (or replace) this mod's tile filler. */
   register(filler: TileFiller): void;
+  /**
+   * Install (or replace) this mod's player-tile provider. One per mod for the
+   * same reason as the filler, and first non-null in load order wins - so a
+   * provider that answers null for everything it has no opinion about leaves
+   * the next mod's answer, and the pack's own tile, both reachable.
+   */
+  player(provider: PlayerTileProvider): void;
 }
 
 /** The monster-AI facade (gated by registry:monster). */
@@ -1490,6 +1591,13 @@ export function createModRegistryHost(
         }
         requireTarget(targets.tiles, "tiles").register(filler);
       },
+      player(provider): void {
+        requireCap(capabilities, "tiles");
+        if (typeof provider !== "function") {
+          throw new Error("mod registry: a player-tile provider must be a function");
+        }
+        requireTarget(targets.tiles, "tiles").player(provider);
+      },
     },
   };
 }

package/src/player/calcs.ts

@@ -644,6 +644,15 @@ export interface CalcBonusesOptions {
    * exactly as upstream. Absent (the live refresh path), no shift is applied.
    */
   statIndBoost?: { str: number; dex: number };
+  /**
+   * p->upkeep->total_weight (the "Analyze weight" block, 2222-2230), in tenth
+   * pounds. Defaults to the player's own carried weight, which is the live
+   * answer. A HYPOTHETICAL loadout supplies the weight it would carry instead:
+   * wearing something already in the pack changes nothing, but buying a mail
+   * shirt adds its weight and can cost speed, and a derive that read the current
+   * burden would miss exactly that.
+   */
+  totalWeight?: number;
   /**
    * p->depth (calc_light town-daytime early-out, 1607). Defaults to undefined,
    * treated as a nonzero depth so the town branch stays dormant.
@@ -712,6 +721,18 @@ function calcLight(
      calc_light sets p->upkeep->update |= (PU_UPDATE_VIEW | PU_MONSTERS) when
      the town light changes (1608-1611), and the port has no dirty-flag pipeline
      to set: the front end recomputes and repaints after every action. */
+  /* GATED ON `update`, exactly as upstream gates it (player-calcs.c:1607 -
+   * `if (!p->depth && is_daytime() && update)`). So a SHADOW derive computes
+   * cur_light from the equipment even in a lit town, and the live derive reports
+   * zero. That asymmetry is upstream's, and it is a wart the port keeps.
+   *
+   * WHAT IT COSTS, because it was measured and is worth knowing: a consumer that
+   * compares a shadow derive's score against the LIVE derive's score is comparing
+   * two different answers, and in a daytime town the gap is a whole torch's light
+   * radius. `simulateLoadout` derives both of its sides through this same shadow
+   * path, so its own `before` / `after` / `delta` are consistent; the baseline to
+   * compare an `after` against is that `before`, never the live score. See
+   * agent/loadout.ts. */
   const depth = options.depth;
   const update = options.update ?? true;
   if (depth === 0 && (options.isDaytime ?? false) && update) {
@@ -1289,7 +1310,7 @@ export function calcBonuses(
   }
 
   /* Analyze weight (2222-2230). */
-  const j = player.upkeep.totalWeight;
+  const j = options.totalWeight ?? player.upkeep.totalWeight;
   const limit = weightLimit(state);
   if (j > Math.trunc(limit / 2)) {
     state.speed -=