Add UPDATE_INVENTORY_DURABILITY (TODO #89)

Fires (no payload) when any equipped item's durability changes -
combat damage, death, repairs - via a co-hook on the engine's
inventory-alerts recompute (FUN_004C7EE0, the routine behind vanilla's
UPDATE_INVENTORY_ALERTS). The engine calls it whenever an owned item's
fields change (the item post-update handler FUN_005D9A90 routes every
item values-update through it) plus equip/enter-world paths, so it is
the engine's own durability-may-have-changed signal. Post-original we
diff a per-slot {itemGuid, durability} snapshot and fire once per
recompute with a real change - a death dinging all armor produces one
event, not nineteen.

The snapshot seeds silently on the first recompute of the process and
is deliberately NOT re-seeded per enter-world: death/release/graveyard
teleports re-run the setup, and a per-setup reset swallowed the
death's own durability loss (verified in-game; repairs fired, deaths
didn't until this was fixed).

Dead end, kept documented at OFF_DESC_ITEM_DURABILITY: bank-1 (ITEM
field) descriptor observers register without error but are never
invoked - item values-updates demonstrably arrive and player-bank
observers fire in the same session; registration arithmetic fully
verified (bank base FUN_00465690(1)=0x18, bank walk item 0->1->2).
Prime suspect is the registrar's internal wrapper lookup
(FUN_00464890, the observer registry, distinct from the object
manager) silently no-op'ing for item objects.

Also in Player::Equipment: resolve the player via the non-throwing
GUID resolver (FUN_00468460, what the engine's own bag observer uses)
instead of FUN_RESOLVE_UNIT_TOKEN, which raises a Lua error when the
token doesn't resolve - unsafe inside SMSG_UPDATE_OBJECT processing
where the player can be mid-create.

Author: brues-code

README.md

@@ -134,6 +134,7 @@ when launching with `-console`), not as Lua functions. See the
 | `QUEST_DATA_LOAD_RESULT` | `questID, success` |
 | `QUEST_REMOVED` | `questID` |
 | `QUEST_TURNED_IN` | `questID, xpReward, moneyReward` |
+| `UPDATE_INVENTORY_DURABILITY` | *(none)* |
 | `UPDATE_SHAPESHIFT_FORM` | *(none)* |
 | `VOICE_CHAT_TTS_PLAYBACK_STARTED` | `numConsumers, utteranceID, durationMS, destination` |
 | `VOICE_CHAT_TTS_PLAYBACK_FINISHED` | `numConsumers, utteranceID, destination` |

TODO.md

@@ -2847,7 +2847,33 @@ Same diff feeds `EQUIPMENT_SETS_CHANGED` /
 module — currently those fire only on user-side mutations, not
 on inventory changes that affect a set's "equipped count".
 
-## 89. `UPDATE_INVENTORY_DURABILITY` event
+## ~~89. `UPDATE_INVENTORY_DURABILITY` event~~ — DONE
+
+**Resolution (2026-07-04, src/player/Equipment.cpp):** co-hook the
+engine's inventory-alerts recompute `FUN_004C7EE0` — the routine that
+walks equipment slots, reads each item's durability/broken state from
+the descriptor, and unconditionally fires vanilla's
+`UPDATE_INVENTORY_ALERTS` (event 501). The engine calls it whenever an
+owned item's fields change (the item post-update handler `FUN_005D9A90`
+routes every item values-update through it, alongside
+UNIT_INVENTORY_CHANGED and the bag-update chain) plus equip and
+enter-world paths — i.e., it IS the engine's own "durability may have
+changed" signal. Post-original we diff a per-slot {guid, durability}
+snapshot (seeded silently on the first recompute per enter-world) and
+fire once per recompute with a real change. No polling, no hot hook.
+
+**Dead end tried first:** bank-1 (ITEM field) descriptor observers per
+equipped item, via the TODO #88 observer system. They register without
+error but are NEVER invoked — item values-updates demonstrably arrive
+(probed the values pre-pass `FUN_00465330`) and player-bank observers
+fire in the same session; registration arithmetic fully verified (bank
+base `FUN_00465690(1)=0x18`, bank walk item 0→1→2, anchors match
+dispatch). Prime suspect: the registrar's internal wrapper lookup
+(`FUN_00464890`, the observer registry — NOT the object manager)
+silently no-ops for item objects. See the DEAD END note at
+`OFF_DESC_ITEM_DURABILITY` in Offsets.h.
+
+Original notes below kept for the investigation trail.
 
 Fires when any equipped item's durability changes — picks up
 combat damage, repairs, item destruction. Used by Repair-O-Matic

docs/API.md

@@ -91,6 +91,7 @@ build instructions.
   - [`C_EventUtils.IsEventValid(eventName)`](#c_eventutilsiseventvalideventname)
   - [`BAG_UPDATE_DELAYED` event](#bag_update_delayed-event)
   - [`PLAYER_EQUIPMENT_CHANGED` event](#player_equipment_changed-event)
+  - [`UPDATE_INVENTORY_DURABILITY` event](#update_inventory_durability-event)
   - [`HEARTHSTONE_BOUND` event](#hearthstone_bound-event)
   - [Player input-state events (`PLAYER_STARTED_MOVING` / `LOOKING` / `TURNING` + `STOPPED_*`)](#player-input-state-events)
   - [`GLOBAL_MOUSE_DOWN` / `GLOBAL_MOUSE_UP` events](#global_mouse_down--global_mouse_up-events)
@@ -2042,6 +2043,31 @@ server's update packet writes a new item GUID into a slot, once per
 changed slot. Swapping two items (e.g. weapon ⇄ bag) fires once per
 affected equipment slot.
 
+### `UPDATE_INVENTORY_DURABILITY` event
+
+Backport of the modern event that fires — with no payload — when an
+equipped item's durability changes: combat damage, resurrection
+penalty, repairs. The standard consumer pattern works unchanged:
+rescan the 19 slots with `GetInventoryItemDurability` on each fire.
+
+```lua
+local f = CreateFrame("Frame")
+f:RegisterEvent("UPDATE_INVENTORY_DURABILITY")
+f:SetScript("OnEvent", RefreshMyDurabilityHUD)
+```
+
+Event-driven, no polling: piggybacks on the engine's own
+inventory-alerts recompute — the routine behind vanilla's
+`UPDATE_INVENTORY_ALERTS` (the red/yellow "broken armor man"), which
+the engine runs whenever an owned item's fields change, on equip
+changes, and at enter-world. On each recompute the DLL diffs a
+per-slot `{item, durability}` snapshot and fires once when anything
+actually changed — a death dinging all your armor produces one event,
+not nineteen. Also fires when the *set* of equipped items changes
+(swapping to a differently-damaged item updates durability UI, so
+consumers want the refresh anyway). Bag-carried items don't trigger
+it: vanilla renders durability UI for equipped gear only.
+
 ### `HEARTHSTONE_BOUND` event
 
 Fires (with no payload) every time the player binds their

src/Offsets.h

@@ -560,12 +560,23 @@ enum Offsets {
     //
     // Registrar — __fastcall(int bank /*ecx*/, uint32_t fieldOffset /*edx*/,
     //   uint32_t guidLo, uint32_t guidHi, int size, const void *callback,
-    //   void *userArg1, void *userArg2). `bank` 4 = player fields;
-    //   `fieldOffset` is the descriptor byte offset (e.g. 0x560 backpack
-    //   slot 0). The engine's inventory setup FUN_004F8CC0 registers bags/
-    //   backpack/bank/keyring GUID ranges this way — but NOT equipment.
+    //   void *userArg1, void *userArg2). `guid` selects the watched OBJECT
+    //   (player, item, container, …); `bank` selects its field bank
+    //   (1 = ITEM, 2 = CONTAINER, 4 = PLAYER — the engine's per-bag
+    //   manager FUN_004F91A0 registers bank-2 observers on each equipped
+    //   bag's CGContainer); `fieldOffset` is BANK-relative (container
+    //   SLOT_1 = 8, not its descriptor-absolute 0x20). The engine's
+    //   inventory setup FUN_004F8CC0 registers the player's bag/backpack/
+    //   bank/keyring GUID ranges this way — but NOT equipment.
     FUN_DESC_OBSERVER_REGISTER = 0x00467E70,
 
+    // Unregister — __fastcall(int bank /*ecx*/, uint32_t fieldOffset
+    //   /*edx*/, uint32_t guidLo, uint32_t guidHi, const void *callback,
+    //   void *userArg1). Removes the node matching (callback, userArg1)
+    //   from that object+field's observer list; harmless no-op when
+    //   nothing matches. What FUN_004F91A0 calls for an unequipped bag.
+    FUN_DESC_OBSERVER_UNREGISTER = 0x00467FB0,
+
     // Observer callback ABI (verified from the dispatcher's call site at
     // 0x004655DC + the engine callback FUN_004F8DB0's RET 0x10):
     //   int __fastcall cb(uint32_t fieldOffset /*ecx, as registered*/,
@@ -591,6 +602,39 @@ enum Offsets {
     OFF_DESC_PLAYER_EQUIP_FIRST = 0x4A8,
     DESC_PLAYER_EQUIP_SLOTS = 19,
     DESC_OBSERVER_BANK_PLAYER = 4,
+
+    // ITEM_FIELD_DURABILITY, ITEM-bank-relative: descriptor-absolute
+    // +0xA0 (field index 0x28, which counts the 6 OBJECT fields) minus
+    // the 0x18-byte OBJECT prefix. u32.
+    //
+    // DEAD END — bank-1 (ITEM field) observers register without error but
+    // are NEVER invoked: item values-updates demonstrably arrive
+    // (verified by probing the values pre-pass FUN_00465330) and
+    // player-bank observers fire in the same session, yet item-bank
+    // callbacks stay silent. Registration arithmetic was fully verified
+    // (bank base FUN_00465690(1)=0x18, next-bank walk FUN_004656E0
+    // item: 0→1→2, anchors match dispatch), so the suspect is the
+    // registrar's internal wrapper lookup (FUN_00464890 — the observer
+    // registry, NOT the object manager) silently no-op'ing for item
+    // objects. UPDATE_INVENTORY_DURABILITY is instead backed by
+    // FUN_INVENTORY_ALERTS_RECOMPUTE below. Constants kept for the
+    // investigation trail.
+    DESC_OBSERVER_BANK_ITEM = 1,
+    OFF_DESC_ITEM_DURABILITY = 0x88,
+
+    // The engine's inventory-alerts recompute — walks the equipment
+    // slots, reads each item's ITEM_FIELD_DURABILITY / MAXDURABILITY /
+    // broken flag from the descriptor, fills the per-slot alert table at
+    // [DAT_00B71F60], and UNCONDITIONALLY fires UPDATE_INVENTORY_ALERTS
+    // (event 501) at the end. The engine calls it whenever an owned
+    // item's fields change (the item post-update handler FUN_005D9A90 —
+    // which also fires UNIT_INVENTORY_CHANGED and the bag-update chain —
+    // routes every item values-update through it) plus equip and
+    // enter-world paths. That makes it the engine's own "durability may
+    // have changed" signal: Player::Equipment co-hooks it and diffs a
+    // {guid, durability} snapshot per slot to back
+    // UPDATE_INVENTORY_DURABILITY. void __fastcall(), no args.
+    FUN_INVENTORY_ALERTS_RECOMPUTE = 0x004C7EE0,
     // ItemMgr::GetItemBySlot — __thiscall(this, slot) → CGItem* (NULL if empty).
     // Slot is the engine's linearized slot index, not bagID/slot tuple.
     FUN_ITEMMGR_GET_ITEM_BY_SLOT = 0x006228A0,
@@ -1153,6 +1197,7 @@ enum Offsets {
     OBJ_TYPE_ITEM = 2,
     OBJ_TYPE_CONTAINER = 4,
     OBJ_TYPE_UNIT = 8,
+    OBJ_TYPE_PLAYER = 0x10, // what the engine's bag observer FUN_004F8DB0 passes
     OBJ_TYPE_GAMEOBJECT = 0x20, // 1<<5; passed by FUN_0052AA20 (hover-tooltip populator).
 
     // `CGObject::GetName` — returns the display-name `const char *` for

src/player/Equipment.cpp

@@ -32,9 +32,25 @@
 // tabard), matching modern. `hasCurrent` is 1 when the slot now holds an
 // item and nil when it's empty (the engine dispatcher has no `%b`; 1/nil
 // keeps the idiomatic `if hasCurrent then` working — see FireIdSuccess).
+//
+// Also `UPDATE_INVENTORY_DURABILITY` (no payload) — fires when any
+// equipped item's durability changes (combat damage, death, repairs) —
+// via a co-hook on the engine's inventory-alerts recompute
+// (FUN_INVENTORY_ALERTS_RECOMPUTE): the engine itself calls that whenever
+// an owned item's fields change (its item post-update handler FUN_005D9A90
+// routes every item values-update through it) and on equip/enter-world
+// paths, so it IS the engine's own "durability may have changed" signal.
+// Post-original we diff a per-slot {itemGuid, durability} snapshot and
+// fire only on a real change. NOT done with bank-1 (ITEM field) descriptor
+// observers: those register without error but are never invoked — the
+// registrar's internal wrapper lookup (FUN_00464890, the observer
+// registry, distinct from the object manager) silently no-ops for item
+// objects, verified empirically (item values-updates arrive and the
+// player-bank observers fire, item-bank ones never do).
 
 #include "Game.h"
 #include "Offsets.h"
+#include "equipmentset/Locations.h"
 #include "event/Custom.h"
 #include "unit/Identity.h"
 
@@ -46,17 +62,28 @@ namespace {
 
 constexpr const char *kEvtEquipmentChanged = "PLAYER_EQUIPMENT_CHANGED";
 const Event::Custom::AutoReserve _r{kEvtEquipmentChanged};
-
-using ResolveUnitToken_t = void *(__fastcall *)(const char *token);
+constexpr const char *kEvtDurability = "UPDATE_INVENTORY_DURABILITY";
+const Event::Custom::AutoReserve _r2{kEvtDurability};
 
 // Whether the slot currently holds an item — read from the player's
 // inventory-manager GUID array, the same source the engine's own bag
 // observer (FUN_004F8DB0) treats as the post-change truth when its field
-// observer fires.
-bool SlotHasItem(int slot0Based) {
+// observer fires. The player is resolved from the GUID the observer
+// callback receives, via the NON-THROWING object resolver — the same call
+// FUN_004F8DB0 makes. NOT via FUN_RESOLVE_UNIT_TOKEN("player"): that's the
+// assert-frame helper that raises a Lua error when the token doesn't
+// resolve, and this runs inside SMSG_UPDATE_OBJECT processing, where the
+// player object can be mid-create and momentarily unresolvable — a Lua
+// error thrown from there unwinds through raw engine code.
+bool SlotHasItem(uint32_t guidLo, uint32_t guidHi, int slot0Based) {
+    using ResolveByGUID_t = void *(__fastcall *)(uint32_t typeMask,
+                                                 const char *debugName,
+                                                 uint32_t guidLo, uint32_t guidHi,
+                                                 int line);
     auto resolve =
-        reinterpret_cast<ResolveUnitToken_t>(Offsets::FUN_RESOLVE_UNIT_TOKEN);
-    auto *player = static_cast<const uint8_t *>(resolve("player"));
+        reinterpret_cast<ResolveByGUID_t>(Offsets::FUN_OBJECT_RESOLVE_BY_GUID);
+    auto *player = static_cast<const uint8_t *>(resolve(
+        Offsets::OBJ_TYPE_PLAYER, "ClassicAPI", guidLo, guidHi, 0x172));
     if (player == nullptr)
         return false;
     const uint8_t *invMgr = player + Offsets::OFF_PLAYER_INVENTORY_MANAGER;
@@ -69,35 +96,50 @@ bool SlotHasItem(int slot0Based) {
     return guids != nullptr && guids[slot0Based] != 0;
 }
 
+// --- PLAYER_EQUIPMENT_CHANGED (player-descriptor observers) -------------
+
 // Descriptor-field observer callback — ABI per the Offsets.h note:
 // __fastcall(fieldOffset /*ecx*/, size /*edx*/, guidLo, guidHi, oldValue*,
 // userArg), return 1, callee cleans 0x10. Invoked by the dispatcher only
 // when the watched equipment GUID field actually changed.
 int __fastcall EquipSlotChanged_cb(uint32_t fieldOffset, uint32_t /*size*/,
-                                   uint32_t /*guidLo*/, uint32_t /*guidHi*/,
+                                   uint32_t guidLo, uint32_t guidHi,
                                    const uint32_t * /*oldValue*/,
                                    void * /*userArg*/) {
     const int slot0 =
         static_cast<int>(fieldOffset - Offsets::OFF_DESC_PLAYER_EQUIP_FIRST) >> 3;
     if (slot0 >= 0 && slot0 < Offsets::DESC_PLAYER_EQUIP_SLOTS) {
         Event::Custom::FireIdSuccess(Event::Custom::Lookup(kEvtEquipmentChanged),
-                                     slot0 + 1, SlotHasItem(slot0));
+                                     slot0 + 1,
+                                     SlotHasItem(guidLo, guidHi, slot0));
     }
     return 1;
 }
 
 // Co-hook on the engine's inventory observer setup: after it registers the
 // bag-range observers, register ours for the equipment range it skips.
 // Same registrar, same shape — only the field offsets differ.
-using ObserverSetup_t = void(__fastcall *)();
-ObserverSetup_t g_origSetup = nullptr;
-
 using RegisterObserver_t = void(__fastcall *)(
     int bank, uint32_t fieldOffset, uint32_t guidLo, uint32_t guidHi, int size,
     const void *callback, void *userArg1, void *userArg2);
+using ObserverSetup_t = void(__fastcall *)();
+ObserverSetup_t g_origSetup = nullptr;
+
+// One-time (per process) seed latch for the durability diff below — the
+// very first recompute seeds the snapshot silently instead of firing for
+// the initial gear population. Deliberately NOT reset per enter-world:
+// death/release/graveyard teleports re-run the setup, and a per-setup
+// reset made the post-teleport recompute re-seed silently — swallowing
+// the death's own durability loss (verified in-game: repairs fired,
+// deaths didn't). Keeping the snapshot across loading screens means
+// changes that land around them diff normally; the cost is at most one
+// spurious fire on relog to a different character, which matches
+// modern's login-time fire anyway.
+bool g_durSnapValid = false;
 
 void __fastcall ObserverSetup_h() {
     g_origSetup();
+
     const uint64_t guid = Unit::Identity::PlayerGuid();
     if (guid == 0)
         return;
@@ -117,6 +159,60 @@ static const Game::HookAutoRegister _setupHook{
     reinterpret_cast<void *>(&ObserverSetup_h),
     reinterpret_cast<void **>(&g_origSetup)};
 
+// --- UPDATE_INVENTORY_DURABILITY (alerts-recompute co-hook) --------------
+
+struct SlotDurability {
+    uint64_t guid;       // equipped item, 0 = empty slot
+    uint32_t durability; // ITEM_FIELD_DURABILITY, 0 when empty/unresolved
+};
+SlotDurability g_durSnap[EquipmentSet::SLOT_COUNT];
+
+uint32_t ItemDurability(uint64_t guid) {
+    if (guid == 0)
+        return 0;
+    const uint8_t *item = EquipmentSet::Locations::ResolveItemByGUID(guid);
+    if (item == nullptr)
+        return 0;
+    const uint8_t *descriptor = *reinterpret_cast<const uint8_t *const *>(
+        item + Offsets::OFF_ITEM_DESCRIPTOR);
+    if (descriptor == nullptr)
+        return 0;
+    return *reinterpret_cast<const uint32_t *>(
+        descriptor + Offsets::OFF_DESCRIPTOR_DURABILITY);
+}
+
+using AlertsRecompute_t = void(__fastcall *)();
+AlertsRecompute_t g_origAlertsRecompute = nullptr;
+
+void __fastcall AlertsRecompute_h() {
+    g_origAlertsRecompute();
+
+    uint64_t paperdoll[EquipmentSet::SLOT_COUNT];
+    EquipmentSet::Locations::SnapshotPaperdoll(paperdoll);
+
+    bool changed = false;
+    for (int i = 0; i < EquipmentSet::SLOT_COUNT; ++i) {
+        const SlotDurability cur{paperdoll[i], ItemDurability(paperdoll[i])};
+        if (g_durSnap[i].guid != cur.guid ||
+            g_durSnap[i].durability != cur.durability) {
+            changed = true;
+            g_durSnap[i] = cur;
+        }
+    }
+
+    if (!g_durSnapValid) {
+        g_durSnapValid = true; // first recompute of the session seeds only
+        return;
+    }
+    if (changed)
+        Event::Custom::Fire(Event::Custom::Lookup(kEvtDurability), "");
+}
+
+static const Game::HookAutoRegister _alertsHook{
+    Offsets::FUN_INVENTORY_ALERTS_RECOMPUTE,
+    reinterpret_cast<void *>(&AlertsRecompute_h),
+    reinterpret_cast<void **>(&g_origAlertsRecompute)};
+
 } // namespace
 
 } // namespace Player::Equipment