@rpgm-tools/neo-angband-core 0.10.0

package/dist/game/gear.js

@@ -0,0 +1,1037 @@
+/**
+ * The player's gear store: the world/UI-owned side of carried objects.
+ *
+ * The parity Player (player/player.ts) deliberately omits struct player's
+ * gear list, keeping only equipment[] as per-body-slot object HANDLES
+ * (0 = empty). This module owns the objects those handles point at: a
+ * handle -> GameObject store plus an ordered pack of non-equipped handles.
+ * It ports the equipment/carry substrate and the birth starting-kit from
+ * reference/src/obj-gear.c (slot_by_type, wield_slot, inven_carry) and
+ * reference/src/player-birth.c (wield_all, player_outfit) (Angband 4.2.6).
+ *
+ * LIVE vs DEFERRED (ledgered in parity/ledger/game-gear.yaml):
+ * - LIVE: slot_by_type (empty-preferring), wield_slot (full tval switch),
+ *   inven_carry's merge-or-add with quiver stack-mode routing, wield_all's
+ *   split-and-wear, player_outfit's start-item roll + prep + carry + wield
+ *   (birth_start_kit + eopts exclusion honoured), the real quiver subsystem
+ *   (object_is_in_quiver, preferred_quiver_slot, quiver_absorb_num,
+ *   calc_inventory's quiver assignment, pack_slots_used quiver accounting),
+ *   combine_pack + inven_can_stack_partial, and minus_ac armour damage,
+ *   pack_is_full / pack_is_overfull (the pack_size overflow enforcement itself,
+ *   pack_overflow, needs drop_near and so lives in game/obj-cmd.ts next to the
+ *   other obj-gear.c verbs that touch the floor).
+ * - DEFERRED: the display knowledge twin (obj->known) and equip_cnt UI
+ *   counter.  The pack-side inven[] listing is a derived view rather than the
+ *   source of truth: gear.pack keeps master-gear insertion order while
+ *   gear.inven reproduces calc_inventory's earlier_object ordering. Wielding DOES learn modifier runes
+ *   (obj-knowledge.c object_learn_on_wield); see obj/knowledge.ts.
+ */
+import { ELEM, OF, ORIGIN, TV } from "../generated/index.js";
+import { tvalFindIdx } from "../obj/bind.js";
+import { learnBirthObviousFlags, objectLearnOnWield, OBJ_NOTICE } from "../obj/knowledge.js";
+import { distributeCharges, objectAbsorb, objectAbsorbPartial, objectMergeable, objectStackable, OSTACK_PACK, OSTACK_QUIVER, tvalCanHaveCharges, tvalCanHaveTimeout, tvalIsAmmo, tvalIsBodyArmor, tvalIsFood, tvalIsHeadArmor, tvalIsLight, tvalIsMeleeWeapon, tvalIsMoney, tvalIsRing, tvalIsRod, } from "../obj/object.js";
+import { EL_INFO_IGNORE } from "../obj/types.js";
+import { objectPrep } from "../obj/make.js";
+import { objectValueReal } from "../obj/value.js";
+import { earlierObject } from "../player/calcs.js";
+/** A fresh, empty gear store (empty quiver; calcInventory sizes it). */
+export function newGear() {
+    return { store: new Map(), next: 1, pack: [], inven: [], quiver: [] };
+}
+/** Store an object under a fresh handle and return it (no pack insertion). */
+export function gearAdd(gear, obj) {
+    const handle = gear.next;
+    gear.next += 1;
+    gear.store.set(handle, obj);
+    return handle;
+}
+/** The object for a handle, or null (0 / unknown handle -> null). */
+export function gearGet(gear, handle) {
+    return gear.store.get(handle) ?? null;
+}
+/* ------------------------------------------------------------------ */
+/* obj-util.c object copy / split                                       */
+/* ------------------------------------------------------------------ */
+/**
+ * object_copy (obj-util.c): a faithful deep copy of the live struct. The
+ * known twin and pile links are not part of GameObject (deferred), and
+ * kind/ego/artifact/activation/effect stay shared references exactly as
+ * upstream's memcpy leaves them.
+ */
+function objectCopy(src) {
+    return {
+        ...src,
+        flags: src.flags.clone(),
+        modifiers: [...src.modifiers],
+        elInfo: src.elInfo.map((e) => ({ resLevel: e.resLevel, flags: e.flags })),
+        brands: src.brands ? [...src.brands] : null,
+        slays: src.slays ? [...src.slays] : null,
+        curses: src.curses
+            ? src.curses.map((c) => ({ power: c.power, timeout: c.timeout }))
+            : null,
+        time: { ...src.time },
+    };
+}
+/**
+ * object_split (obj-util.c): split `amt` items off `src` into a fresh copy,
+ * distributing wand/staff/rod charges, and reduce src by amt. Requires
+ * src.number > amt (upstream assert). Exported for the floor-pile module
+ * (floor_object_for_use splits floor stacks the same way).
+ */
+export function objectSplit(src, amt) {
+    const dest = objectCopy(src);
+    /* Distribute charges of wands, staves, or rods (dest is a new stack). */
+    distributeCharges(src, dest, amt, true);
+    dest.number = amt;
+    src.number -= amt;
+    if (src.note)
+        dest.note = src.note;
+    return dest;
+}
+/* ------------------------------------------------------------------ */
+/* obj-gear.c slot logic                                                */
+/* ------------------------------------------------------------------ */
+/**
+ * slot_by_type (obj-gear.c L71-93): the index of a slot of the given type,
+ * preferring an empty one (full = false) or a full one (full = true), else
+ * any matching-type slot, else body.count when none exists.
+ *
+ * Upstream reads body.slots[i].obj to decide full/empty; here a slot is
+ * "filled" when equipment[i] !== 0, so the equipment array is passed in.
+ */
+function slotByType(body, equipment, type, full) {
+    let fallback = body.count;
+    let i = 0;
+    for (; i < body.count; i++) {
+        if (type === body.slots[i].type) {
+            const filled = (equipment[i] ?? 0) !== 0;
+            if (full) {
+                /* Found a full slot */
+                if (filled)
+                    break;
+            }
+            else {
+                /* Found an empty slot */
+                if (!filled)
+                    break;
+            }
+            /* Not right for full/empty, but still the right type */
+            if (fallback === body.count)
+                fallback = i;
+        }
+    }
+    /* Index for the best slot we found, or body.count if none found. */
+    return i !== body.count ? i : fallback;
+}
+/**
+ * wield_slot (obj-gear.c L341-367): the equipment slot an object of the
+ * given tval likes (an open slot preferred for rings), or -1 for a
+ * non-wearable tval.
+ *
+ * `equipment` (optional, defaults to all-empty) lets the empty-slot
+ * preference work; wieldObject/wieldAll pass the player's real equipment
+ * so a second ring lands in the free hand, matching upstream.
+ */
+export function wieldSlot(body, tval, equipment) {
+    const eq = equipment ?? new Array(body.count).fill(0);
+    switch (tval) {
+        case TV.BOW:
+            return slotByType(body, eq, "BOW", false);
+        case TV.AMULET:
+            return slotByType(body, eq, "AMULET", false);
+        case TV.CLOAK:
+            return slotByType(body, eq, "CLOAK", false);
+        case TV.SHIELD:
+            return slotByType(body, eq, "SHIELD", false);
+        case TV.GLOVES:
+            return slotByType(body, eq, "GLOVES", false);
+        case TV.BOOTS:
+            return slotByType(body, eq, "BOOTS", false);
+        default:
+            break;
+    }
+    if (tvalIsMeleeWeapon(tval))
+        return slotByType(body, eq, "WEAPON", false);
+    if (tvalIsRing(tval))
+        return slotByType(body, eq, "RING", false);
+    if (tvalIsLight(tval))
+        return slotByType(body, eq, "LIGHT", false);
+    if (tvalIsBodyArmor(tval))
+        return slotByType(body, eq, "BODY_ARMOR", false);
+    if (tvalIsHeadArmor(tval))
+        return slotByType(body, eq, "HAT", false);
+    /* No slot available */
+    return -1;
+}
+/* ------------------------------------------------------------------ */
+/* Quiver membership and slot preference (obj-gear.c)                   */
+/* ------------------------------------------------------------------ */
+/**
+ * object_is_in_quiver (obj-gear.c L163-174): is the object referenced by
+ * `handle` currently held in one of the computed quiver slots? A zero handle
+ * (empty slot / no object) is never in the quiver.
+ */
+export function objectIsInQuiver(gear, handle) {
+    if (handle === 0)
+        return false;
+    return (gear.quiver ?? []).includes(handle);
+}
+/**
+ * preferred_quiver_slot (obj-gear.c L1396-1427): the quiver slot an object's
+ * inscription asks for, or -1 when it is not quiver-appropriate or not
+ * inscribed with a matching @f/@v (fire / throw) key. The fire key depends on
+ * the keyset: 't' under rogue-like commands, else 'f'; the throw key is always
+ * 'v' (upstream hardwires these because cmd_lookup_key is in the UI layer).
+ */
+export function preferredQuiverSlot(obj, rogueLike = false) {
+    let desiredSlot = -1;
+    if (obj.note && (tvalIsAmmo(obj.tval) || obj.flags.has(OF.THROWING))) {
+        const fireKey = rogueLike ? "t" : "f";
+        const throwKey = "v";
+        let s = obj.note.indexOf("@");
+        while (s !== -1) {
+            const k = obj.note[s + 1];
+            if (k === fireKey || k === throwKey) {
+                /* s[2] - '0': the single digit slot after the key. */
+                desiredSlot = (obj.note.charCodeAt(s + 2) || 0) - "0".charCodeAt(0);
+                break;
+            }
+            s = obj.note.indexOf("@", s + 1);
+        }
+    }
+    return desiredSlot;
+}
+/* ------------------------------------------------------------------ */
+/* minus_ac (obj-gear.c L376-438)                                       */
+/* ------------------------------------------------------------------ */
+/** The non-armour equipment slot types minus_ac skips (obj-gear.c L387-391). */
+function slotIsArmour(type) {
+    return (type !== undefined &&
+        type !== "WEAPON" &&
+        type !== "BOW" &&
+        type !== "RING" &&
+        type !== "AMULET" &&
+        type !== "LIGHT");
+}
+/**
+ * minus_ac (obj-gear.c L376-438): acid has hit the player, so attempt to
+ * damage a piece of worn armour. Counts the armour slots, draws one at random
+ * with the exact upstream reverse one_in_(count--) scan, and (if that item can
+ * still lose armour) either reports it resists (EL_INFO_IGNORE on ELEM_ACID)
+ * or decrements its to_a and prints the damage message. Returns whether there
+ * was any effect (a piece was picked and had ac + to_a > 0), matching upstream
+ * so the caller can halve the elemental damage.
+ *
+ * The RNG draw order is preserved bit-for-bit: the forward count loop, then
+ * the reverse pick loop consuming one_in_(count--) per armour slot until it
+ * breaks. `obj->known->to_a = obj->to_a` (L425-426) is DEFERRED - the port has
+ * no per-object known twin (obj-knowledge #4.8); obj_k->to_a is 1 at birth so
+ * the real to_a is already the shown value.
+ */
+export function minusAc(player, gear, rng, env = {}) {
+    const body = player.body;
+    /* Avoid crash during monster power calculations (L382): no gear, no effect. */
+    if (gear.pack.length === 0 && player.equipment.every((h) => h === 0)) {
+        return false;
+    }
+    /* Count the armour slots (L384-395). */
+    let count = 0;
+    for (let i = 0; i < body.count; i++) {
+        if (slotIsArmour(body.slots[i]?.type))
+            count++;
+    }
+    /* Pick one at random with the reverse one_in_(count--) scan (L397-407). */
+    let picked = body.count;
+    for (let i = body.count - 1; i >= 0; i--) {
+        if (!slotIsArmour(body.slots[i]?.type))
+            continue;
+        if (rng.oneIn(count--)) {
+            picked = i;
+            break;
+        }
+    }
+    /* Get the item in the picked slot (L410). */
+    const handle = picked < body.count ? (player.equipment[picked] ?? 0) : 0;
+    const obj = handle !== 0 ? (gear.store.get(handle) ?? null) : null;
+    /* If we can still damage the item (L412-433). */
+    if (obj && obj.ac + obj.toA > 0) {
+        const name = env.describe ? env.describe(obj) : obj.kind.name;
+        const acidEl = obj.elInfo[ELEM.ACID];
+        if (acidEl && (acidEl.flags & EL_INFO_IGNORE) !== 0) {
+            env.msg?.(`Your ${name} is unaffected!`);
+        }
+        else {
+            env.msg?.(`Your ${name} is damaged!`);
+            obj.toA--;
+            /* DEFERRED: obj->known->to_a = obj->to_a (no known twin, #4.8). */
+            env.updateBonuses?.(); /* PU_BONUS */
+        }
+        /* There was an effect. */
+        return true;
+    }
+    /* No damage or effect (L435-436). */
+    return false;
+}
+/** inven_carry plus the C `combining` bit needed by pickup awareness. */
+export function invenCarryResult(gear, obj, limits) {
+    /* Check for combining with an existing non-equipped stack. */
+    for (const handle of gear.pack) {
+        const stack = gear.store.get(handle);
+        const mode = objectIsInQuiver(gear, handle) ? OSTACK_QUIVER : OSTACK_PACK;
+        if (stack && objectMergeable(stack, obj, mode, limits)) {
+            objectAbsorb(stack, obj, ORIGIN.MIXED);
+            return { handle, combining: true };
+        }
+    }
+    /* We did not find an object to combine with: add a new pack handle. */
+    const handle = gearAdd(gear, obj);
+    gear.pack.push(handle);
+    return { handle, combining: false };
+}
+export function invenCarry(gear, obj, limits) {
+    return invenCarryResult(gear, obj, limits).handle;
+}
+/* ------------------------------------------------------------------ */
+/* inven_carry_num / object_copy_amt / gear_object_for_use             */
+/* ------------------------------------------------------------------ */
+/**
+ * pack_slots_used (obj-gear.c L257-296): the number of pack slots occupied.
+ * Equipped items don't count (they are absent from `pack`); ammo / throwing
+ * items assigned to the quiver aggregate by weighted count into quiver slots
+ * of quiver_slot_size, so a non-empty quiver frees up whole pack slots. When
+ * the quiver is empty this equals pack.length (every item is a pack slot).
+ */
+export function packSlotsUsed(gear, constants) {
+    let packSlots = 0;
+    let quiverAmmo = 0;
+    for (const handle of gear.pack) {
+        const obj = gear.store.get(handle);
+        if (!obj)
+            continue;
+        let found = false;
+        if (tvalIsAmmo(obj.tval) || obj.flags.has(OF.THROWING)) {
+            if (objectIsInQuiver(gear, handle)) {
+                quiverAmmo +=
+                    obj.number * (tvalIsAmmo(obj.tval) ? 1 : constants.thrownQuiverMult);
+                found = true;
+            }
+        }
+        /* Count regular slots. */
+        if (!found)
+            packSlots++;
+    }
+    /* Full slots, plus one for any remainder. */
+    packSlots += Math.trunc(quiverAmmo / constants.quiverSlotSize);
+    if (quiverAmmo % constants.quiverSlotSize)
+        packSlots++;
+    return packSlots;
+}
+/**
+ * pack_is_full (obj-gear.c L1328-1331): the pack holds exactly the maximum
+ * number of items.
+ */
+export function packIsFull(gear, constants) {
+    return packSlotsUsed(gear, constants) === constants.packSize;
+}
+/**
+ * pack_is_overfull (obj-gear.c L1337-1340): the pack holds MORE than the
+ * maximum, so pack_overflow (game/obj-cmd.ts) will shed an item.
+ */
+export function packIsOverfull(gear, constants) {
+    return packSlotsUsed(gear, constants) > constants.packSize;
+}
+/**
+ * quiver_absorb_num (obj-gear.c L649-744): how many of `obj` the quiver can
+ * take, and how many additional pack slots that costs. Reads the current
+ * computed quiver (gear.quiver) exactly as upstream reads p->upkeep->quiver.
+ * `nAddPack` is the number of extra pack slots the quiver may claim; the return
+ * carries the leftover (nAddPack minus the slots consumed) alongside nToQuiver.
+ */
+export function quiverAbsorbNum(gear, obj, constants, nAddPack, rogueLike = false) {
+    const ammo = tvalIsAmmo(obj.tval);
+    /* Must be ammo or good for throwing (L655). */
+    if (ammo || obj.flags.has(OF.THROWING)) {
+        let quiverCount = 0;
+        let spaceFree = 0;
+        let nEmpty = 0;
+        const desiredSlot = preferredQuiverSlot(obj, rogueLike);
+        let displaces = false;
+        const qSize = constants.quiverSize;
+        const qSlot = constants.quiverSlotSize;
+        const quiver = gear.quiver ?? [];
+        /* Count the current space this object could go into (L660-710). */
+        for (let i = 0; i < qSize; i++) {
+            const qHandle = quiver[i] ?? 0;
+            const quiverObj = qHandle !== 0 ? gear.store.get(qHandle) : undefined;
+            if (quiverObj) {
+                const mult = tvalIsAmmo(quiverObj.tval) ? 1 : constants.thrownQuiverMult;
+                quiverCount += quiverObj.number * mult;
+                if (objectStackable(quiverObj, obj, OSTACK_PACK)) {
+                    spaceFree += qSlot - quiverObj.number * mult;
+                }
+                else if (desiredSlot === i &&
+                    preferredQuiverSlot(quiverObj, rogueLike) !== i) {
+                    /* The added object prefers this slot, but it is occupied by a stack
+                     * that could be displaced elsewhere if a slot is available. */
+                    displaces = true;
+                    if (ammo) {
+                        spaceFree += qSlot - quiverObj.number * mult;
+                    }
+                    else {
+                        spaceFree += qSlot;
+                    }
+                }
+            }
+            else {
+                nEmpty++;
+                /* Ammo fits any empty slot; a non-ammo throwing item only its
+                 * preferred slot (L699-708). */
+                if (ammo || desiredSlot === i) {
+                    spaceFree += qSlot;
+                }
+            }
+        }
+        /* Only addable if there is free space and we either displace a pile with an
+         * empty slot available or don't displace at all (L712-738). */
+        if (spaceFree && ((displaces && nEmpty) || !displaces)) {
+            const mult = ammo ? 1 : constants.thrownQuiverMult;
+            const remainder = quiverCount % qSlot;
+            let limitFromPack = remainder ? qSlot - remainder : 0;
+            if (nAddPack > 0)
+                limitFromPack += nAddPack * qSlot;
+            spaceFree = Math.min(spaceFree, limitFromPack);
+            const nToQuiver = Math.min(obj.number, Math.trunc(spaceFree / mult));
+            const usedPack = nAddPack -
+                Math.trunc((nToQuiver * mult + qSlot - 1 - remainder) / qSlot);
+            return { nToQuiver, nAddPack: usedPack };
+        }
+    }
+    /* Not suitable for the quiver or no space (L742-743). */
+    return { nToQuiver: 0, nAddPack };
+}
+/**
+ * inven_carry_num (obj-gear.c L749-780): how many of `obj` the gear can accept
+ * across quiver and pack. The quiver absorbs what it can first; then a free
+ * pack slot takes the rest, or the remainder squeezes into partially-full
+ * stackable pack slots.
+ */
+export function invenCarryNum(gear, obj, constants) {
+    /* Treasure can always be picked up (never reached via a store). */
+    if (tvalIsMoney(obj.tval))
+        return obj.number;
+    const nFreeSlot = constants.packSize - packSlotsUsed(gear, constants);
+    /* Absorb as many as we can in the quiver (L760). quiver_absorb_num DECREMENTS
+     * the free-slot count by the pack slots the quiver expands into (via
+     * &n_free_slot); the port returns that decremented value as nAddPack. GR-01:
+     * the >0 test must use the decremented nAddPack, not the pre-call nFreeSlot,
+     * or capacity is over-reported when the quiver eats free pack slots but still
+     * cannot hold the whole stack. */
+    const { nToQuiver, nAddPack } = quiverAbsorbNum(gear, obj, constants, nFreeSlot);
+    /* The quiver will get everything, or the pack can hold what's left (L763). */
+    if (nToQuiver === obj.number || nAddPack > 0)
+        return obj.number;
+    /* See if we can add to partially-full inventory slots (L767-776). GR-02:
+     * upstream iterates p->upkeep->inven[], which EXCLUDES ammo already sitting
+     * in the quiver; gear.pack still carries those handles, so a stackable
+     * quiver ammo stack would be double-counted as pack free space. Skip any
+     * handle that is in the quiver. */
+    let numLeft = obj.number - nToQuiver;
+    for (const handle of gear.pack) {
+        if (objectIsInQuiver(gear, handle))
+            continue;
+        const stack = gear.store.get(handle);
+        if (stack && objectStackable(stack, obj, OSTACK_PACK)) {
+            numLeft -= stack.kind.base.maxStack - stack.number;
+            if (numLeft <= 0)
+                break;
+        }
+    }
+    return obj.number - Math.max(numLeft, 0);
+}
+/** Build EarlierObjectOpts (ammo tiebreak) from the calc-inventory opts. */
+function earlierOpts(opts) {
+    const e = { store: false };
+    if (opts.ammoTval !== undefined)
+        e.ammoTval = opts.ammoTval;
+    if (opts.objectValue)
+        e.objectValue = opts.objectValue;
+    if (opts.isAware)
+        e.isAware = opts.isAware;
+    if (opts.canBrowse)
+        e.canBrowse = opts.canBrowse;
+    return e;
+}
+/**
+ * calc_inventory (player-calcs.c:1023-1238): rebuild gear.quiver and the
+ * separate sorted gear.inven listing.  `gear.pack` remains the raw master-gear
+ * order, so changing this derived view cannot destabilize combine/split logic.
+ * from the current non-equipped gear. First place inscribed items in their
+ * preferred slots (splitting a stack that overflows quiver_slot_size, with the
+ * excess going back to the pack), then fill the remaining slots in earlier_object
+ * order with ammo.  Then select each remaining non-quiver handle in
+ * earlier_object order, exactly as upstream fills upkeep->inven[].
+ *
+ * Split remainders are appended to gear.pack via object_split, exactly as
+ * upstream's gear_insert_end. `n_stack_split <= n_pack_remaining` guards splits
+ * so the pack can overflow by at most one slot, matching upstream.
+ */
+export function calcInventory(gear, constants, opts = {}) {
+    const qSize = constants.quiverSize;
+    const qSlot = constants.quiverSlotSize;
+    const rogueLike = opts.rogueLike ?? false;
+    let nStackSplit = 0;
+    const nPackRemaining = constants.packSize - packSlotsUsed(gear, constants);
+    /* Copy the current quiver, then empty it (L1053-1061). */
+    const oldQuiver = [];
+    for (let i = 0; i < qSize; i++)
+        oldQuiver[i] = gear.quiver?.[i] ?? 0;
+    const quiver = new Array(qSize).fill(0);
+    gear.quiver = quiver;
+    const assigned = new Set();
+    /* Fill quiver.  First, allocate inscribed items (L1063-1117). */
+    for (const handle of [...gear.pack]) {
+        const current = gear.store.get(handle);
+        if (!current)
+            continue;
+        const prefslot = preferredQuiverSlot(current, rogueLike);
+        if (prefslot >= 0 && prefslot < qSize && (quiver[prefslot] ?? 0) === 0) {
+            const mult = tvalIsAmmo(current.tval) ? 1 : constants.thrownQuiverMult;
+            let toQuiver = false;
+            if (current.number * mult <= qSlot) {
+                toQuiver = true;
+            }
+            else {
+                const nsplit = Math.trunc(qSlot / mult);
+                if (nsplit > 0 && nStackSplit <= nPackRemaining) {
+                    /* Split off the portion that goes to the pack; the quiver stack is
+                     * earlier in the gear list so it stays preferred (L1091-1102). */
+                    const rem = objectSplit(current, current.number - nsplit);
+                    gear.pack.push(gearAdd(gear, rem));
+                    nStackSplit++;
+                    toQuiver = true;
+                }
+            }
+            if (toQuiver) {
+                quiver[prefslot] = handle;
+                assigned.add(handle);
+            }
+        }
+    }
+    /* Now fill the rest of the slots in order (L1119-1172). */
+    for (let i = 0; i < qSize; i++) {
+        if ((quiver[i] ?? 0) !== 0)
+            continue;
+        let first = null;
+        let firstHandle = 0;
+        for (const handle of gear.pack) {
+            if (assigned.has(handle))
+                continue;
+            const current = gear.store.get(handle);
+            if (!current || !tvalIsAmmo(current.tval))
+                continue;
+            /* Only assign if, when a split is needed, there is room for it. */
+            if (current.number <= qSlot ||
+                (qSlot > 0 && nStackSplit <= nPackRemaining)) {
+                if (earlierObject(first, current, earlierOpts(opts))) {
+                    first = current;
+                    firstHandle = handle;
+                }
+            }
+        }
+        /* Nothing left in the gear. */
+        if (!first)
+            break;
+        /* Put it in the slot, splitting (if needed) to fit (L1159-1168). */
+        if (first.number > qSlot) {
+            const rem = objectSplit(first, first.number - qSlot);
+            gear.pack.push(gearAdd(gear, rem));
+            nStackSplit++;
+        }
+        quiver[i] = firstHandle;
+        assigned.add(firstHandle);
+    }
+    /* Note reordering (L1174-1182). */
+    if (opts.characterDungeon) {
+        for (let i = 0; i < qSize; i++) {
+            if ((oldQuiver[i] ?? 0) !== 0 && quiver[i] !== oldQuiver[i]) {
+                opts.msg?.("You re-arrange your quiver.");
+                break;
+            }
+        }
+    }
+    /* Copy the current pack (L1183-1186) and remember how full it was (L1025),
+     * both read only by the re-arrange notice below. */
+    const oldInvenCnt = (gear.inven ?? []).length;
+    const oldPack = [...(gear.inven ?? [])];
+    /* Fill upkeep->inven[] (player-calcs.c:1191-1222).  Do not sort pack in
+     * place: C's p->gear remains its own linked-list order and inven[] is only
+     * a listing.  Repeated first-selection (rather than Array.sort()) faithfully
+     * preserves master-gear order when earlier_object has no preference. */
+    const inven = [];
+    const invenAssigned = new Set(quiver.filter((h) => h !== 0));
+    for (;;) {
+        let first = null;
+        let firstHandle = 0;
+        for (const handle of gear.pack) {
+            if (invenAssigned.has(handle))
+                continue;
+            const current = gear.store.get(handle);
+            if (current && earlierObject(first, current, earlierOpts(opts))) {
+                first = current;
+                firstHandle = handle;
+            }
+        }
+        if (!first)
+            break;
+        inven.push(firstHandle);
+        invenAssigned.add(firstHandle);
+    }
+    gear.inven = inven;
+    /* Note reordering (L1224-1233). The quiver half of this notice was ported;
+     * the pack half was not, so shuffling the pack was silent. Only fires when
+     * the pack holds the SAME number of items as before (L1225) - a pickup or a
+     * drop reorders it too, and upstream does not call that a re-arrangement. */
+    if (opts.characterDungeon && inven.length === oldInvenCnt) {
+        for (let i = 0; i < constants.packSize; i++) {
+            const was = oldPack[i] ?? 0;
+            if (was === 0)
+                continue;
+            if (inven[i] === was)
+                continue;
+            if (opts.isEquipped?.(was))
+                continue;
+            opts.msg?.("You re-arrange your pack.");
+            break;
+        }
+    }
+}
+/**
+ * inven_can_stack_partial (obj-gear.c L1183-1236): can obj1 and obj2 be merged
+ * into two uneven stacks, with obj1 the (maximised) leading stack? Refuses when
+ * obj1 is already at its per-stack limit, and (for a quiver->pack move) when the
+ * quiver has no room, to avoid combining then re-splitting in calc_inventory.
+ */
+function invenCanStackPartial(gear, obj1, obj2, mode1, mode2, constants) {
+    const cmode = mode1 | mode2;
+    if (!objectStackable(obj1, obj2, cmode))
+        return false;
+    /* Verify the numbers suit uneven stacks (L1196-1233). OSTACK_STORE absorbs
+     * without limit; the port's combine_pack never passes it. */
+    if (mode1 & OSTACK_QUIVER) {
+        const qlimit = Math.trunc(constants.quiverSlotSize /
+            (tvalIsAmmo(obj1.tval) ? 1 : constants.thrownQuiverMult));
+        if (obj1.number === qlimit)
+            return false;
+        /* Moving items INTO the quiver: also check the overall quiver limits. */
+        if (mode2 & ~OSTACK_QUIVER) {
+            const nFreeSlot = constants.packSize - packSlotsUsed(gear, constants);
+            const { nToQuiver } = quiverAbsorbNum(gear, obj2, constants, nFreeSlot);
+            if (nToQuiver <= 0)
+                return false;
+        }
+    }
+    else if (obj1.number === obj1.kind.base.maxStack) {
+        return false;
+    }
+    return true;
+}
+/**
+ * combine_pack (obj-gear.c L1242-1323): sweep the gear from the back, merging
+ * each stack fully into an earlier compatible stack where possible, else moving
+ * items between stacks into two uneven stacks (inven_can_stack_partial). Runs
+ * calc_inventory afterward. Returns whether any full combine happened (upstream
+ * shows "You combine some items in your pack." and disables command repeat).
+ */
+export function combinePack(gear, constants, opts = {}) {
+    const limits = {
+        quiverSlotSize: constants.quiverSlotSize,
+        thrownQuiverMult: constants.thrownQuiverMult,
+    };
+    let displayMessage = false;
+    /* Combine the pack (backwards) over a snapshot; removals mutate gear.pack. */
+    for (const h1 of [...gear.pack].reverse()) {
+        const obj1 = gear.store.get(h1);
+        if (!obj1)
+            continue;
+        const idx1 = gear.pack.indexOf(h1);
+        if (idx1 < 0)
+            continue;
+        /* Scan the items above obj1 (L1256). */
+        for (let k = 0; k < idx1; k++) {
+            const h2 = gear.pack[k];
+            const obj2 = gear.store.get(h2);
+            if (!obj2)
+                continue;
+            const mode2 = objectIsInQuiver(gear, h2) ? OSTACK_QUIVER : OSTACK_PACK;
+            if (objectMergeable(obj2, obj1, mode2, limits)) {
+                objectAbsorb(obj2, obj1, ORIGIN.MIXED);
+                gear.pack.splice(idx1, 1);
+                gear.store.delete(h1);
+                displayMessage = true;
+                break;
+            }
+            const mode1 = objectIsInQuiver(gear, h1) ? OSTACK_QUIVER : OSTACK_PACK;
+            if (invenCanStackPartial(gear, obj2, obj1, mode2, mode1, constants)) {
+                /* Shuffling items between stacks - no message (L1282-1287). */
+                objectAbsorbPartial(obj2, obj1, mode2, mode1, limits, ORIGIN.MIXED);
+                break;
+            }
+        }
+    }
+    calcInventory(gear, constants, opts);
+    if (displayMessage)
+        opts.msg?.("You combine some items in your pack.");
+    return displayMessage;
+}
+/**
+ * object_copy_amt (obj-pile.c L743): a fresh copy of `src` holding `amt`
+ * items, with wand/staff charges and rod/activation timeouts scaled to the
+ * split (source unchanged). The AVERAGE charge time is deterministic.
+ */
+export function objectCopyAmt(src, amt) {
+    const dest = objectCopy(src);
+    dest.number = amt;
+    if (tvalCanHaveCharges(src.tval)) {
+        dest.pval = Math.trunc((src.pval * amt) / src.number);
+    }
+    if (tvalCanHaveTimeout(src.tval)) {
+        /* randcalc(src->time, 0, AVERAGE). */
+        const t = src.time;
+        const chargeTime = t.base + Math.trunc((t.dice * (t.sides + 1)) / 2);
+        const maxTime = chargeTime * amt;
+        dest.timeout = src.timeout > maxTime ? maxTime : src.timeout;
+    }
+    return dest;
+}
+/**
+ * gear_to_label's label alphabet (obj-gear.c:446): a-z minus the roguelike
+ * cardinal-movement keys h/j/k/l, then A-Z. An equipment slot index and a pack
+ * LISTING index both index straight into it (L452, L465).
+ */
+export const GEAR_LABELS = "abcdefgimnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+/**
+ * gear_to_label (obj-gear.c:443-469): the one-character label for a held object -
+ * an equipment slot letter, a quiver slot digit (I2D), or a pack listing letter.
+ * "" when the handle is not currently held, upstream's '\0'.
+ *
+ * THE LISTING, NOT THE STORAGE ORDER. Upstream's pack arm reads
+ * `p->upkeep->inven[]` (L462-466) - the earlier_object-sorted view calc_inventory
+ * builds and every inventory display walks - NOT the master gear list. The port
+ * had three copies of this function (game/project-obj.ts, game/obj-cmd.ts,
+ * game/known.ts) and all three read `gear.pack`, the raw storage order, because
+ * they were written while `gear.inven` was still an unbuilt stand-in. calcInventory
+ * has filled `inven` for some time, so every one of them was quoting a letter the
+ * pack listing disagreed with: pick up a scroll into raw slot 8 of a pack that
+ * sorts it fourth and the message says (i) while the item is at (e) and (i) holds
+ * whatever sorted eighth. Same defect class as #92, one layer further in - the
+ * listings were fixed and the MESSAGES about them were not.
+ *
+ * Deliberately reads `inven` with no fallback to `pack`. A wrong letter is worse
+ * than a missing one: it sends the player to another item, and no census can see
+ * it because the slot is filled (paraphrase-is-a-deviation). If `inven` is stale
+ * the caller has skipped upstream's PU_INVEN/update_stuff, which is a bug to fix
+ * at that caller - gear-label-freshness.test.ts asserts the invariant holds after
+ * every gear mutation the live session performs.
+ *
+ * `equipment` is optional because most callers hold a Gear and no Player; a pack
+ * or quiver handle is never in equipment[], so omitting it cannot mislabel one.
+ */
+export function gearToLabel(gear, handle, equipment) {
+    /* Equipment is easy (L450-453). */
+    if (equipment) {
+        const eq = equipment.indexOf(handle);
+        if (eq >= 0)
+            return GEAR_LABELS[eq] ?? "";
+    }
+    /* Check the quiver (L455-460). */
+    const qi = gear.quiver?.indexOf(handle) ?? -1;
+    if (qi >= 0)
+        return String(qi);
+    /* Check the inventory (L462-466). */
+    const pi = (gear.inven ?? []).indexOf(handle);
+    if (pi >= 0 && pi < GEAR_LABELS.length)
+        return GEAR_LABELS[pi];
+    return "";
+}
+/**
+ * The p->gear view object_pack_total walks, built from the live gear.
+ *
+ * Upstream iterates all of p->gear and lets object_similar reject the equipped
+ * entries; the port's objectSimilar has the equipped test deferred (obj/object.ts
+ * module docs), so the view is built from the non-equipped handles instead. The
+ * resulting SET is the same, which is all object_pack_total reads.
+ */
+export function packTotalView(gear) {
+    const objs = [];
+    const labels = new Map();
+    for (const handle of gear.pack) {
+        const obj = gear.store.get(handle);
+        if (!obj)
+            continue;
+        objs.push(obj);
+        labels.set(obj, gearToLabel(gear, handle));
+    }
+    return {
+        gear: objs,
+        /* Never: the view holds only non-equipped handles (see above). */
+        isEquipped: () => false,
+        gearToLabel: (obj) => labels.get(obj) ?? "",
+    };
+}
+/**
+ * Whether upstream suppresses the split-stack aggregate for this object.
+ *
+ * A charges count or "recharging" notice in the description belongs to ONE
+ * stack, so aggregating the number across stacks would contradict the notice
+ * printed beside it. Upstream repeats this test verbatim at every aggregate
+ * site - gear_object_for_use (obj-gear.c L550-556, L583-589), inven_carry
+ * (L899-901) and inven_drop (L1138-1140) - the last two of which also test
+ * object_is_equipped, which the callers here add because inven_carry does not.
+ */
+export function packTotalSuppressed(obj) {
+    return tvalCanHaveCharges(obj.tval) || tvalIsRod(obj.tval) || obj.timeout > 0;
+}
+/**
+ * Detach `handle` (or the free equipment/pack slot holding it) from the
+ * gear. A pack handle is removed from the ordered pack; an equipped handle
+ * clears its body slot. Either way the handle leaves the store map.
+ */
+function gearExcise(gear, player, handle) {
+    /* Clear any stale quiver reference (calc_inventory rebuilds it). */
+    if (gear.quiver) {
+        const qi = gear.quiver.indexOf(handle);
+        if (qi >= 0)
+            gear.quiver[qi] = 0;
+    }
+    const pi = gear.pack.indexOf(handle);
+    if (pi >= 0) {
+        gear.pack.splice(pi, 1);
+        gear.store.delete(handle);
+        return;
+    }
+    const si = player.equipment.indexOf(handle);
+    if (si >= 0) {
+        player.equipment[si] = 0;
+        gear.store.delete(handle);
+    }
+}
+/**
+ * gear_object_for_use (obj-gear.c L524): remove `amt` items of the gear
+ * object referenced by `handle`, returning a detached object to hand off.
+ * When part of a stack is taken, the remainder stays under `handle` and a
+ * fresh split is returned (noneLeft=false); when the whole stack is taken,
+ * the original is excised (noneLeft=true). The total_weight upkeep and the
+ * knowledge twin are DEFERRED (see the module ledger).
+ */
+export function gearObjectForUse(gear, player, handle, amt) {
+    const obj = gear.store.get(handle);
+    if (!obj)
+        throw new Error(`gearObjectForUse: no object for handle ${handle}`);
+    const num = Math.min(amt, obj.number);
+    /* Split off a usable object if we are not taking the whole stack. */
+    if (obj.number > num) {
+        const usable = objectSplit(obj, num);
+        return { obj: usable, noneLeft: false };
+    }
+    /* Using the entire stack. */
+    gearExcise(gear, player, handle);
+    return { obj, noneLeft: true };
+}
+/**
+ * Wield the pack object with the given handle into its liked slot. If the
+ * stack has more than one item it is split, following `split` (see
+ * WieldSplit - the two upstream callers differ). Returns the filled slot, or
+ * -1 if the object cannot be wielded or the slot is already occupied. Read
+ * `player.equipment[slot]` for the handle that ended up worn: under
+ * "inven_wield" a split stack equips a FRESH handle, not `handle`.
+ *
+ * object_learn_on_wield runs the instant the item is worn (as in wield_all
+ * and inven_wield), so a worn item's modifier runes become known and its
+ * pval bonuses go live at once. The equip_cnt UI counter is DEFERRED.
+ *
+ * `intoSlot` is the slot ARGUMENT upstream's inven_wield takes
+ * (`void inven_wield(struct object *obj, int slot)`, obj-gear.c:931): the caller
+ * decides the destination and inven_wield never recomputes it. That matters for
+ * rings - do_cmd_wield asks "Replace which ring? " and then overwrites slot with
+ * `equipped_item_slot(player->body, equip_obj)` (cmd-obj.c:309), so re-deriving
+ * it here would silently discard the hand the player picked. Omit it to keep the
+ * wield_slot default (wield_all and every non-choosing caller).
+ */
+export function wieldObject(gear, player, handle, env, split = "wield_all", intoSlot) {
+    const obj = gear.store.get(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;
+    if ((player.equipment[slot] ?? 0) !== 0)
+        return -1;
+    /* Split if necessary. */
+    let wieldedHandle = handle;
+    let wielded = obj;
+    if (obj.number > 1) {
+        if (split === "inven_wield") {
+            /* One item off the stack becomes the worn object; the original stays
+             * put in the pack holding number - 1 (obj-gear.c L947-968). */
+            wielded = objectSplit(obj, 1);
+            wieldedHandle = gearAdd(gear, wielded);
+        }
+        else {
+            /* All but one go back to the pack as a new stack at the END
+             * (player-birth.c L484-491 + L502-505). */
+            const remainder = objectSplit(obj, obj.number - 1);
+            gear.pack.push(gearAdd(gear, remainder));
+        }
+    }
+    /* Remove the wielded handle from the pack and wear it. A fresh
+     * "inven_wield" split was never in the pack, so the splice no-ops and the
+     * original keeps its listing position. */
+    const idx = gear.pack.indexOf(wieldedHandle);
+    if (idx >= 0)
+        gear.pack.splice(idx, 1);
+    player.equipment[slot] = wieldedHandle;
+    /* Learn the runes that wearing makes obvious (obj-knowledge.c wield_all
+     * L494-495). With an env the full obvious-flag/curse learning runs; the
+     * env-less path (birth outfit, worldless tests) learns the modifier
+     * runes, so worn pval bonuses apply immediately either way. */
+    objectLearnOnWield(player, wielded, env);
+    return slot;
+}
+/**
+ * wield_all (player-birth.c L462-507): try to wield everything wieldable in
+ * the pack. Scans a snapshot of the current pack handles (so the split-off
+ * remainders added during the pass are not re-scanned, matching upstream's
+ * deferred pile_insert_end), wielding each object whose liked slot is empty.
+ */
+export function wieldAll(gear, player) {
+    const handles = [...gear.pack];
+    for (const handle of handles) {
+        const obj = gear.store.get(handle);
+        if (!obj)
+            continue;
+        /* Make sure we can wield it into an empty slot. */
+        const slot = wieldSlot(player.body, obj.tval, player.equipment);
+        if (slot < 0 || slot >= player.body.count)
+            continue;
+        if ((player.equipment[slot] ?? 0) !== 0)
+            continue;
+        wieldObject(gear, player, handle);
+    }
+}
+/**
+ * Evaluate a start_item's eopts birth-option exclusion (player-birth.c
+ * L619-637): each token is an option name, optionally "NOT-" prefixed
+ * (init.c L3619-3634 stores +ind / -ind). A plain option excludes the item
+ * when it is SET; a NOT- option excludes it when it is UNSET. Returns true if
+ * the item should be included. With no accessor, nothing is excluded.
+ */
+function startItemIncluded(eopts, opt) {
+    if (eopts.length === 0 || !opt)
+        return true;
+    for (const token of eopts) {
+        const negated = token.startsWith("NOT-");
+        const name = negated ? token.slice(4) : token;
+        if (negated) {
+            if (!opt(name))
+                return false;
+        }
+        else {
+            if (opt(name))
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * player_outfit (player-birth.c L584-666): give the player their class
+ * starting equipment and wield everything wieldable.
+ *
+ * For each class start_item: roll the count in [min, max] via the project
+ * Rng (rand_range), look the kind up by tval/sval name, honour birth_start_kit
+ * (gap 1.6) and the eopts birth-option exclusion (gap 1.8), prep it with
+ * MINIMISE at level 0 (object_prep), set number and ORIGIN_BIRTH, carry it
+ * (invenCarry), and finally wield_all.
+ *
+ * wield_all learns each worn item's modifier runes (object_learn_on_wield);
+ * for a default class kit those items carry no modifiers, so obj_k stays
+ * empty at birth exactly as upstream.
+ *
+ * Each item is marked OBJ_NOTICE_ASSESSED (L652), the per-object half of the
+ * knowledge block that the port models on the live object, and reported through
+ * opts.onStartKind for object_flavor_aware (L650) - which the caller applies
+ * once the per-game awareness store exists (see OutfitOptions.onStartKind).
+ */
+export function outfitPlayer(gear, player, reg, rng, constants, opts = {}) {
+    const startKit = opts.startKit ?? (opts.opt ? opts.opt("birth_start_kit") : true);
+    const limits = {
+        quiverSlotSize: constants.quiverSlotSize,
+        thrownQuiverMult: constants.thrownQuiverMult,
+    };
+    /* Currently carrying nothing (running total is owned by the calc/inventory
+     * side, which is DEFERRED; we mirror only the reset upstream performs). */
+    player.upkeep.totalWeight = 0;
+    /* Give the player obvious object knowledge (player-birth.c L597-602): the
+     * LIGHT / DIG / THROW / CURSE_ONLY subtype flags are known from birth. Without
+     * this a mundane torch / digger / thrown item would read as not-fully-known
+     * and show a spurious "{??}" in stores and lists. (The dd/ds/ac and combat
+     * runes from the same upstream block are set in blankObjKnowledge.) */
+    learnBirthObviousFlags(player.objKnown.flags, reg.properties);
+    /* Modifier runes are learned per item at wield_all (below); the display
+     * half of the knowledge block (flavor_aware / base_known) is DEFERRED. */
+    /* Give the player starting equipment. */
+    for (const si of player.cls.startItems) {
+        let num = rng.randRange(si.min, si.max);
+        const tval = tvalFindIdx(si.tval);
+        if (tval < 0)
+            throw new Error(`outfit: unknown tval ${si.tval}`);
+        const sval = reg.lookupSval(tval, si.sval);
+        if (sval < 0)
+            throw new Error(`outfit: unknown sval ${si.tval}:${si.sval}`);
+        const kind = reg.lookupKind(tval, sval);
+        if (!kind)
+            throw new Error(`outfit: no kind ${si.tval}:${si.sval}`);
+        /* Without start_kit, only start with 1 food and 1 light. (Upstream
+         * tval_is_food_k / tval_is_light_k are TV_FOOD / TV_LIGHT only.) */
+        if (!startKit) {
+            if (!tvalIsFood(tval) && !tvalIsLight(tval))
+                continue;
+            num = 1;
+        }
+        /* Exclude if configured to do so based on birth options (player-birth.c
+         * L619-637). RNG order is preserved: rand_range(num) is drawn above, before
+         * any continue, exactly as upstream. */
+        if (!startItemIncluded(si.eopts, opts.opt))
+            continue;
+        /* Prepare a new item. */
+        const obj = objectPrep(rng, reg, constants, kind, 0, "minimise");
+        obj.number = num;
+        obj.origin = ORIGIN.BIRTH;
+        /* Deduct the cost of the item from starting cash (player-birth.c L654).
+         * object_value_real draws no RNG. Upstream prices from obj->known; the
+         * port has no known twin, so it prices the real object - the same
+         * approximation the store path uses (obj/value.ts). */
+        player.au -= objectValueReal(reg, obj, obj.number);
+        /* obj->known->notice |= OBJ_NOTICE_ASSESSED (player-birth.c L652): a start
+         * item has been handled, so it is assessed from birth. The port keeps that
+         * per-object bit on the live object (objectKnownShadow mirrors it), and
+         * without it the synthesised shadow returned before the flag/element
+         * intersection - so a Wooden Torch's own BURNS_OUT / LIGHT_2 flags read as
+         * UNKNOWN and the character sheet printed '?' down the torch's column even
+         * though those flags are known from birth (learnBirthObviousFlags above). */
+        obj.notice |= OBJ_NOTICE.ASSESSED;
+        /* object_flavor_aware(p, obj) (player-birth.c:650). Deferred to the caller
+         * because the awareness store does not exist yet - see onStartKind. */
+        opts.onStartKind?.(kind);
+        /* Carry the item. */
+        invenCarry(gear, obj, limits);
+    }
+    /* Sanity check: never let the outfit drive starting gold negative
+     * (player-birth.c L662). */
+    if (player.au < 0)
+        player.au = 0;
+    /* Now try wielding everything. */
+    wieldAll(gear, player);
+}
+//# sourceMappingURL=gear.js.map