@rpgm-tools/neo-angband-core 0.10.0

package/dist/game/obj-cmd.js

@@ -0,0 +1,1530 @@
+/**
+ * Object commands, ported from reference/src/cmd-obj.c (Angband 4.2.6) with
+ * the obj-gear.c inventory verbs they sit on: take off / wield / drop, and
+ * the use family (eat, quaff, read, use staff, aim wand, zap rod, activate)
+ * running each object's effect chain through the effect interpreter with a
+ * player source - the same stack monster spells cast through.
+ *
+ * Knowledge rides on the ported FlavorKnowledge (obj/knowledge.ts):
+ * unaware flavored items aim at random when they secretly need a direction,
+ * single-use items learn their flavor on use, devices are marked tried.
+ * The deeper known-object bookkeeping (obj->known twins, work_obj copies
+ * for messaging) is knowledge/UI work (#24/#25) and is replaced by hooks.
+ *
+ * Inscribe/uninscribe/refill (fuel) are ported below (cmd-obj.c
+ * do_cmd_inscribe/do_cmd_uninscribe/do_cmd_refill + refill_lamp,
+ * obj-util.c obj_can_refill/obj_has_inscrip). Autoinscribe
+ * (do_cmd_autoinscribe/apply_autoinscription) applies the per-kind
+ * note_aware/note_unaware registry (obj/knowledge.ts AutoinscriptionRegistry,
+ * wired through ObjCmdDeps.autoNote by session/game.ts). The separate
+ * rune-based autoinscription (runes_autoinscribe, obj-ignore.c L217) rides the
+ * rune knowledge system and stays deferred (#24).
+ *
+ * DEFERRED with their subsystems (ledgered in game-obj-cmd.yaml):
+ * cast/study (player spells #22), the glyph-of-warding push_object
+ * interaction (traps #21), command repetition, and the !t take-off
+ * confirmation prompt (get_check, UI).
+ */
+import { EFFECT_ENTRIES, EQUIP_SLOT_ENTRIES, OF, TMD } from "../generated/index.js";
+import { DDD } from "../loc.js";
+import { SKILL } from "../player/types.js";
+import { EffectBuilder } from "../effects/effect.js";
+import { sourcePlayer } from "../effects/interpreter.js";
+import { objectPackTotal, tvalIsEdible, tvalIsFuel, tvalIsLauncher, tvalIsLight, tvalIsMeleeWeapon, tvalIsPotion, tvalIsRing, tvalIsRod, tvalIsScroll, tvalIsStaff, tvalIsWand, tvalIsWearable, tvalCanHaveCharges, tvalCanHaveTimeout, } from "../obj/object.js";
+import { FlavorKnowledge, NOOP_FLAVOR_AWARE_DEPS, buildRuneList, objectHasRune, playerKnowsRune, } from "../obj/knowledge.js";
+import { ignoreItemOk } from "../obj/ignore.js";
+import { dropNear, floorObjectForUse, floorPile } from "./floor.js";
+import { calcInventory, combinePack, gearGet, gearObjectForUse, gearToLabel, invenCarry, invenCarryNum, objectSplit, packIsOverfull, packTotalSuppressed, packTotalView, wieldObject, wieldSlot, } from "./gear.js";
+import { checkForInscrip } from "./pickup.js";
+import { disturb } from "./player-path.js";
+import { buildEffectContext } from "./effect-env.js";
+import { attachGameEnv } from "./effect-game-env.js";
+import { describeObject } from "./describe.js";
+import { ODESC, objDescNameFormat } from "../obj/desc.js";
+import { substituteTimedMessage } from "../player/timed.js";
+import { squareIsSeen } from "../world/view.js";
+import { updatePlayerObjectKnowledge } from "./known.js";
+import { targetFix, targetGet, targetOkay, targetRelease } from "./target.js";
+/** enum use (cmd-obj.c). */
+export const USE = { TIMEOUT: 0, CHARGE: 1, SINGLE: 2 };
+/** Build calc_inventory options from the object-command deps (gap 4.1). */
+function calcInvOpts(state, deps) {
+    const o = {
+        /* object_is_equipped(p->body, old_pack[i]) (player-calcs.c:1227): wielding
+         * an item moves it out of the pack, which must not read as a re-arrangement.
+         * This is the path where that happens, so the predicate belongs here. */
+        isEquipped: (handle) => state.actor.player.equipment.includes(handle),
+    };
+    if (deps.env?.msg)
+        o.msg = deps.env.msg;
+    if (deps.rogueLike)
+        o.rogueLike = deps.rogueLike;
+    if (deps.characterDungeon)
+        o.characterDungeon = deps.characterDungeon;
+    const at = deps.ammoTval?.() ?? state.playerState?.ammoTval;
+    if (at !== undefined)
+        o.ammoTval = at;
+    if (deps.objectValue)
+        o.objectValue = deps.objectValue;
+    return o;
+}
+/**
+ * The combine_pack / pack_overflow seams for the command handlers: the message
+ * sink, the calc_inventory inputs, and the drop_near environment
+ * pack_overflow's drop needs (deps.floorEnv is the same one inven_drop uses).
+ */
+function packOpts(state, deps) {
+    const o = { calcInv: calcInvOpts(state, deps) };
+    if (deps.env?.msg)
+        o.msg = deps.env.msg;
+    if (deps.floorEnv)
+        o.floorEnv = deps.floorEnv;
+    return o;
+}
+function stackLimits(constants) {
+    return {
+        quiverSlotSize: constants.quiverSlotSize,
+        thrownQuiverMult: constants.thrownQuiverMult,
+    };
+}
+/* ------------------------------------------------------------------ *
+ * obj-gear.c inventory verbs.
+ * ------------------------------------------------------------------ */
+/**
+ * inven_takeoff (obj-gear.c L1033): de-equip an object back into the pack.
+ * Returns whether the handle was equipped. (Upstream does not re-combine;
+ * the caller runs combine_pack, which the port's pack model does lazily on
+ * the next inven_carry.)
+ */
+export function invenTakeoff(state, handle) {
+    const player = state.actor.player;
+    const slot = player.equipment.indexOf(handle);
+    if (slot < 0)
+        return false;
+    player.equipment[slot] = 0;
+    state.gear.pack.push(handle);
+    state.updateBonuses?.(); /* PU_BONUS */
+    return true;
+}
+/** calcInv with the shared msg sink filled in when the caller left it out. */
+function overflowCalcInv(opts) {
+    const base = { ...opts.calcInv };
+    if (!base.msg && opts.msg)
+        base.msg = opts.msg;
+    return base;
+}
+/**
+ * pack_overflow (obj-gear.c L1345-1390): when the pack holds more than
+ * pack_size slots, shed one item onto the floor. `handle` is upstream's `obj`
+ * argument - the item to shed, normally whatever displaced into the pack; 0 is
+ * upstream's NULL, meaning "shed the last item of the inventory listing".
+ * Returns the object that left the pack, or null when nothing overflowed.
+ *
+ * The C's three messages and their order are reproduced exactly: the warning,
+ * then "You drop X." with X described BEFORE the excise, then the drop, then
+ * "You no longer have X."
+ *
+ * For the NULL case, upkeep->inven[] is represented by the derived,
+ * earlier_object-sorted gear.inven view (player-calcs.c:1191-1222); gear.pack
+ * remains the raw master-gear order and must not select the victim.
+ */
+export function packOverflow(state, handle, constants, opts = {}) {
+    /* packSlotsUsed's public Constants type includes unrelated z_info fields;
+     * only the PackOverflowConstants subset is read on this path. */
+    if (!packIsOverfull(state.gear, constants))
+        return null;
+    /* Disturbing (L1353). */
+    disturb(state);
+    /* Warning (L1356). */
+    opts.msg?.("Your pack overflows!");
+    /* Drop the last inventory item unless requested otherwise (L1359-1366). */
+    const victim = handle !== 0
+        ? handle
+        : (state.gear.inven?.[state.gear.inven.length - 1] ?? 0);
+    const obj = gearGet(state.gear, victim);
+    /* Upstream asserts obj != NULL here (L1369). The port can reach a stale
+     * handle where upstream reads freed memory: combine_pack (which runs just
+     * before every caller's pack_overflow) may have absorbed the displaced item
+     * into an earlier stack, which upstream frees while still holding the
+     * pointer. Absorbing shrinks the pack, so an overfull pack with a stale
+     * handle is a corner the C does not define; the port sheds nothing. */
+    if (!obj)
+        return null;
+    /* Describe (L1372-1374) BEFORE the excise, so the count is the pre-drop one. */
+    const name = describeObject(state, obj);
+    /* Message (L1377). */
+    opts.msg?.(`You drop ${name}.`);
+    /* Excise the object and drop it (carefully) near the player (L1379-1380).
+     * gear_excise_object re-runs calc_inventory (obj-gear.c L497). */
+    const { obj: dropped } = gearObjectForUse(state.gear, state.actor.player, victim, obj.number);
+    calcInventory(state.gear, constants, overflowCalcInv(opts));
+    /* drop_near(cave, &obj, 0, player->grid, false, true): prefer_pile. */
+    dropNear(state, dropped, 0, state.actor.grid, false, true, opts.floorEnv ?? {});
+    /* Describe (L1383). */
+    opts.msg?.(`You no longer have ${name}.`);
+    state.updateBonuses?.(); /* gear_excise_object's PU_BONUS (obj-gear.c L500). */
+    return dropped;
+}
+/**
+ * inven_wield (obj-gear.c L931-1017): wield a pack object into `intoSlot`,
+ * taking off whatever occupies it first, then combine_pack + pack_overflow so
+ * a displaced item that does not fit is dropped (L1009-1010). Returns the
+ * slot, or -1 when the object cannot be worn. Read
+ * `state.actor.player.equipment[slot]` for the handle actually worn - a wield
+ * out of a stack equips a FRESH split, not `handle` (L947-968).
+ *
+ * The slot is an ARGUMENT upstream (`inven_wield(struct object *obj, int slot)`,
+ * obj-gear.c:931) and is NOT recomputed inside: do_cmd_wield picks it, and for a
+ * ring the player picks it (cmd-obj.c:298-311). Re-deriving it with wield_slot
+ * here is what made the third ring always land in the same hand. `intoSlot` is
+ * optional only so the pre-existing worldless callers keep the wield_slot
+ * default; every in-play caller passes the slot it decided.
+ *
+ * The MSG_WIELD line and the OF_STICKY warning (L986-1008) live here rather
+ * than in the command handler because upstream emits them BEFORE combine_pack,
+ * while do_cmd_wield's "You were wielding ..." line comes AFTER it (cmd-obj.c
+ * L346-352) and so reads the post-combine gear label.
+ */
+export function invenWield(state, handle, constants, opts = {}, intoSlot) {
+    const player = state.actor.player;
+    const obj = gearGet(state.gear, handle);
+    if (!obj)
+        return -1;
+    const slot = intoSlot !== undefined
+        ? intoSlot
+        : wieldSlot(player.body, obj.tval, player.equipment);
+    if (slot < 0 || slot >= player.body.count)
+        return -1;
+    /* `old` (L933): the slot's current occupant. Upstream just overwrites
+     * body.slots[slot].obj, which leaves `old` in p->gear as a pack item; the
+     * port's equipment[]/pack split needs the move spelled out. */
+    const oldHandle = player.equipment[slot] ?? 0;
+    if (oldHandle !== 0)
+        invenTakeoff(state, oldHandle);
+    const worn = wieldObject(state.gear, player, handle, state.runeEnv, "inven_wield", slot);
+    if (worn < 0)
+        return worn;
+    const wornHandle = player.equipment[worn] ?? 0;
+    const wornObj = gearGet(state.gear, wornHandle);
+    /* Where is the item now, and the message (L991-1006). */
+    if (wornObj && opts.msg) {
+        const verb = tvalIsMeleeWeapon(wornObj.tval)
+            ? "You are wielding"
+            : tvalIsLauncher(wornObj.tval)
+                ? "You are shooting with"
+                : tvalIsLight(wornObj.tval)
+                    ? "Your light source is"
+                    : "You are wearing";
+        opts.msg(`${verb} ${describeObject(state, wornObj)} (${gearLabelFor(state, wornHandle)}).`);
+        /* Sticky flag gets a special mention (L1008). */
+        if (wornObj.flags.has(OF.STICKY)) {
+            opts.msg("Oops! It feels deathly cold!");
+        }
+    }
+    /* See if we have to overflow the pack (L1009-1010). */
+    combinePack(state.gear, constants, overflowCalcInv(opts));
+    packOverflow(state, oldHandle, constants, opts);
+    /* object_learn_on_wield's player_learn_rune tail-calls
+     * update_player_object_knowledge (obj-knowledge.c L1373): the wield learns the
+     * obvious runes, and the sweep is what turns that into cross-object awareness
+     * (e.g. a worn Ring of Strength becoming flavour-aware - KN-03). */
+    updatePlayerObjectKnowledge(state);
+    state.updateBonuses?.(); /* PU_BONUS */
+    return worn;
+}
+/** cmd_get_item's prompt for the second wield question (cmd-obj.c:300). */
+export const WIELD_REPLACE_RING_PROMPT = "Replace which ring? ";
+/** cmd_get_item's error for it (cmd-obj.c:301) - a "please report" paranoia line. */
+export const WIELD_REPLACE_RING_ERROR = "Error in do_cmd_wield(), please report.";
+export function wieldRingChoice(state, obj) {
+    const player = state.actor.player;
+    if (!tvalIsRing(obj.tval))
+        return null;
+    const slot = wieldSlot(player.body, obj.tval, player.equipment);
+    if (slot < 0 || slot >= player.body.count)
+        return null;
+    /* "If the slot is open, wield and be done" (cmd-obj.c:291-295) - asked BEFORE
+     * the ring branch, so an empty hand skips the question entirely. */
+    if ((player.equipment[slot] ?? 0) === 0)
+        return null;
+    const slots = [];
+    for (let i = 0; i < player.body.count; i++) {
+        const handle = player.equipment[i] ?? 0;
+        if (!handle)
+            continue;
+        const worn = gearGet(state.gear, handle);
+        /* USE_EQUIP filtered by tval_is_ring: the worn rings, both of them. */
+        if (worn && tvalIsRing(worn.tval))
+            slots.push(i);
+    }
+    if (slots.length === 0)
+        return null;
+    return {
+        prompt: WIELD_REPLACE_RING_PROMPT,
+        error: WIELD_REPLACE_RING_ERROR,
+        slots,
+    };
+}
+export function wieldTakeoffConfirm(state, slot) {
+    const handle = state.actor.player.equipment[slot] ?? 0;
+    if (!handle)
+        return null;
+    const displaced = gearGet(state.gear, handle);
+    if (!displaced)
+        return null;
+    const count = checkForInscrip(displaced, "!t");
+    if (!count)
+        return null;
+    const name = describeObject(state, displaced, ODESC.PREFIX | ODESC.FULL);
+    return { prompt: `Really take off ${name}? `, count };
+}
+/**
+ * inven_drop (obj-gear.c L1078): drop amt of a carried object near the
+ * player (equipment is taken off first). Returns null when nothing was dropped.
+ *
+ * The two messages stay at the caller (the command handler), but `noneLeft` and
+ * `wasEquipped` come back with the result because upstream's own message block
+ * (L1120-1165) branches on both.
+ */
+export function invenDrop(state, handle, amt, floorEnv = {}) {
+    if (amt <= 0)
+        return null;
+    const obj = gearGet(state.gear, handle);
+    if (!obj)
+        return null;
+    if (amt > obj.number)
+        amt = obj.number;
+    /* Take off equipment, don't combine. */
+    let wasEquipped = false;
+    if (state.actor.player.equipment.includes(handle)) {
+        wasEquipped = true;
+        invenTakeoff(state, handle);
+    }
+    const { obj: dropped, noneLeft } = gearObjectForUse(state.gear, state.actor.player, handle, amt);
+    dropNear(state, dropped, 0, state.actor.grid, false, true, floorEnv);
+    return { dropped, noneLeft, wasEquipped };
+}
+/* ------------------------------------------------------------------ *
+ * cmd-obj.c use machinery.
+ * ------------------------------------------------------------------ */
+/**
+ * gear_to_label (obj-gear.c:443) with the equipment arm supplied: this module's
+ * callers can be holding an equipped object (takeoff, the "you cannot remove"
+ * refusals), so the body slots are passed in. One implementation, game/gear.ts.
+ */
+function gearLabelFor(state, handle) {
+    return gearToLabel(state.gear, handle, state.actor.player.equipment);
+}
+/**
+ * gear_to_label for an object object_pack_total handed back by reference, which
+ * the port must map to a handle first.
+ */
+function packLabelFor(state, obj) {
+    for (const handle of state.gear.pack) {
+        if (state.gear.store.get(handle) === obj)
+            return gearLabelFor(state, handle);
+    }
+    return "";
+}
+/**
+ * equip_describe (obj-gear.c L320-332): how a slot's occupant is being used,
+ * for the "You cannot remove the X you are Y." refusal. A heavy weapon or
+ * launcher reads as the slot's heavy wording instead, and a named slot (rings,
+ * hands) interpolates the slot name into its describe template.
+ */
+function equipDescribe(state, slot) {
+    const p = state.actor.player;
+    const bodySlot = p.body.slots[slot];
+    if (!bodySlot)
+        return "";
+    const entry = EQUIP_SLOT_ENTRIES.find((e) => e.name === bodySlot.type);
+    if (!entry)
+        return "";
+    const ps = state.playerState;
+    if (bodySlot.type === "WEAPON" && (ps?.heavyWield || ps?.heavyShoot)) {
+        return entry.heavyDescribe;
+    }
+    if (entry.named)
+        return entry.describe.replace("%s", bodySlot.name);
+    return entry.describe;
+}
+/** beam_chance (cmd-obj.c L112). */
+export function beamChance(tval) {
+    if (tvalIsWand(tval))
+        return 20;
+    if (tvalIsRod(tval))
+        return 10;
+    return 0;
+}
+/** The difficulty level of a used object (artifact / activation / kind). */
+function objectLevel(obj) {
+    if (obj.artifact)
+        return obj.artifact.level;
+    if (obj.activation)
+        return obj.activation.level;
+    return obj.kind.level;
+}
+/**
+ * get_use_device_chance (obj-util.c L930): failure rate out of 1000 for
+ * using a device, from the device skill against the item level.
+ */
+export function getUseDeviceChance(state, obj) {
+    const skill = state.actor.combat.skills[SKILL.DEVICE] ?? 0;
+    const lev = objectLevel(obj);
+    const x = 2 * (skill - lev) + 1;
+    let fail = -370 * x;
+    fail = Math.trunc(fail / (5 + Math.abs(x)));
+    fail += 380;
+    return fail;
+}
+/**
+ * check_devices (cmd-obj.c L59): can the device be used this turn?
+ * Returns 1 usable, 0 failed-but-retryable, -1 unusable.
+ */
+export function checkDevices(state, obj, env = {}) {
+    let action;
+    let what = null;
+    if (tvalIsRod(obj.tval)) {
+        action = "zap the rod";
+    }
+    else if (tvalIsWand(obj.tval)) {
+        action = "use the wand";
+        what = "wand";
+    }
+    else if (tvalIsStaff(obj.tval)) {
+        action = "use the staff";
+        what = "staff";
+    }
+    else {
+        action = "activate it";
+    }
+    /* Notice empty staffs / wands. */
+    if (what && obj.pval <= 0) {
+        env.msg?.(`The ${what} has no charges left.`);
+        return -1;
+    }
+    const fail = getUseDeviceChance(state, obj);
+    if (state.rng.randint1(1000) < fail) {
+        env.msg?.(`You failed to ${action} properly.`);
+        return fail < 1001 ? 0 : -1;
+    }
+    return 1;
+}
+/**
+ * number_charging (obj-util.c L1020): how many rods in a stack are still
+ * charging, from the average charge time.
+ */
+export function numberCharging(obj) {
+    const t = obj.time;
+    const chargeTime = t.base + Math.trunc((t.dice * (t.sides + 1)) / 2);
+    if (chargeTime <= 0)
+        return 0;
+    if (obj.timeout <= 0)
+        return 0;
+    const num = Math.trunc((obj.timeout + chargeTime - 1) / chargeTime);
+    return Math.min(num, obj.number);
+}
+/** obj_can_zap (obj-util.c L709): any rod in the stack not charging? */
+export function objCanZap(obj) {
+    return tvalCanHaveTimeout(obj.tval) && numberCharging(obj) < obj.number;
+}
+/**
+ * object_effect (obj-util.c L886): the effect an object actually runs - the
+ * ACTIVATION's effect when it has one, otherwise the kind/instance effect.
+ * The activation wins outright, so an artifact or ego activation replaces the
+ * base kind's effect rather than being appended to it.
+ */
+export function objectEffect(obj) {
+    if (obj.activation)
+        return obj.activation.effect;
+    return obj.effect;
+}
+/**
+ * obj_is_activatable (obj-util.c L721): a WEARABLE object that has an effect.
+ * Note both halves: a non-wearable with an effect (a potion) is not
+ * "activatable", and a wearable's effect may come from its kind rather than an
+ * activation - the rings of Flames / Acid / Ice / Lightning / Open Wounds /
+ * Digging carry an `effect:` in object.txt and no `act:`, so they ARE
+ * activatable even though obj.activation is null.
+ */
+export function objIsActivatable(obj) {
+    if (!tvalIsWearable(obj.tval))
+        return false;
+    const effect = objectEffect(obj);
+    return effect !== null && effect.length > 0;
+}
+/**
+ * obj_can_activate (obj-util.c L730): activatable AND not recharging. This is
+ * NOT obj_can_zap: do_cmd_activate guards on this (cmd-obj.c L886) while
+ * do_cmd_zap_rod guards on obj_can_zap (L851), and obj_can_zap requires a ROD
+ * tval, so reusing it for activation refuses every artifact and ring.
+ */
+export function objCanActivate(obj) {
+    return objIsActivatable(obj) && obj.timeout === 0;
+}
+/**
+ * obj_can_wear (obj-util.c L810): wield_slot(obj) >= 0 - do_cmd_wield's
+ * item_tester (cmd-obj.c L284). Over the shipped body plan this is exactly
+ * tvalIsWearable (wield_slot handles the same tval set), but it is the slot
+ * lookup that decides, so a body plan without some slot type changes the
+ * answer. NOTE the upstream wart it inherits: slot_by_type's fallback for
+ * "type not on this body" is `false`, i.e. slot 0 - so wield_slot returns 0,
+ * not -1, and obj_can_wear stays true for a slot the body does not have.
+ */
+export function objCanWear(state, obj) {
+    const player = state.actor.player;
+    return wieldSlot(player.body, obj.tval, player.equipment) >= 0;
+}
+/* ------------------------------------------------------------------ *
+ * Inscriptions and refuelling (cmd-obj.c, obj-util.c, obj-ignore.c).
+ * ------------------------------------------------------------------ */
+/** obj_has_inscrip (obj-util.c L841): does this object carry an inscription? */
+export function objHasInscrip(obj) {
+    return !!obj.note;
+}
+/** The equipped light source, or null when no LIGHT slot is worn. */
+function equippedLight(state) {
+    const lightSlot = state.actor.player.body.slots.findIndex((s) => s.type === "LIGHT");
+    return lightSlot >= 0 ? state.runeEnv.slotObject(lightSlot) : null;
+}
+/**
+ * obj_can_refill (obj-util.c L743): is `obj` a valid fuel source for the
+ * currently equipped light - a flask of oil, or another TAKES_FUEL lantern
+ * still holding fuel (its timeout)?
+ */
+export function objCanRefill(state, obj) {
+    if (obj.flags.has(OF.NO_FUEL))
+        return false;
+    const light = equippedLight(state);
+    if (light && light.flags.has(OF.TAKES_FUEL)) {
+        if (tvalIsFuel(obj.tval))
+            return true;
+        if (tvalIsLight(obj.tval) &&
+            obj.flags.has(OF.TAKES_FUEL) &&
+            obj.timeout > 0) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * refill_lamp (cmd-obj.c L1008): add `obj`'s fuel (its timeout for a donor
+ * lantern, or pval for a flask of oil) to `lamp`, capping at
+ * constants.fuelLamp. A stacked donor lantern splits off one empty unit
+ * (carried back if there's room, else dropped); a lone donor is emptied in
+ * place. A flask is consumed entirely (one unit, from the pack or floor).
+ * Recomputes the light radius (PU_TORCH) afterward.
+ */
+export function refillLamp(state, lamp, obj, opts, deps) {
+    const env = deps.env ?? {};
+    lamp.timeout += obj.timeout ? obj.timeout : obj.pval;
+    env.msg?.("You fuel your lamp.");
+    if (lamp.timeout >= deps.constants.fuelLamp) {
+        lamp.timeout = deps.constants.fuelLamp;
+        env.msg?.("Your lamp is full.");
+    }
+    if (obj.flags.has(OF.TAKES_FUEL)) {
+        /* Refilled from a lantern: empty it (splitting one off if stacked). */
+        if (obj.number > 1) {
+            const used = objectSplit(obj, 1);
+            used.timeout = 0;
+            const carried = opts.handle !== undefined && !opts.fromFloor;
+            if (carried && invenCarryNum(state.gear, used, deps.constants) > 0) {
+                invenCarry(state.gear, used, stackLimits(deps.constants));
+            }
+            else {
+                /* Overflow / floor donor: drop_near's own breakage roll (randint0)
+                 * fires here exactly as upstream, even at chance=0 (a real, faithful
+                 * RNG draw on this rare branch only - see obj-cmd.test.ts). */
+                dropNear(state, used, 0, state.actor.grid, false, true, deps.floorEnv);
+            }
+        }
+        else {
+            obj.timeout = 0;
+        }
+    }
+    else {
+        /* Refilled from a flask: consume one unit entirely. */
+        if (opts.fromFloor) {
+            floorObjectForUse(state, obj, 1);
+        }
+        else if (opts.handle !== undefined) {
+            gearObjectForUse(state.gear, state.actor.player, opts.handle, 1);
+        }
+    }
+    /* PU_TORCH: force the light-radius recalc so a just-refuelled, previously
+     * spent (timeout 0) lantern stops reading as dark (player/calcs.ts). */
+    state.updateBonuses?.();
+}
+/** Is `obj` presently carried (pack or equipped), by identity? */
+function objIsCarried(state, obj) {
+    for (const [handle, stored] of state.gear.store) {
+        if (stored !== obj)
+            continue;
+        return (state.gear.pack.includes(handle) ||
+            state.actor.player.equipment.includes(handle));
+    }
+    return false;
+}
+/**
+ * rune_add_autoinscription (obj-ignore.c:172-186): make or extend the rune-`i`
+ * autoinscription on one object. No note, or the note already present as a
+ * substring, is a no-op; otherwise the note is APPENDED to any existing
+ * inscription.
+ *
+ * Two upstream details preserved:
+ * - `strstr(obj->note, rune_note(i))` (obj-ignore.c:176) is a substring test,
+ *   not equality, so a note already contained in a longer inscription is not
+ *   appended twice - and an EMPTY note is never appended at all, because
+ *   strstr(x, "") is non-NULL;
+ * - `char current_note[80]` with my_strcpy/my_strcat (obj-ignore.c:174-182)
+ *   truncates the combined inscription to 79 characters.
+ */
+function runeAddAutoinscription(state, obj, i) {
+    const note = state.runeNotes?.get(i);
+    if (note === undefined)
+        return; // !rune_note(i)
+    const current = obj.note ?? "";
+    if (obj.note && current.includes(note))
+        return;
+    obj.note = (current + note).slice(0, 79) || null;
+}
+/**
+ * runes_autoinscribe (obj-ignore.c:217-225): put every applicable rune
+ * autoinscription on `obj` - each rune the object carries and the player knows,
+ * walked in rune-list order.
+ */
+function runesAutoinscribe(state, obj) {
+    if (!state.runeNotes)
+        return;
+    const env = state.runeEnv;
+    const p = state.actor.player;
+    const runes = buildRuneList(env);
+    for (let i = 0; i < runes.length; i++) {
+        const rune = runes[i];
+        if (objectHasRune(env, obj, rune) && playerKnowsRune(p, rune)) {
+            runeAddAutoinscription(state, obj, i);
+        }
+    }
+}
+/**
+ * rune_autoinscribe (obj-ignore.c:193-212): the player just set a note on rune
+ * `i` - stamp it on every object carrying that rune, on the floor beneath them
+ * first and then through the gear. Gated on player_knows_rune (:198).
+ * Upstream caller: ui-knowledge.c rune_xtra_act (:2275).
+ */
+export function runeAutoinscribe(state, i) {
+    if (!state.runeNotes)
+        return;
+    const env = state.runeEnv;
+    const rune = buildRuneList(env)[i];
+    if (!rune)
+        return;
+    if (!playerKnowsRune(state.actor.player, rune))
+        return;
+    for (const obj of floorPile(state, state.actor.grid)) {
+        if (objectHasRune(env, obj, rune))
+            runeAddAutoinscription(state, obj, i);
+    }
+    for (const obj of state.gear.store.values()) {
+        if (objectHasRune(env, obj, rune))
+            runeAddAutoinscription(state, obj, i);
+    }
+}
+/**
+ * apply_autoinscription (obj-ignore.c L242): put the kind's registered
+ * autoinscription on `obj`, unless it is already inscribed, not carried, or
+ * ignored. Also clears a stale unaware autoinscription once the kind
+ * becomes aware. Returns 1 when an inscription was applied, 0 otherwise
+ * (upstream's int return, kept for parity though callers ignore it).
+ */
+export function applyAutoinscription(state, obj, deps) {
+    const aware = deps.flavor ? deps.flavor.isAware(obj.kind) : true;
+    const note = deps.autoNote?.(obj.kind, aware) ?? null;
+    /* Remove an unaware inscription once aware, if it no longer applies. */
+    if (aware && obj.note) {
+        const unawareNote = deps.autoNote?.(obj.kind, false) ?? null;
+        if (unawareNote && obj.note === unawareNote && (!note || obj.note !== note)) {
+            obj.note = null;
+        }
+    }
+    /* "Make rune autoinscription go first, for now" (obj-ignore.c:258-259):
+     * BEFORE the no-kind-note early return, so the rune notes land even when the
+     * kind itself has no autoinscription. */
+    runesAutoinscribe(state, obj);
+    if (!note)
+        return 0;
+    if (obj.note)
+        return 0;
+    if (!objIsCarried(state, obj))
+        return 0;
+    if (ignoreItemOk(obj, state.ignore, aware))
+        return 0;
+    obj.note = note.length > 0 ? note : null;
+    deps.env?.msg?.(`You autoinscribe ${describeObject(state, obj)}.`);
+    return 1;
+}
+/**
+ * autoinscribe_ground (obj-ignore.c:340-348): apply_autoinscription over the
+ * whole pile beneath the player.
+ */
+export function autoinscribeGround(state, deps) {
+    for (const obj of floorPile(state, state.actor.grid)) {
+        applyAutoinscription(state, obj, deps);
+    }
+}
+/**
+ * autoinscribe_pack (obj-ignore.c:352-359): apply_autoinscription over p->gear
+ * (which upstream is one list covering pack AND equipment, as here).
+ */
+export function autoinscribePack(state, deps) {
+    for (const obj of state.gear.store.values()) {
+        applyAutoinscription(state, obj, deps);
+    }
+}
+/** randcalc(obj->time, 0, RANDOMISE): the recharge time roll. */
+function rollRechargeTime(state, obj) {
+    return state.rng.randcalc(obj.time, 0, "randomise");
+}
+/** Build an object's effect chain from its raw records (per use). */
+export function buildObjectEffectChain(records, state, inject = {}) {
+    const builder = new EffectBuilder({
+        ...inject,
+        baseValues: {
+            PLAYER_LEVEL: () => state.actor.player.lev,
+            MAX_SIGHT: () => state.z.maxSight,
+            DUNGEON_LEVEL: () => state.chunk.depth,
+            /* effects.c L308-315: WEAPON_DAMAGE is a live damroll(dd, ds)+to_d
+             * expression base. Keeping this provider lazy preserves the C draw
+             * position: the roll occurs exactly when the expression is evaluated. */
+            WEAPON_DAMAGE: () => {
+                const weapon = state.actor.weapon;
+                return weapon
+                    ? state.rng.damroll(weapon.dd, weapon.ds) + weapon.toD
+                    : 0;
+            },
+            ...inject.baseValues,
+        },
+    });
+    for (const e of records) {
+        let spec = e.eff;
+        const hasType = e.type !== undefined && e.type !== "";
+        if (hasType || e.radius || e.other)
+            spec += ":" + (e.type ?? "");
+        if (e.radius || e.other)
+            spec += ":" + (e.radius ?? 0);
+        if (e.other)
+            spec += ":" + e.other;
+        builder.effect(spec);
+        if (e.dice)
+            builder.dice(e.dice);
+        for (const x of e.expr ?? [])
+            builder.expr(x.name, x.base, x.expr);
+    }
+    return builder.build();
+}
+/** effect_aim over an effect name, from the generated base table. */
+const EFFECT_NEEDS_AIM = new Map(EFFECT_ENTRIES.map((e) => [e.name, e.aim]));
+/** effect_aim over a raw record chain: any effect marked as aimed. */
+export function effectRecordsNeedAim(records) {
+    /* RANDOM/SELECT children share the parent walk; the flat list covers them. */
+    return records.some((e) => EFFECT_NEEDS_AIM.get(e.eff.split(":")[0] ?? e.eff) === true);
+}
+/** obj_needs_aim (obj-util.c L899), on the raw effect records. */
+export function objNeedsAim(obj, deps) {
+    const aimed = effectRecordsNeedAim(obj.effect ?? []);
+    const aware = deps.flavor ? deps.flavor.isAware(obj.kind) : true;
+    return aimed || tvalIsWand(obj.tval) || (tvalIsRod(obj.tval) && !aware);
+}
+/** player_is_shapechanged (player-util.c L1065): null shape = normal. */
+export function playerIsShapechanged(state) {
+    return state.actor.player.shape !== null;
+}
+/**
+ * player_resume_normal_shape (player-util.c L1048): back to normal form,
+ * killing the vampire attack and refreshing the bonuses.
+ */
+export function playerResumeNormalShape(state, env = {}) {
+    state.actor.player.shape = null;
+    env.msg?.("You resume your usual shape.");
+    /* Kill vampire attack. */
+    state.actor.player.timed[TMD.ATT_VAMP] = 0;
+    state.updateBonuses?.();
+}
+/**
+ * player_get_resume_normal_shape (player-util.c L1022): a shapechanged
+ * player must return to normal form before acting with hands/voice. The
+ * y/n/r prompt is the confirm seam (headless default: change back and
+ * proceed).
+ */
+export function playerGetResumeNormalShape(state, env = {}) {
+    if (!playerIsShapechanged(state))
+        return true;
+    env.msg?.(`You cannot do this while in ${state.actor.player.shape.name} form.`);
+    if (env.confirm?.("Change back and continue? ") ?? true) {
+        playerResumeNormalShape(state, env);
+        return true;
+    }
+    return false;
+}
+/**
+ * player_can_read (player-util.c L1166): scrolls and spellbooks need working
+ * eyes, light, a clear head and intact memory. Checked in this exact order, and
+ * each refusal prints its own message and spends no turn. do_cmd_read_scroll
+ * (cmd-obj.c L748) calls this with show_msg true BEFORE cmd_get_item, so a blind
+ * player with no scrolls at all still hears "You can't see anything." rather
+ * than the "You have no scrolls to read." rejection.
+ *
+ * Reached from two places upstream and both are this same predicate:
+ * do_cmd_read_scroll (cmd-obj.c:748) and the 'r' key's prereq
+ * player_can_read_prereq (player-util.c:1264, wired at ui-game.c:131) - which
+ * is why the show_msg parameter exists rather than the messages being inlined.
+ * The prereq's TMD_COMMAND bypass is NOT reproduced here: while TMD_COMMAND runs
+ * the turn loop redirects every command to do_cmd_mon_command before the handler
+ * is reached (game/player-turn.ts L708-714), which is exactly what the bypass
+ * exists to permit.
+ *
+ * Note the order and strings differ from player_can_cast (L1087), which folds
+ * blind and no_light into one "You cannot see!" and has no amnesia check.
+ */
+export function playerCanRead(state, env = {}, showMsg = true) {
+    const p = state.actor.player;
+    if ((p.timed[TMD.BLIND] ?? 0) > 0) {
+        if (showMsg)
+            env.msg?.("You can't see anything.");
+        return false;
+    }
+    if (noLight(state)) {
+        if (showMsg)
+            env.msg?.("You have no light to read by.");
+        return false;
+    }
+    if ((p.timed[TMD.CONFUSED] ?? 0) > 0) {
+        if (showMsg)
+            env.msg?.("You are too confused to read!");
+        return false;
+    }
+    if ((p.timed[TMD.AMNESIA] ?? 0) > 0) {
+        if (showMsg)
+            env.msg?.("You can't remember how to read!");
+        return false;
+    }
+    return true;
+}
+/**
+ * no_light (cave-view.c L913): the player's own grid is not currently seen.
+ * Shared by playerCanRead here and player_can_cast (game/spell-cmd.ts).
+ *
+ * SQUARE_SEEN is maintained by update_view, which this port drives through the
+ * `state.updateFov` host seam. This used to open with a guard - `if
+ * (state.updateFov === undefined) return false` - described in its own comment as
+ * "a seam guard, not a rule of the game", because a host that installed no seam
+ * left SEEN clear on every grid and would have found casting and reading
+ * permanently impossible.
+ *
+ * The guard is gone because its premise is: core installs a DEFAULT updateFov in
+ * wireGame, so startGame and loadGame both maintain SEEN with no host cooperation
+ * and there is no configuration left in which the flag carries no information.
+ * Keeping it would mean a host that deleted the seam silently got non-upstream
+ * spell rules - the guard's whole purpose was to make an unplayable state
+ * playable, and that state cannot happen now.
+ *
+ * So this is upstream verbatim for every caller.
+ */
+export function noLight(state) {
+    return !squareIsSeen(state.chunk, state.actor.grid);
+}
+/**
+ * player_confuse_dir (player-util.c): confusion randomises the direction
+ * 75% of the time (always for "no direction").
+ */
+export function playerConfuseDir(state, dir, too = false) {
+    if ((state.actor.player.timed[TMD.CONFUSED] ?? 0) > 0) {
+        let newDir = dir;
+        if (dir === 5 || state.rng.randint0(100) < 75) {
+            /* Random direction. */
+            newDir = DDD[state.rng.randint0(8)];
+        }
+        /* player-util.c L1363-1366: running is refused after the same confusion
+         * roll, with the C's message. */
+        if (too) {
+            state.msg?.("You are too confused.");
+            return dir;
+        }
+        /* player-util.c L1369: emit "You are confused." and report the change only
+         * when the direction actually changed (a same-direction roll is silent).
+         * The RNG draw above is unconditional whenever confused, matching C. */
+        if (newDir !== dir) {
+            state.msg?.("You are confused.");
+            return newDir;
+        }
+    }
+    return dir;
+}
+/**
+ * object_learn_on_use (obj-knowledge.c L1925-1936), XP slice (gap 4.3): the
+ * flavor-awareness half is handled by the caller (objectFlavorAware); this adds
+ * the experience reward player_exp_gain(p, (lev + p->lev/2)/p->lev) with lev the
+ * used object's KIND level. Integer division throughout, exactly as upstream.
+ */
+function objectLearnOnUseXp(state, obj, deps) {
+    if (!deps.expGain)
+        return;
+    const p = state.actor.player;
+    const lev = obj.kind.level;
+    deps.expGain(Math.trunc((lev + Math.trunc(p.lev / 2)) / p.lev));
+}
+/**
+ * activation_message (cmd-obj.c L127): print an activated object's custom
+ * message. The message text comes from the activation (activation.txt msg:),
+ * but an artifact carrying its own alt_msg (artifact.txt msg:) overrides it -
+ * and the override only fires when the activation itself defines a message. The
+ * text is run through print_custom_message's {name}/{kind}/{s}/{is} object-tag
+ * substitution (obj-util.c L1118): {name} -> object_desc(PREFIX|BASE), {kind} ->
+ * object_kind_name (easy_know), {s}/{is} keyed on the stack count.
+ */
+function activationMessage(state, obj, env) {
+    if (!obj.activation?.message)
+        return;
+    const message = obj.artifact && obj.artifact.altMsg
+        ? obj.artifact.altMsg
+        : obj.activation.message;
+    const text = substituteTimedMessage(message, {
+        name: describeObject(state, obj, ODESC.PREFIX | ODESC.BASE),
+        kind: objDescNameFormat(obj.kind.name, null, false),
+        number: obj.number,
+    });
+    env.msg?.(text);
+}
+/**
+ * use_aux (cmd-obj.c L407): use an object the right way - aim resolution,
+ * the device check, charge/timeout/single-use deduction with restore on an
+ * unused effect, and the effect chain run with a player source.
+ */
+export function useAux(state, obj, use, deps, opts = {}) {
+    const env = deps.env ?? {};
+    const fromFloor = opts.fromFloor ?? false;
+    const wasAware = deps.flavor ? deps.flavor.isAware(obj.kind) : true;
+    /* Determine whether we know an item needs to be aimed. */
+    const knownAim = tvalIsWand(obj.tval) || tvalIsRod(obj.tval) || wasAware;
+    let dir = 5;
+    if (objNeedsAim(obj, deps)) {
+        if (!knownAim) {
+            /* Unknown things with no obvious aim get a random direction. */
+            dir = DDD[state.rng.randint0(8)];
+        }
+        else {
+            dir = opts.dir ?? env.chooseDir?.() ?? 5;
+        }
+        /* Confusion wrecks aim. */
+        dir = playerConfuseDir(state, dir);
+    }
+    /* Check for use if necessary. */
+    let canUse = 1;
+    if (use === USE.CHARGE || use === USE.TIMEOUT) {
+        canUse = checkDevices(state, obj, env);
+    }
+    if (canUse > 0) {
+        const beam = beamChance(obj.tval);
+        const level = objectLevel(obj);
+        const boost = Math.max(Math.trunc(((state.actor.combat.skills[SKILL.DEVICE] ?? 0) - level) / 2), 0);
+        /* Sound / message (cmd-obj.c L493-504): an activation prints the generic
+         * "You activate it." then its own activation_message; otherwise the kind's
+         * effect_msg (always) or vis_msg (only when not blind). */
+        if (obj.activation) {
+            env.msg?.("You activate it.");
+            activationMessage(state, obj, env);
+        }
+        else if (obj.kind.effectMsg) {
+            env.msg?.(obj.kind.effectMsg);
+        }
+        else if (obj.kind.visMsg &&
+            (state.actor.player.timed[TMD.BLIND] ?? 0) === 0) {
+            env.msg?.(obj.kind.visMsg);
+        }
+        /* Capture the describe inputs before the effect can rearrange the pack
+         * (cmd-obj.c L462-483): the gear label of the item and the count to report.
+         * For anything but a CHARGE / TIMEOUT device that count is the AGGREGATE
+         * across every like stack (object_pack_total, L474), and the label becomes
+         * the first such stack's - "You have 3 Scrolls of Light (1st d)."  A charge
+         * or recharging notice is stack-specific, so those keep their own number
+         * (L480). A floor object has no pack context at all (L465). */
+        let describeLabel = opts.handle !== undefined ? gearLabelFor(state, opts.handle) : "";
+        let startNumber = obj.number;
+        let firstRemainder = null;
+        if (!fromFloor && use !== USE.CHARGE && use !== USE.TIMEOUT) {
+            const view = packTotalView(state.gear);
+            const agg = objectPackTotal(view, obj, false);
+            startNumber = agg.total;
+            firstRemainder = agg.first;
+            /* One stack only: nothing to call "1st" (L477-479). */
+            if (firstRemainder && firstRemainder.number === agg.total) {
+                firstRemainder = null;
+            }
+        }
+        /* Tentatively deduct floor-object usage before the effect (the effect
+         * could leave the object inaccessible). */
+        let deductBefore = false;
+        let charges = 0;
+        let singleUsed = null;
+        if (fromFloor) {
+            if (use === USE.SINGLE) {
+                deductBefore = true;
+                singleUsed = floorObjectForUse(state, obj, 1).usable;
+            }
+            else if (use === USE.CHARGE) {
+                deductBefore = true;
+                charges = obj.pval;
+                obj.pval--;
+            }
+            else if (use === USE.TIMEOUT) {
+                deductBefore = true;
+                charges = obj.timeout;
+                obj.timeout += rollRechargeTime(state, obj);
+            }
+        }
+        /* Do effect. use_aux takes its chain from object_effect(obj) (cmd-obj.c
+         * L410 `struct effect *effect = object_effect(obj);`), so an activation's
+         * effect REPLACES the base kind's - reading obj.effect here ran a
+         * Narthanc-style artifact's (empty) kind effect instead of its activation. */
+        const chain = buildObjectEffectChain(objectEffect(obj) ?? [], state, deps.inject);
+        const ctx = attachGameEnv(buildEffectContext(state, deps.envDeps), {
+            state,
+            cast: deps.cast,
+            /* take_hit consequences for effects that rebound damage onto the player
+             * (EF_BANISH), so such a death records died_from too. */
+            ...(deps.envDeps.takeHitHooks
+                ? { takeHitHooks: deps.envDeps.takeHitHooks }
+                : {}),
+            /* target_get inside the handlers: a DIR_TARGET cast re-reads the
+             * live target per handler, as upstream. */
+            get aimed() {
+                return targetOkay(state) ? targetGet(state) : undefined;
+            },
+            ...(deps.teleport ? { teleport: deps.teleport } : {}),
+            ...(deps.general ? { general: deps.general } : {}),
+            ...(deps.item ? { item: deps.item } : {}),
+            ...(deps.summon ? { summon: deps.summon } : {}),
+            /* Flavor knowledge for item-identifying effects (EF_IDENTIFY fires the
+             * object_flavor_aware side effect of player_know_object). */
+            ...(deps.flavor ? { flavor: deps.flavor } : {}),
+            ...(deps.flavorDeps ? { flavorDeps: deps.flavorDeps } : {}),
+        });
+        const ident = { value: false };
+        targetFix(state);
+        /* cmd_get_item "tgtitem" / "tgtcurse" presets: the item-choosing effects
+         * read state.itemTarget / state.curseTarget through the getItem seam. Set
+         * before the run, cleared after (cmd_set_arg_item's scope). */
+        state.itemRequest = null;
+        state.itemTarget = opts.tgtItem ?? null;
+        state.curseTarget = opts.tgtCurse ?? null;
+        const used = deps.registry.effectDo(chain, ctx, {
+            origin: sourcePlayer(),
+            obj,
+            ident,
+            aware: wasAware,
+            dir,
+            beam,
+            boost,
+        });
+        state.itemTarget = null;
+        state.curseTarget = null;
+        targetRelease(state);
+        if (!used && deductBefore) {
+            /* Restore the tentative deduction. */
+            if (use === USE.SINGLE && singleUsed) {
+                dropNear(state, singleUsed, 0, state.actor.grid, false, true, deps.floorEnv);
+            }
+            else if (use === USE.CHARGE) {
+                obj.pval = charges;
+            }
+            else if (use === USE.TIMEOUT) {
+                obj.timeout = charges;
+            }
+        }
+        /* Increase knowledge. */
+        if (deps.flavor) {
+            const knowObj = singleUsed ?? obj;
+            const flavorDeps = deps.flavorDeps ?? NOOP_FLAVOR_AWARE_DEPS;
+            if (use === USE.SINGLE) {
+                /* Single use items are automatically learned. */
+                if (!wasAware) {
+                    deps.flavor.objectFlavorAware(knowObj.kind, flavorDeps);
+                    objectLearnOnUseXp(state, knowObj, deps);
+                }
+            }
+            else if (!wasAware && ident.value) {
+                deps.flavor.objectFlavorAware(knowObj.kind, flavorDeps);
+                objectLearnOnUseXp(state, knowObj, deps);
+            }
+            else {
+                deps.flavor.setTried(knowObj.kind);
+            }
+        }
+        /* Use up, deduct charge, or apply timeout if it wasn't done before. */
+        if (used && !deductBefore) {
+            if (use === USE.CHARGE) {
+                obj.pval--;
+            }
+            else if (use === USE.TIMEOUT) {
+                obj.timeout += rollRechargeTime(state, obj);
+            }
+            else if (use === USE.SINGLE && opts.handle !== undefined) {
+                gearObjectForUse(state.gear, state.actor.player, opts.handle, 1);
+            }
+        }
+        /* Describe what's left (cmd-obj.c L633-706). Single-use items are always
+         * described; a charge/timeout device only when it was just identified (and
+         * never for wearables, which take the update-knowledge branch). Otherwise a
+         * used charge device reports its remaining charges. */
+        const describe = use === USE.SINGLE ||
+            (!tvalIsWearable(obj.tval) && !wasAware && ident.value);
+        if (describe) {
+            const shown = startNumber - (used && use === USE.SINGLE ? 1 : 0);
+            const name = describeObject(state, obj, ODESC.PREFIX | ODESC.FULL | ODESC.ALTNUM, shown);
+            if (fromFloor)
+                env.msg?.(`You see ${name}.`);
+            else {
+                /* cmd-obj.c L692-698: the "1st" label is looked up AFTER the effect,
+                 * because the pack may have moved underneath it. */
+                if (firstRemainder)
+                    describeLabel = packLabelFor(state, firstRemainder);
+                env.msg?.(firstRemainder
+                    ? `You have ${name} (1st ${describeLabel}).`
+                    : `You have ${name} (${describeLabel}).`);
+            }
+        }
+        else if (used &&
+            use === USE.CHARGE &&
+            tvalCanHaveCharges(obj.tval) &&
+            (deps.flavor ? deps.flavor.isAware(obj.kind) : true)) {
+            /* inven_item_charges / floor_item_charges (obj-gear.c L790-799). */
+            env.msg?.(`You have ${obj.pval} charge${obj.pval === 1 ? "" : "s"} remaining.`);
+        }
+    }
+    /* Use the turn (even a device fizzle spends it, as upstream). */
+    return { turnSpent: true, used: canUse > 0 };
+}
+/* ------------------------------------------------------------------ *
+ * Command actions.
+ * ------------------------------------------------------------------ */
+/** Resolve a command's object: a gear handle or a floor pile position. */
+function commandObject(state, cmd) {
+    const args = cmd.args ?? {};
+    const handle = typeof args["handle"] === "number" ? args["handle"] : null;
+    if (handle !== null) {
+        const obj = gearGet(state.gear, handle);
+        return obj ? { obj, handle, fromFloor: false } : null;
+    }
+    const floorIdx = typeof args["floor"] === "number" ? args["floor"] : null;
+    if (floorIdx !== null) {
+        const pile = floorPile(state, state.actor.grid);
+        const obj = pile[floorIdx];
+        return obj ? { obj, fromFloor: true } : null;
+    }
+    return null;
+}
+function commandDir(cmd) {
+    const d = cmd.args?.["dir"] ?? cmd.dir;
+    return typeof d === "number" ? d : undefined;
+}
+/** cmd_get_arg_item "tgtitem": the shell's pre-resolved item-effect target. */
+function commandTargetItem(cmd) {
+    const t = cmd.args?.["tgtitem"];
+    if (t && typeof t === "object") {
+        if (typeof t.handle === "number") {
+            return { handle: t.handle };
+        }
+        if (typeof t.floor === "number") {
+            return { floor: t.floor };
+        }
+    }
+    return undefined;
+}
+/**
+ * A use command over a tval filter and use kind.
+ *
+ * `ready` is the command's OWN pre-use guard, because upstream does NOT share
+ * one: do_cmd_zap_rod tests obj_can_zap and says "That rod is still charging."
+ * (cmd-obj.c L851-855) while do_cmd_activate tests obj_can_activate and says
+ * "That item is still charging." (L886-890). obj_can_zap requires a rod tval,
+ * so the two are not interchangeable - using obj_can_zap for activation
+ * refused EVERY artifact and ring.
+ */
+function useCommand(deps, filter, use, ready) {
+    return (state, cmd) => {
+        const found = commandObject(state, cmd);
+        if (!found || !filter(found.obj))
+            return 0;
+        if (ready && !ready.ok(found.obj)) {
+            deps.env?.msg?.(ready.msg);
+            return 0;
+        }
+        if (use === USE.CHARGE && found.obj.pval <= 0) {
+            /* do_cmd_aim_wand (cmd-obj.c L817-820) / do_cmd_use_staff (L783-786)
+             * pre-check obj_has_charges and return BEFORE use_aux, so an empty
+             * device costs no turn (checkDevices' "... no charges left." path in
+             * useAux would otherwise burn one). */
+            deps.env?.msg?.(tvalIsWand(found.obj.tval)
+                ? "That wand has no charges."
+                : "That staff has no charges.");
+            return 0;
+        }
+        const dir = commandDir(cmd);
+        const tgtItem = commandTargetItem(cmd);
+        const tgtCurse = cmd.args?.["tgtcurse"];
+        const result = useAux(state, found.obj, use, deps, {
+            fromFloor: found.fromFloor,
+            ...(found.handle !== undefined ? { handle: found.handle } : {}),
+            ...(dir !== undefined ? { dir } : {}),
+            ...(tgtItem ? { tgtItem } : {}),
+            ...(typeof tgtCurse === "number" ? { tgtCurse } : {}),
+        });
+        /* "Autoinscribe if we are guaranteed to still have any"
+         * (cmd-obj.c:717-719): `if (!none_left && !from_floor)`. none_left is
+         * gear_object_for_use consuming the last of the stack, which here is the
+         * gear handle no longer resolving. */
+        if (!found.fromFloor && found.handle !== undefined) {
+            const left = state.gear.store.get(found.handle);
+            if (left)
+                applyAutoinscription(state, left, deps);
+        }
+        return result.turnSpent ? state.z.moveEnergy : 0;
+    };
+}
+/**
+ * Register the object commands (wield / takeoff / drop / eat / quaff /
+ * read / use-staff / aim-wand / zap-rod / activate) on the registry.
+ */
+export function installObjCommands(registry, deps) {
+    /* player_get_resume_normal_shape gates the hands/voice commands
+     * (cmd-obj.c: takeoff/wield/drop, scroll/staff/wand/rod/activate AND
+     * quaff - do_cmd_quaff_potion opens with the resume gate at cmd-obj.c L923).
+     * do_cmd_eat_food (L899) is the one use command with NO gate, so eating stays
+     * possible in any shape. */
+    const gated = (fn) => {
+        return (state, cmd) => playerGetResumeNormalShape(state, deps.env ?? {}) ? fn(state, cmd) : 0;
+    };
+    /* do_cmd_wield (cmd-obj.c:265-353): wear/wield from the pack or the floor.
+     *
+     * The statement order below is upstream's, and it is load-bearing:
+     *   1. cmd_get_item for the item
+     *   2. slot = wield_slot(obj); equip_obj = slot_object(player, slot)
+     *   3. slot empty -> inven_wield and return, asking nothing
+     *   4. ring -> the SECOND cmd_get_item, "Replace which ring? ", which
+     *      overwrites slot with the hand the player chose
+     *   5. obj_can_takeoff refusal (sticky)
+     *   6. the "!t" get_check loop
+     *   7. act wording from the SLOT's type, then inven_wield(obj, slot)
+     *   8. the MSG_WIELD "You were ..." line
+     *
+     * The floor pickup belongs at step 7, not step 1: upstream carries a floor
+     * item INSIDE inven_wield (`floor_object_for_use` + `inven_carry`,
+     * obj-gear.c:973-976), which is past every abort above. Doing it first - as the
+     * port did - leaked the item into the pack when the player escaped the ring or
+     * "!t" prompt, or when the slot turned out to be stuck. */
+    registry.register("wield", gated((state, cmd) => {
+        const found = commandObject(state, cmd);
+        if (!found)
+            return 0;
+        const player = state.actor.player;
+        /* Step 2. */
+        let targetSlot = wieldSlot(player.body, found.obj.tval, player.equipment);
+        if (targetSlot < 0 || targetSlot >= player.body.count)
+            return 0;
+        /* Step 4: the ring question. The core command path cannot block on UI, so
+         * the shell resolves wieldRingChoice() and passes the chosen slot back as
+         * the "slot" argument, which is precisely what upstream's cmd_get_item does
+         * when the command already carries the answer (cmd-obj.c:298). With no
+         * answer supplied (a headless driver, the borg) the pre-prompt wield_slot
+         * stands, the same "unprompted terminal takes the default" rule the confirm
+         * seam uses. */
+        if ((player.equipment[targetSlot] ?? 0) !== 0 && tvalIsRing(found.obj.tval)) {
+            const chosen = cmd.args?.["slot"];
+            if (typeof chosen === "number") {
+                const chosenHandle = player.equipment[chosen] ?? 0;
+                const chosenObj = chosenHandle ? gearGet(state.gear, chosenHandle) : null;
+                /* Only a worn RING is a legal answer (the tval_is_ring filter on
+                 * USE_EQUIP); anything else is not something cmd_get_item could have
+                 * returned, so it is ignored rather than obeyed. */
+                if (chosenObj && tvalIsRing(chosenObj.tval))
+                    targetSlot = chosen;
+            }
+        }
+        const displacedHandle = player.equipment[targetSlot] ?? 0;
+        const displaced = displacedHandle ? gearGet(state.gear, displacedHandle) : null;
+        /* Step 5: prevent wielding into a stickied slot (cmd-obj.c:313-320).
+         * obj_can_takeoff is !OF_STICKY (obj-util.c L794), and the refusal names the
+         * stuck item by its base description plus equip_describe's wording for the
+         * slot. Draws no RNG and spends no energy: the command aborts before
+         * inven_wield. */
+        if (displaced && displaced.flags.has(OF.STICKY)) {
+            deps.env?.msg?.(`You cannot remove the ${describeObject(state, displaced, ODESC.BASE)} ` +
+                `you are ${equipDescribe(state, targetSlot)}.`);
+            return 0;
+        }
+        /* Step 6: the "!t" checks for taking off (cmd-obj.c:321-330). One refusal
+         * ends the command with no turn spent. The shell has normally answered these
+         * already (it must, to ask before the item moves); the seam is here too so a
+         * driver that queues the command directly still honours the inscription. */
+        const ask = wieldTakeoffConfirm(state, targetSlot);
+        if (ask) {
+            for (let i = 0; i < ask.count; i++) {
+                if (!(deps.env?.confirm?.(ask.prompt) ?? true))
+                    return 0;
+            }
+        }
+        /* Step 7: the wording comes from the SLOT's type upstream
+         * (slot_type_is(player, slot, EQUIP_WEAPON), cmd-obj.c:337-347), not from the
+         * displaced item's tval - and it is read BEFORE inven_wield empties the
+         * slot. */
+        const slotType = player.body.slots[targetSlot]?.type ?? "";
+        const act = slotType === "WEAPON"
+            ? "You were wielding"
+            : slotType === "BOW" || slotType === "LIGHT"
+                ? "You were holding"
+                : "You were wearing";
+        /* inven_wield's own floor path (obj-gear.c:973-976), reached only now. */
+        let handle = found.handle;
+        if (found.fromFloor) {
+            const { usable } = floorObjectForUse(state, found.obj, 1);
+            handle = invenCarry(state.gear, usable, stackLimits(deps.constants));
+        }
+        if (handle === undefined)
+            return 0;
+        /* invenWield owns the MSG_WIELD line, the sticky warning, combine_pack and
+         * pack_overflow, in that upstream order (obj-gear.c L986-1010). The slot is
+         * passed, not re-derived: for a ring it is the hand the player chose. */
+        const slot = invenWield(state, handle, deps.constants, packOpts(state, deps), targetSlot);
+        if (slot < 0)
+            return 0;
+        /* Step 8. The displaced item is now back in the pack - or on the floor if
+         * pack_overflow shed it, in which case gear_to_label gives '\0' and the
+         * port's gearLabelFor gives "" (cmd-obj.c L337-354, read AFTER
+         * combine_pack, so the label is the post-combine one). */
+        if (displaced) {
+            const dname = describeObject(state, displaced);
+            const dlabel = gearLabelFor(state, displacedHandle);
+            deps.env?.msg?.(`${act} ${dname} (${dlabel}).`);
+        }
+        return state.z.moveEnergy;
+    }));
+    /* do_cmd_takeoff: energy is half a turn. */
+    registry.register("takeoff", gated((state, cmd) => {
+        const args = cmd.args ?? {};
+        const handle = typeof args["handle"] === "number" ? args["handle"] : null;
+        if (handle === null)
+            return 0;
+        const obj = gearGet(state.gear, handle);
+        const tval = obj?.tval ?? 0;
+        /* obj_can_takeoff (obj-util.c:794-796) is the takeoff-item filter in
+         * do_cmd_takeoff (cmd-obj.c:251): a sticky item is not selectable, so this
+         * direct command entry likewise aborts silently and spends no energy. */
+        if (obj?.flags.has(OF.STICKY))
+            return 0;
+        if (!invenTakeoff(state, handle))
+            return 0;
+        /* inven_takeoff sets PU_INVEN and calls update_stuff ITSELF (obj-gear.c
+         * L1058-1062), one line before its message - because that message names the
+         * item at its NEW pack letter, and the item has only just stopped being
+         * equipment. The port deferred this to the caller's combine_pack below, which
+         * is after the message: the letter was read off a listing the item was not
+         * in yet. (The old comment here cited L1060 for combine_pack; L1060 is
+         * update_stuff inside inven_takeoff.) */
+        calcInventory(state.gear, deps.constants, calcInvOpts(state, deps));
+        /* inven_takeoff's message (obj-gear.c L1046-1065): the slot wording, then
+         * the item named at its new pack label. */
+        if (obj) {
+            const act = tvalIsMeleeWeapon(tval)
+                ? "You were wielding"
+                : tvalIsLauncher(tval) || tvalIsLight(tval)
+                    ? "You were holding"
+                    : "You were wearing";
+            deps.env?.msg?.(`${act} ${describeObject(state, obj)} (${gearLabelFor(state, handle)}).`);
+        }
+        /* combine_pack (which re-runs calc_inventory for inven_takeoff's PU_INVEN,
+         * obj-gear.c L1060) then pack_overflow on the item just taken off
+         * (cmd-obj.c L255-257). */
+        const opts = packOpts(state, deps);
+        combinePack(state.gear, deps.constants, calcInvOpts(state, deps));
+        packOverflow(state, handle, deps.constants, opts);
+        return Math.trunc(state.z.moveEnergy / 2);
+    }));
+    /* do_cmd_drop: energy is half a turn. */
+    registry.register("drop", gated((state, cmd) => {
+        const args = cmd.args ?? {};
+        const handle = typeof args["handle"] === "number" ? args["handle"] : null;
+        if (handle === null)
+            return 0;
+        const obj = gearGet(state.gear, handle);
+        if (!obj)
+            return 0;
+        /* Cannot drop stickied equipment (cmd-obj.c L377-381). The C checks
+         * object_is_equipped && !obj_can_takeoff and aborts before inven_drop, so no
+         * energy is spent and no RNG is drawn. */
+        if (state.actor.player.equipment.includes(handle) &&
+            obj.flags.has(OF.STICKY)) {
+            deps.env?.msg?.("Hmmm, it seems to be stuck.");
+            return 0;
+        }
+        const amt = typeof args["quantity"] === "number" ? args["quantity"] : obj.number;
+        /* Label captured before the drop (inven_drop L1099). */
+        const label = gearLabelFor(state, handle);
+        const result = invenDrop(state, handle, amt, deps.floorEnv);
+        if (!result)
+            return 0;
+        const { dropped, noneLeft, wasEquipped } = result;
+        /* gear_object_for_use excises through gear_excise_object, which re-runs
+         * calc_inventory (obj-gear.c L497) - BEFORE inven_drop's messages, not after
+         * them. It matters for the "1st" letter below, which upstream looks up at
+         * L1157 against the rebuilt listing; `label` above stays the pre-drop one
+         * (L1099), exactly as upstream captures it. */
+        calcInventory(state.gear, deps.constants, calcInvOpts(state, deps));
+        /* inven_drop's messages (obj-gear.c L1120-1165): the drop, then what's
+         * left. Dropping an equipped item omits the take-off line the port's
+         * inven_takeoff does not emit - ledgered. */
+        deps.env?.msg?.(`You drop ${describeObject(state, dropped)} (${label}).`);
+        if (dropped.artifact) {
+            deps.env?.msg?.(`You no longer have the ${describeObject(state, dropped, ODESC.FULL | ODESC.SINGULAR)} (${label}).`);
+        }
+        else {
+            /* The remaining count is the AGGREGATE over every like stack still in the
+             * pack (object_pack_total, L1149), and the letter is the first such
+             * stack's - so dropping 2 of 5 flasks split over slots c and f says
+             * "You have 3 Flasks of oil (1st c)." Suppressed when the item was
+             * equipped, or carries a stack-specific charge / recharging notice
+             * (L1138-1141), in which case the aggregate would contradict it. */
+            let total;
+            let first;
+            let descTarget;
+            if (wasEquipped || packTotalSuppressed(obj)) {
+                first = null;
+                if (noneLeft) {
+                    total = 0;
+                    descTarget = dropped;
+                }
+                else {
+                    total = obj.number;
+                    descTarget = obj;
+                }
+            }
+            else {
+                const view = packTotalView(state.gear);
+                ({ total, first } = objectPackTotal(view, obj, false));
+                descTarget = total ? obj : dropped;
+            }
+            const name = describeObject(state, descTarget, ODESC.PREFIX | ODESC.FULL | ODESC.ALTNUM, total);
+            if (!first) {
+                deps.env?.msg?.(`You have ${name} (${label}).`);
+            }
+            else {
+                const firstLabel = packLabelFor(state, first);
+                deps.env?.msg?.(total > first.number
+                    ? `You have ${name} (1st ${firstLabel}).`
+                    : `You have ${name} (${firstLabel}).`);
+            }
+        }
+        return Math.trunc(state.z.moveEnergy / 2);
+    }));
+    registry.register("eat", useCommand(deps, (o) => tvalIsEdible(o.tval), USE.SINGLE));
+    /* do_cmd_quaff_potion (cmd-obj.c L917-931): the resume-shape gate, THEN the
+     * potion pick. Unlike do_cmd_eat_food it is gated. */
+    registry.register("quaff", gated(useCommand(deps, (o) => tvalIsPotion(o.tval), USE.SINGLE)));
+    /*
+     * do_cmd_read_scroll (cmd-obj.c L740-758): resume shape, THEN
+     * player_can_read(player, true) - blind / no light / confused / amnesia each
+     * refuse with their own message and cost no turn - and only then the scroll
+     * pick, so the read gate fires before "You have no scrolls to read.".
+     *
+     * Two lanes ported this independently and reached OPPOSITE orderings, because
+     * upstream checks the same condition in two places and each lane found one:
+     * this handler order, and `player_can_read_prereq` hung on the 'r' key entry
+     * (ui-game.c:131), which ui-game.c:596 runs BEFORE the command is ever
+     * pushed. Both are real. The prereq means a blind player pressing 'r' never
+     * reaches the shape-resume prompt at all, while anything that pushes
+     * CMD_READ_SCROLL without going through that key entry still takes
+     * resume-then-read. Collapsing the pair into a single head-of-handler guard
+     * reproduces the keyboard order but breaks the handler's own, so the guard
+     * stays here in C order and the prereq belongs at the port's dispatch layer
+     * next to the key binding - the same split playercan applied to cast/study.
+     */
+    registry.register("read", gated((state, cmd) => {
+        if (!playerCanRead(state, deps.env ?? {}))
+            return 0;
+        return useCommand(deps, (o) => tvalIsScroll(o.tval), USE.SINGLE)(state, cmd);
+    }));
+    registry.register("use-staff", gated(useCommand(deps, (o) => tvalIsStaff(o.tval), USE.CHARGE)));
+    registry.register("aim-wand", gated(useCommand(deps, (o) => tvalIsWand(o.tval), USE.CHARGE)));
+    /* do_cmd_zap_rod (cmd-obj.c L832): tval_is_rod filter, obj_can_zap guard. */
+    registry.register("zap-rod", gated(useCommand(deps, (o) => tvalIsRod(o.tval), USE.TIMEOUT, {
+        ok: objCanZap,
+        msg: "That rod is still charging.",
+    })));
+    /* do_cmd_activate (cmd-obj.c L866): obj_is_activatable filter (a WEARABLE
+     * with an object_effect - which includes the kind-effect rings that have no
+     * activation), then the obj_can_activate guard. */
+    registry.register("activate", gated(useCommand(deps, objIsActivatable, USE.TIMEOUT, {
+        ok: objCanActivate,
+        msg: "That item is still charging.",
+    })));
+    /* do_cmd_inscribe (cmd-obj.c L179): set the note. Upstream's
+     * quark_add("") does NOT return 0 (z-quark.c L31: it adds a new,
+     * non-zero, empty quark, so obj->note stays truthy and object_desc
+     * renders " {}"). This port intentionally maps "" -> null instead: it is
+     * a deliberate normalization (not literal parity) that keeps note's
+     * truthiness meaningful for objectStackable/objectCombine (object.ts
+     * L844/L920), which already compare/merge notes by truthiness. No
+     * energy; upstream's PN_COMBINE/PN_IGNORE notice + PR_INVEN/PR_EQUIP
+     * redraw are UI bookkeeping this port doesn't model (combine already runs
+     * lazily on the next inven_carry; ignore/display refresh is #25). */
+    registry.register("inscribe", gated((state, cmd) => {
+        const found = commandObject(state, cmd);
+        if (!found)
+            return 0;
+        const raw = cmd.args?.["inscription"];
+        const text = typeof raw === "string" ? raw : "";
+        found.obj.note = text.length > 0 ? text : null;
+        return 0;
+    }));
+    /* do_cmd_uninscribe (cmd-obj.c L153). */
+    registry.register("uninscribe", gated((state, cmd) => {
+        const found = commandObject(state, cmd);
+        if (!found || !objHasInscrip(found.obj))
+            return 0;
+        found.obj.note = null;
+        deps.env?.msg?.("Inscription removed.");
+        return 0;
+    }));
+    /* do_cmd_autoinscribe (cmd-obj.c L219): not gated by
+     * player_get_resume_normal_shape - upstream just no-ops while
+     * shapechanged, with no resume prompt. */
+    registry.register("autoinscribe", (state, _cmd) => {
+        if (playerIsShapechanged(state))
+            return 0;
+        autoinscribeGround(state, deps);
+        autoinscribePack(state, deps);
+        return 0;
+    });
+    /* do_cmd_refill (cmd-obj.c L1071): validate the equipped light, then
+     * refill it from the chosen fuel source. Half a turn on success. */
+    registry.register("refill", gated((state, cmd) => {
+        const light = equippedLight(state);
+        if (!light || !tvalIsLight(light.tval)) {
+            deps.env?.msg?.("You are not wielding a light.");
+            return 0;
+        }
+        if (light.flags.has(OF.NO_FUEL) || !light.flags.has(OF.TAKES_FUEL)) {
+            deps.env?.msg?.("Your light cannot be refilled.");
+            return 0;
+        }
+        const found = commandObject(state, cmd);
+        if (!found || !objCanRefill(state, found.obj))
+            return 0;
+        refillLamp(state, light, found.obj, {
+            fromFloor: found.fromFloor,
+            ...(found.handle !== undefined ? { handle: found.handle } : {}),
+        }, deps);
+        return Math.trunc(state.z.moveEnergy / 2);
+    }));
+}
+//# sourceMappingURL=obj-cmd.js.map