azeroth-shell 0.0.0-stage → 0.1.0

package/src/engine/game/vendorOffers.ts

@@ -0,0 +1,244 @@
+// Vendor shelf resolution: what one purchase costs and delivers, and what limited supply is left. The
+// single resolver every vendor surface reads, so a tile cannot promise what the buy then refuses.
+
+import { buyCostCopper } from '../../domain/economy/trading.ts';
+import { getRank, reputationPriceDiscount, REP_RANK } from '../../domain/creature/reputation.ts';
+import {
+  calculateHonorRank,
+  highestInternalRank,
+  honorRankRequirementTitle,
+} from '../../domain/run/honor.ts';
+import { honorPriceOf } from '../../domain/economy/honorPrice.ts';
+import { factionOf } from '../../domain/character/races.ts';
+import { RANK_NAMES } from '../../domain/creature/reputation.ts';
+import { getFactionReaction, playerFactionTemplateId } from '../../domain/creature/faction.ts';
+import { creatureRepFactionId } from '../../domain/creature/faction.ts';
+import { getVendorItemCurrentCount, type VendorStockDef, type VendorItemCountState } from '../../domain/economy/vendorStock.ts';
+import type { Character } from '../../domain/character/character.ts';
+import type { DataStore } from '../../data/dataStore.ts';
+import type { ItemDef } from '../../data/schema.ts';
+import type { Game, VendorOffer } from './types.ts';
+import type { GameCtx } from './context.ts';
+
+export interface VendorOffersExtras {
+  /** Reputation price multiplier for this vendor (1 = no discount). */
+  vendorPriceMultiplier: (vendorEntry: number) => number;
+  /** Persisted limited-stock tracker for one line, in domain shape. */
+  vendorStockTracker: (vendorEntry: number, itemEntry: number) => VendorItemCountState | undefined;
+  /** Family-aware bag-space check (quiver/pouch vs general bags). */
+  canFitUnits: (itemEntry: number, units: number, stackable: number) => boolean;
+  // npc_vendor.condition_id evaluator (Player.cpp:17545 CONDITION_FROM_VENDOR). Required: the 445 baked
+  // conditional lines are the WSG/AB rep gear, and omitting it sells them ungated.
+  vendorConditionSatisfied: VendorConditionCheck;
+}
+
+// GetReputationPriceDiscount for a creature entry (vendor or trainer). Cite: Player.cpp:18339–18357;
+// NPCHandler.cpp SendTrainerList / HandleTrainerBuySpellOpcode.
+export function vendorPriceMultiplierFor(
+  ds: DataStore,
+  char: Character,
+  creatureEntry: number,
+): number {
+  const facId = creatureRepFactionId(ds, creatureEntry);
+  const fac = facId != null ? ds.faction(facId) : undefined;
+  if (!fac) return 1;
+  const rank = getRank(char.reputations, fac, char.race, char.cls);
+  let visualRank = undefined;
+  if (char.honor?.rp) {
+    visualRank = calculateHonorRank(char.honor.rp).visualRank;
+  }
+  let isFriendly = false;
+  const playerTemplateId = playerFactionTemplateId(ds, char.race);
+  if (playerTemplateId != null && facId != null) {
+    const pTemplate = ds.factionTemplate(playerTemplateId);
+    const vTemplateId = ds.creature(creatureEntry)?.factionId;
+    const vTemplate = vTemplateId != null ? ds.factionTemplate(vTemplateId) : undefined;
+    if (pTemplate && vTemplate) {
+      isFriendly = getFactionReaction(pTemplate, vTemplate) >= REP_RANK.FRIENDLY;
+    }
+  }
+  return reputationPriceDiscount(rank, visualRank, isFriendly);
+}
+
+/** A refusal from the purchase requirement gates, or `ok` when the line may be bought. */
+export type VendorRequirement = { ok: true } | { ok: false; reason: string };
+
+// The vendor condition, evaluated by the caller, which owns the snapshot and the table. Undefined means
+// no evaluator is wired and the line is NOT refused: a missing supplier must not turn real stock off.
+export type VendorConditionCheck = (conditionId: number) => boolean;
+
+// The item's required reputation, with the fallback the item bake cannot carry: an item naming a RANK
+// but no faction is gated on the VENDOR's faction. No rows hit it in 1.12. Cite: Player.cpp:17528.
+function repRequirement(
+  ds: DataStore,
+  char: Character,
+  vendorEntry: number,
+  def: ItemDef,
+): VendorRequirement {
+  const named = def.requiredRep;
+  const wantRank = named?.rank ?? 0;
+  if (wantRank <= 0) return { ok: true };
+  const facId = named && named.faction > 0 ? named.faction : creatureRepFactionId(ds, vendorEntry);
+  const fac = facId != null ? ds.faction(facId) : undefined;
+  // Fail closed: a rank is demanded and we cannot resolve who it is with.
+  if (!fac) return { ok: false, reason: 'Requires higher reputation' };
+  if (getRank(char.reputations, fac, char.race, char.cls) < wantRank) {
+    const rankName = RANK_NAMES[wantRank] ?? 'higher';
+    return { ok: false, reason: `Requires ${rankName} with ${fac.name}` };
+  }
+  return { ok: true };
+}
+
+// The item's required honor rank against the HIGHEST ever held, plus a required level: PvP bonus items
+// are exempt from the normal level gate, so this branch re-checks it. Cite: Player.cpp:17539-17543.
+// PRODUCT RULE: rank is status now, so the gate only holds the rows Honor Points do NOT buy — the
+// nine war mounts at visual 11, the four tabards and the two battle standards.
+function honorRequirement(ds: DataStore, char: Character, def: ItemDef): VendorRequirement {
+  const want = def.requiredHonorRank ?? 0;
+  if (want <= 0 || honorPriceOf(ds, def) > 0) return { ok: true };
+  const faction = factionOf(ds, char.race) === 'horde' ? 'horde' : 'alliance';
+  const title = honorRankRequirementTitle(want, faction);
+  if (highestInternalRank(char.honor) < want) {
+    return { ok: false, reason: `Requires the rank of ${title}` };
+  }
+  if (char.level < def.requiredLevel) {
+    return { ok: false, reason: `Requires level ${def.requiredLevel}` };
+  }
+  return { ok: true };
+}
+
+// Every requirement the vendor purchase checks before it looks at price, in C++ order, so the merchant
+// tile and the buy can never disagree. Stock, bag space, gold and unique ownership stay with callers.
+export function vendorPurchaseRequirement(
+  ds: DataStore,
+  char: Character,
+  vendorEntry: number,
+  def: ItemDef,
+  conditionId: number,
+  conditionSatisfied?: VendorConditionCheck,
+): VendorRequirement {
+  const rep = repRequirement(ds, char, vendorEntry, def);
+  if (!rep.ok) return rep;
+  const honor = honorRequirement(ds, char, def);
+  if (!honor.ok) return honor;
+  if (conditionId > 0 && conditionSatisfied && !conditionSatisfied(conditionId)) {
+    return { ok: false, reason: 'You do not meet the requirements for that' };
+  }
+  return { ok: true };
+}
+
+/** npc_vendor.condition_id for one line, from the baked `itemConditions` list. */
+export function vendorLineConditionId(
+  vendor: { itemConditions?: ReadonlyArray<{ item: number; conditionId: number }> } | undefined,
+  itemEntry: number,
+): number {
+  if (!vendor?.itemConditions?.length) return 0;
+  for (const c of vendor.itemConditions) {
+    if (c.item === itemEntry) return c.conditionId | 0;
+  }
+  return 0;
+}
+
+// C++ floor(spellCost * GetReputationPriceDiscount). Cite: NPCHandler.cpp SendTrainerSpellHelper (list
+// packet) and HandleTrainerBuySpellOpcode (buy).
+export function trainerSpellCost(cost: number, discountMod: number): number {
+  return Math.floor(cost * discountMod);
+}
+
+// The two lookups the buy path and the shelf must agree on. Kept here (not in game.ts) so there is exactly
+// one definition of "what does this cost" and "how much is left".
+export function makeVendorHelpers(ctx: GameCtx): Pick<VendorOffersExtras, 'vendorPriceMultiplier' | 'vendorStockTracker'> {
+  const { ds, state } = ctx;
+  return {
+    // The reputation price discount comes off the creature's FACTION TEMPLATE mapped to a real faction:
+    // looking up the template id directly misses ~651 capital vendors and collides with real ids.
+    vendorPriceMultiplier: (vendorEntry) => vendorPriceMultiplierFor(ds, state.char, vendorEntry),
+    // The save omits `itemId` (it is the map key); rebuild the domain shape once, here.
+    vendorStockTracker: (vendorEntry, itemEntry) => {
+      const row = state.vendorStock?.[vendorEntry]?.[itemEntry];
+      return row ? { itemId: itemEntry, count: row.count, lastIncrementTime: row.lastIncrementTime } : undefined;
+    },
+  };
+}
+
+export function createVendorOffersModule(
+  ctx: GameCtx,
+  extras: VendorOffersExtras,
+): Pick<Game, 'vendorOffers'> {
+  const { ds, state } = ctx;
+  const { vendorPriceMultiplier, vendorStockTracker, canFitUnits, vendorConditionSatisfied } = extras;
+
+  return {
+    vendorOffers(vendorEntry, nowMs = Date.now()) {
+      const vendor = ds.vendor(vendorEntry);
+      if (!vendor) return [];
+      const nowSec = Math.floor(nowMs / 1000);
+      const priceMultiplier = vendorPriceMultiplier(vendorEntry);
+      const offers: VendorOffer[] = [];
+
+      for (const itemEntry of vendor.items) {
+        const def = ds.item(itemEntry);
+        if (!def || def.buyPrice <= 0) continue; // not purchasable (the panel hides these too)
+        const unitsPerPurchase = Math.max(1, def.buyCount ?? 1);
+        // A PvP gear line is paid in Honor Points, so its coin price is not what the tile quotes.
+        const honorPrice = honorPriceOf(ds, def);
+        const pricePerPurchase = honorPrice > 0 ? 0 : buyCostCopper(def, 1, priceMultiplier);
+
+        const row = vendor.stock?.find((s) => s.item === itemEntry);
+        let maxStock: number | null = null;
+        let stockRemaining: number | null = null;
+        let restockInMs: number | null = null;
+        let restockEverySec: number | null = null;
+        let inStock = true;
+        if (row && row.maxcount > 0) {
+          const stockDef: VendorStockDef = {
+            item: itemEntry,
+            maxcount: row.maxcount,
+            incrtime: row.incrtime,
+            buyCount: unitsPerPurchase,
+          };
+          const cur = getVendorItemCurrentCount(stockDef, vendorStockTracker(vendorEntry, itemEntry), nowSec);
+          maxStock = row.maxcount;
+          stockRemaining = cur.available;
+          restockEverySec = row.incrtime > 0 ? row.incrtime : null;
+          inStock = cur.available >= unitsPerPurchase;
+          // Next tick is incrtime after the last one; a full shelf has nothing pending.
+          if (cur.state && row.incrtime > 0 && cur.available < row.maxcount) {
+            restockInMs = Math.max(0, (cur.state.lastIncrementTime + row.incrtime) * 1000 - nowMs);
+          }
+        }
+
+        // The requirement gates the buy path runs, so a tile can never promise a rank-gated
+        // set piece the purchase then refuses. Cite: Player.cpp:17528-17549.
+        const req = vendorPurchaseRequirement(
+          ds,
+          state.char,
+          vendorEntry,
+          def,
+          vendorLineConditionId(vendor, itemEntry),
+          vendorConditionSatisfied,
+        );
+
+        offers.push({
+          itemEntry,
+          unitsPerPurchase,
+          pricePerPurchase,
+          basePricePerPurchase: def.buyPrice,
+          maxStock,
+          stockRemaining,
+          restockInMs,
+          restockEverySec,
+          inStock,
+          fits: canFitUnits(itemEntry, unitsPerPurchase, def.stackable ?? 1),
+          honorPrice,
+          affordable: honorPrice > 0
+            ? (state.char.honor?.honorPoints ?? 0) >= honorPrice
+            : state.char.gold >= pricePerPurchase,
+          meetsRequirements: req.ok,
+          ...(req.ok ? {} : { requirementReason: req.reason }),
+        });
+      }
+      return offers;
+    },
+  };
+}

package/src/engine/game/weaponImbueItem.ts

@@ -0,0 +1,281 @@
+// Applying a temporary weapon imbue item to a hand the player picks, on themselves or a companion.
+// One eligible hand auto-applies, two ask, an ineligible one REFUSES rather than retargeting.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { EquipSlot, SpellDef } from '../../data/schema.ts';
+import type { Character, EquippedMap, TempEnchantHand } from '../../domain/character/character.ts';
+import type { Inventory } from '../../domain/items/inventory.ts';
+import { countItem, removeItem } from '../../domain/items/inventory.ts';
+import { applyTempEnchant } from '../../domain/professions/characterEnchants.ts';
+import { resolveTempWeaponImbueHand } from '../../domain/professions/weaponImbueHand.ts';
+import { equippedEntry } from '../../domain/items/itemInstance.ts';
+import { hasAttrEx2, SPELL_ATTR_EX2 } from '../spells/spellAttributes.ts';
+import type { Companion } from '../../domain/bots/squad.ts';
+import { resolveCombatSpell } from '../spells/interpreter/item-triggers.ts';
+import {
+  applyWeaponImbueKitFromItemEnchant,
+  combatPayloadFromSpell,
+  type WeaponImbueEffect,
+} from '../spells/interpreter/weapon-imbue-kit.ts';
+import type { CombatSession } from '../combat/session-types.ts';
+import type { ConsumeItemOpts, EnchantNeedsTarget, EnchantTarget } from './types.ts';
+import { consumeItemCharges } from '../../domain/items/inventory.ts';
+
+export type WeaponImbueItemResult =
+  | { ok: true; restored: number; enchantedSlot: EquipSlot }
+  | { ok: false; reason: string; needsTarget?: EnchantNeedsTarget };
+
+// The live unit that owns a wearer's weapon while a combat session is open (`player` / `ally_N`), or null
+// when nothing is running. See `mirrorImbueOntoLiveUnit`.
+export type LiveImbueUnit = (
+  target: EnchantTarget,
+) => { session: CombatSession; side: string } | null;
+
+export interface WeaponImbueItemDeps {
+  ds: DataStore;
+  char: Character;
+  inventory: Inventory;
+  squad: Companion[] | undefined;
+  botRoster?: Record<string, Companion>;
+  raidMembers?: Record<string, Companion>;
+  setPlayer(char: Character, inventory: Inventory): void;
+  setCompanion(id: string, charPatch: { equipped: EquippedMap; tempEnchants?: Character['tempEnchants'] }, inventory: Inventory): void;
+  log(msg: string): void;
+  /** Optional wall clock for expiresAt (tests inject). */
+  now?: number;
+  /** Live unit that owns this wearer's weapon while a session is open (mirror target). */
+  liveUnit?: LiveImbueUnit;
+  /** The wearer is spending their OWN item on their OWN weapon (companion self-prep). */
+  byWearer?: boolean;
+}
+
+function ownedCompanion(d: WeaponImbueItemDeps, id: string): Companion | undefined {
+  const c = d.squad?.find((m) => m.id === id) ?? d.botRoster?.[id] ?? d.raidMembers?.[id];
+  return c && !c.mission ? c : undefined;
+}
+
+// Land the same coat on the LIVE unit, not just the sheet: a dungeon's one session read the temp
+// enchant when it was built, so a poison applied on the floor procced nothing for the rest of the run.
+function mirrorImbueOntoLiveUnit(
+  live: { session: CombatSession; side: string },
+  hand: TempEnchantHand,
+  spell: SpellDef,
+  eff: WeaponImbueEffect,
+  ds: DataStore,
+  casterLevel: number,
+): void {
+  if (typeof live.session.applySpellToUnit !== 'function') return;
+  live.session.applySpellToUnit(live.side, spell, { weaponImbueHand: hand });
+  const equipSpellId = eff.equipSpellId ?? 0;
+  if (equipSpellId <= 0 || eff.attackPower) return;
+  const equip = ds.spell(equipSpellId);
+  if (equip) live.session.applySpellToUnit(live.side, resolveCombatSpell(equip, { casterLevel }));
+}
+
+// Route a temporary imbue item, or return null when `itemEntry` is not one (permanent enchants go through
+// enchantItem.ts; ordinary consumables fall through).
+export function routeWeaponImbueItem(
+  itemEntry: number,
+  opts: ConsumeItemOpts,
+  d: WeaponImbueItemDeps,
+): WeaponImbueItemResult | null {
+  const { ds } = d;
+  const item = ds.item(itemEntry);
+  if (!item?.useSpell) return null;
+  const app = ds.enchantApplicator(item.useSpell);
+  if (!app || app.permanent) return null; // not a temp imbue
+
+  if (countItem(d.inventory, itemEntry) <= 0) return { ok: false, reason: "You don't have that" };
+
+  const target: EnchantTarget = opts.target ?? { kind: 'self' };
+
+  // ENCHANT_OWN_ITEM_ONLY refuses the enchant only when the WEARER is not the caster
+  // (Spell.cpp:6694-6698 `item->GetOwner() != m_caster`). A companion coating their own weapon out
+  // of their own bags is the wearer casting, so poisons (ownItemOnly) reach a companion rogue.
+  if (target.kind === 'companion' && !d.byWearer) {
+    const spell = ds.spell(item.useSpell);
+    if (hasAttrEx2(spell, SPELL_ATTR_EX2.ENCHANT_OWN_ITEM_ONLY)) {
+      return { ok: false, reason: 'You can only enchant your own items with that' };
+    }
+  }
+
+  let equipped: EquippedMap;
+  let wearerName: string;
+  let companion: Companion | undefined;
+  let baseChar: Character;
+  if (target.kind === 'companion') {
+    companion = ownedCompanion(d, target.id);
+    if (!companion) return { ok: false, reason: 'That companion is not with you' };
+    equipped = companion.equipped;
+    wearerName = companion.name;
+    // Companion.tempEnchants is the typed TEMP_ENCHANTMENT_SLOT map (W5 gap 1).
+    baseChar = {
+      ...d.char,
+      equipped: companion.equipped,
+      tempEnchants: companion.tempEnchants,
+    };
+  } else {
+    equipped = d.char.equipped;
+    wearerName = 'your';
+    baseChar = d.char;
+  }
+
+  // Shared eligibility (weapon hands only — never shield) + ask when both eligible.
+  // Cite: domain/professions/weaponImbueHand.ts; W5 dual-wield poison OH.
+  const picked = resolveTempWeaponImbueHand({
+    equipped,
+    ds,
+    app,
+    requested: opts.slot,
+    mode: 'ask-when-ambiguous',
+  });
+  if (!picked.ok) {
+    if (picked.needsChoose) {
+      return {
+        ok: false,
+        reason: 'Choose a slot',
+        needsTarget: {
+          itemEntry,
+          enchantId: app.enchantId,
+          target,
+          slots: picked.needsChoose.slots,
+          rejected: picked.needsChoose.rejected,
+        },
+      };
+    }
+    const who = target.kind === 'companion' ? `${wearerName} has` : 'you are wearing';
+    return {
+      ok: false,
+      reason: picked.reason.replace('you are wearing', who).replace('Nothing you are wearing', `Nothing ${who}`),
+    };
+  }
+  const slot = picked.hand;
+  const wornEntry = equippedEntry(equipped[slot]);
+  const worn = wornEntry != null ? ds.item(wornEntry) : undefined;
+  if (!worn) return { ok: false, reason: 'Unknown item' };
+
+  // Resolve the full weapon_imbue payload (itemEnchant kit + combat spell numbers).
+  const spRaw = ds.spell(item.useSpell);
+  const sp = spRaw
+    ? resolveCombatSpell(spRaw, {
+        spellLookup: (id) => ds.spell(id),
+        // itemEnchantLookup is read via cast in resolveCombatSpell; pass via object bag.
+        ...({ itemEnchantLookup: (id: number) => ds.itemEnchant(id) } as object),
+      } as Parameters<typeof resolveCombatSpell>[1])
+    : undefined;
+  const eff = sp?.effects?.find((e) => e.kind === 'weapon_imbue');
+  if (!sp || !eff || eff.kind !== 'weapon_imbue') {
+    return { ok: false, reason: 'That does not coat a weapon' };
+  }
+  // Ensure combat.direct is filled even when resolve lacked spellLookup wiring.
+  applyWeaponImbueKitFromItemEnchant(eff, ds.itemEnchant(eff.enchantId), (id) => ds.spell(id));
+  if (!eff.combat && eff.combatSpellId) {
+    const proc = ds.spell(eff.combatSpellId);
+    if (proc) {
+      const combat = combatPayloadFromSpell(resolveCombatSpell(proc));
+      if (combat) eff.combat = combat;
+    }
+  }
+
+  // Consume one use (multi-charge oils decrement; −1 / absent destroy one stack unit).
+  const taken = consumeItemCharges(d.inventory, itemEntry, item);
+  if (!taken.ok) return { ok: false, reason: taken.reason };
+
+  const now = d.now ?? Date.now();
+  const durationMs = eff.durationMs > 0
+    ? eff.durationMs
+    : (app.durationMs && app.durationMs > 0 ? app.durationMs : 1_800_000);
+  const hand = slot;
+  const nextChar = applyTempEnchant(baseChar, hand, {
+    spellId: item.useSpell,
+    enchantId: eff.enchantId,
+    expiresAt: now + durationMs,
+    family: eff.family,
+    attackPower: eff.attackPower,
+    // The equip-spell passive (oil mana per five, Rockbiter's attack power), applied as an aura for the
+    // temp duration. Cite: Player.cpp ApplyEnchantment ITEM_ENCHANTMENT_TYPE_EQUIP_SPELL.
+    equipSpellId: eff.equipSpellId,
+    combatSpellId: eff.combatSpellId,
+    combatChancePct: eff.combatChancePct,
+    combatPpm: eff.combatPpm,
+    damageFlat: eff.damageFlat,
+    rockbiterAmount: eff.rockbiterAmount,
+    combat: eff.combat,
+  }, now, ds);
+
+  if (companion) {
+    d.setCompanion(
+      companion.id,
+      { equipped: nextChar.equipped, tempEnchants: nextChar.tempEnchants },
+      taken.inventory,
+    );
+  } else {
+    d.setPlayer(nextChar, taken.inventory);
+  }
+
+  const live = d.liveUnit?.(target);
+  if (live) mirrorImbueOntoLiveUnit(live, hand, sp, eff, ds, d.char.level);
+
+  d.log(target.kind === 'companion'
+    ? `You apply ${item.name} to ${wearerName}'s ${worn.name}.`
+    : `You apply ${item.name} to your ${worn.name}.`);
+
+  return { ok: true, restored: 0, enchantedSlot: slot };
+}
+
+/** Bind the router to a live game state. Keeps wiring out of game.ts (filesize ratchet). */
+export function makeWeaponImbueItemRouter(g: {
+  ds: DataStore;
+  state: {
+    char: Character;
+    inventory: Inventory;
+    squad?: Companion[];
+    botRoster?: Record<string, Companion>;
+    raidRoster?: { members?: Record<string, Companion> };
+  };
+  log(msg: string): void;
+  liveUnit?: LiveImbueUnit;
+}): (itemEntry: number, opts: ConsumeItemOpts) => WeaponImbueItemResult | null {
+  type ImbuePatch = { equipped: EquippedMap; tempEnchants?: Character['tempEnchants'] };
+  const writeCompanion = (id: string, patch: ImbuePatch): void => {
+    const next = (prev: Companion): Companion => ({
+      ...prev,
+      equipped: patch.equipped,
+      tempEnchants: patch.tempEnchants,
+    });
+    const idx = (g.state.squad ?? []).findIndex((c) => c.id === id);
+    if (idx >= 0) {
+      g.state.squad![idx] = next(g.state.squad![idx]!);
+      return;
+    }
+    if (g.state.botRoster?.[id]) {
+      g.state.botRoster[id] = next(g.state.botRoster[id]!);
+      return;
+    }
+    const raid = g.state.raidRoster?.members;
+    if (raid?.[id]) raid[id] = next(raid[id]!);
+  };
+  return (itemEntry, opts) => routeWeaponImbueItem(itemEntry, opts, {
+    ds: g.ds,
+    char: g.state.char,
+    inventory: g.state.inventory,
+    squad: g.state.squad,
+    botRoster: g.state.botRoster,
+    raidMembers: g.state.raidRoster?.members,
+    ...(g.liveUnit ? { liveUnit: g.liveUnit } : {}),
+    setPlayer: (char, inventory) => {
+      g.state.char = char;
+      g.state.inventory = inventory;
+    },
+    setCompanion: (id, patch, inventory) => {
+      writeCompanion(id, patch);
+      g.state.inventory = inventory;
+    },
+    log: g.log,
+  });
+}
+
+/** @deprecated — prefer consumeItemCharges; kept for call sites that only removeItem. */
+function takeOneImbueItem(inv: Inventory, itemEntry: number): [Inventory, number] {
+  return removeItem(inv, itemEntry, 1);
+}