Add PLAYER_EQUIPMENT_CHANGED(equipmentSlot, hasCurrent) (TODO #88)

The earlier investigation tried to hook a firer of
UNIT_INVENTORY_CHANGED; none of the three known 0xBA fire sites
trigger on equip because equipment descriptor writes are silent — the
engine registers descriptor-field observers (the __AUCMirrorHandler__
system: registrar 0x00467E70, dispatcher 0x00465570 with per-node
mirror + memcmp change detection) for the bag/backpack/bank/keyring
GUID ranges but never for equipment 0x4A8..0x538.

So register our own: co-hook the engine's inventory observer setup
(FUN_004F8CC0, once per enter-world) and, post-original, register one
observer per equipment GUID field through the engine's registrar —
same bank/size/GUID shape as the engine's bag observers, engine-
managed lifetime, no polling, no hot-function hook. The dispatcher
invokes us only on a real change.

Callback ABI verified from the dispatcher call site at 0x004655DC and
the engine callback FUN_004F8DB0's RET 0x10:
  __fastcall(fieldOffset /*ecx*/, size /*edx*/, guidLo, guidHi,
             oldValue*, userArg) -> ret 0x10

equipmentSlot is the 1-based Lua inventory slot (1 head .. 19 tabard);
hasCurrent (1/nil) is read from the player invMgr GUID array — the
same post-change truth the engine's bag observer reads.

Author: brues-code

README.md

@@ -122,6 +122,7 @@ when launching with `-console`), not as Lua functions. See the
 | `NAME_PLATE_CREATED` | `nameplateFrame` |
 | `NAME_PLATE_UNIT_ADDED` | `unitToken` ("nameplateN") |
 | `NAME_PLATE_UNIT_REMOVED` | `unitToken` ("nameplateN") |
+| `PLAYER_EQUIPMENT_CHANGED` | `equipmentSlot, hasCurrent` |
 | `PLAYER_FOCUS_CHANGED` | *(none)* |
 | `PLAYER_STARTED_LOOKING` | *(none)* |
 | `PLAYER_STOPPED_LOOKING` | *(none)* |

TODO.md

@@ -2725,7 +2725,26 @@ matching modern's 3-tuple. `CastSpellNoToggle("<name>")` macros are
 also recognized because `Spell::CastNoToggle` already hooks the same
 parser to register that pattern.
 
-## 88. `PLAYER_EQUIPMENT_CHANGED(equipmentSlot, hasCurrent)` event
+## ~~88. `PLAYER_EQUIPMENT_CHANGED(equipmentSlot, hasCurrent)` event~~ — DONE
+
+**Resolution (2026-07-04, src/player/Equipment.cpp):** the 2026-05-22
+investigation kept trying to hook a FIRER of UNIT_INVENTORY_CHANGED.
+The winning move was the opposite: the engine has a generic
+descriptor-field observer system (the "__AUCMirrorHandler__" nodes —
+registrar `FUN_00467E70`, dispatcher `FUN_00465570` with per-node
+mirror + memcmp change detection). `FUN_004F8CC0` registers observers
+for the bag/backpack/bank/keyring GUID ranges but never for equipment
+`0x4A8..0x538` — so we co-hook it and REGISTER OUR OWN observer per
+equipment field, mirroring the engine's registration exactly (bank 4,
+size 8, player GUID). Callback ABI verified from the dispatcher call
+site at `0x004655DC` + `FUN_004F8DB0`'s `RET 0x10`:
+`__fastcall(fieldOffset /*ecx*/, size /*edx*/, guidLo, guidHi,
+oldValue*, userArg)`. hasCurrent read from the invMgr GUID array (the
+same "current truth" the engine's bag callback reads). No polling, no
+hot hook, engine-managed lifetime (setup re-runs each enter-world).
+Offsets documented at `FUN_DESC_OBSERVER_REGISTER` in Offsets.h.
+
+Original notes below kept for the investigation trail.
 
 WotLK-era event that fires every time a paperdoll slot changes
 (equip, unequip, swap). Heavily used by gear-tracking,

docs/API.md

@@ -90,6 +90,7 @@ build instructions.
 - [Events](#events)
   - [`C_EventUtils.IsEventValid(eventName)`](#c_eventutilsiseventvalideventname)
   - [`BAG_UPDATE_DELAYED` event](#bag_update_delayed-event)
+  - [`PLAYER_EQUIPMENT_CHANGED` event](#player_equipment_changed-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)
@@ -2003,6 +2004,43 @@ event handlers.
 > currently won't trigger `BAG_UPDATE_DELAYED`. Player bag (0..4)
 > and bank (5..10) updates work normally — the 95% case.
 
+### `PLAYER_EQUIPMENT_CHANGED` event
+
+Backport of the WotLK-era event that fires once per paperdoll slot
+change — equip, unequip, or swap:
+
+```
+PLAYER_EQUIPMENT_CHANGED: equipmentSlot, hasCurrent
+```
+
+- **`equipmentSlot`** (number) — the 1-based inventory slot that
+  changed (`1` = head … `19` = tabard; same numbering as
+  `GetInventoryItemLink("player", slot)`).
+- **`hasCurrent`** — `1` when the slot now holds an item, `nil` when
+  it's now empty (write `if hasCurrent then` as in modern code —
+  vanilla's event dispatcher can't push real booleans).
+
+Vanilla only fires `UNIT_INVENTORY_CHANGED("player")`, which doesn't
+say *which* slot changed; this event lets gear trackers, stat sheets,
+and tooltip decorators refresh exactly one slot instead of rescanning
+all 19.
+
+```lua
+local f = CreateFrame("Frame")
+f:RegisterEvent("PLAYER_EQUIPMENT_CHANGED")
+f:SetScript("OnEvent", function()
+    print("slot", arg1, arg2 and "equipped" or "now empty")
+end)
+```
+
+Fully event-driven — no polling. The DLL registers change observers
+for the 19 equipment GUID fields of the player descriptor through the
+engine's own field-observer system (the same mechanism the engine
+uses to watch bag slots), so the event fires exactly when the
+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.
+
 ### `HEARTHSTONE_BOUND` event
 
 Fires (with no payload) every time the player binds their

src/Offsets.h

@@ -542,7 +542,55 @@ enum Offsets {
     // addon's CHAT_MSG_* OnEvent.
     FUN_CHAT_DISPATCH = 0x0049A870,
     // Per-player inventory manager lives at this offset on the player object.
+    // +0x00 = u32 slot count (OFF_INVMGR_SLOT_COUNT), +0x04 = u64* GUID
+    // array (see OFF_INVMGR_GUID_ARRAY below for the slot-range map).
     OFF_PLAYER_INVENTORY_MANAGER = 0x1D38,
+    OFF_INVMGR_SLOT_COUNT = 0x00,
+
+    // --- Descriptor-field observer system --------------------------------
+    // The engine's generic "watch a descriptor field range for changes"
+    // mechanism (nodes tagged "__AUCMirrorHandler__", 0x30 bytes). The
+    // registrar attaches a node to the object's per-field observer anchors;
+    // each node keeps a private MIRROR of the watched bytes, seeded from
+    // the live value at registration. During SMSG_UPDATE_OBJECT processing
+    // the dispatcher FUN_00465570 memcmps live vs mirror and invokes the
+    // callback only on a real change (the mirror is then re-synced by
+    // FUN_004667A0). Firing engine events from the callback is sanctioned —
+    // the engine's own bag observer does exactly that.
+    //
+    // 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.
+    FUN_DESC_OBSERVER_REGISTER = 0x00467E70,
+
+    // 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*/,
+    //                     uint32_t size /*edx*/,
+    //                     uint32_t guidLo, uint32_t guidHi,
+    //                     const uint32_t *oldValue /*the node's mirror*/,
+    //                     void *userArg1)   → return 1, callee cleans 0x10.
+    // The live (new) value is NOT passed — read it from the object (the
+    // engine's bag callback reads the invMgr GUID array).
+
+    // The engine's inventory observer setup — registers the bag-slot
+    // GUID-field observers above, once per enter-world (sole caller is the
+    // enter-world initializer FUN_004908C0, latched by DAT_00B4B424).
+    // Player::Equipment co-hooks it to register the equipment-slot
+    // observers the engine never installs; the co-hook inherits the exact
+    // engine timing + lifetime (nodes die with the player object).
+    FUN_INV_OBSERVER_SETUP = 0x004F8CC0,
+
+    // PLAYER_FIELD_INV_SLOT_HEAD — first of the 19 equipment-slot u64 GUID
+    // fields in the player descriptor (0x4A8..0x538, stride 8; 0x540 is
+    // the first equipped-bag slot). 0-based slot = (offset - 0x4A8) >> 3;
+    // Lua inventory slot (GetInventoryItemLink etc.) = that + 1.
+    OFF_DESC_PLAYER_EQUIP_FIRST = 0x4A8,
+    DESC_PLAYER_EQUIP_SLOTS = 19,
+    DESC_OBSERVER_BANK_PLAYER = 4,
     // 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,

src/player/Equipment.cpp

@@ -0,0 +1,122 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `PLAYER_EQUIPMENT_CHANGED(equipmentSlot, hasCurrent)` — the WotLK-era
+// per-slot paperdoll event. Vanilla only fires UNIT_INVENTORY_CHANGED for
+// the player, which doesn't say WHICH slot changed; gear trackers and stat
+// sheets built against 3.3+ gate their refresh on this event.
+//
+// Fully event-driven via the engine's own descriptor-field observer system
+// (see the FUN_DESC_OBSERVER_REGISTER block in Offsets.h). The engine's
+// inventory setup (FUN_INV_OBSERVER_SETUP, once per enter-world) registers
+// change observers for the bag/backpack/bank/keyring GUID fields of the
+// player descriptor — but never for the 19 equipment slots (0x4A8..0x538).
+// We co-hook that setup and register our own observer per equipment field,
+// mirroring the engine's registration shape exactly (bank 4, size 8). The
+// dispatcher invokes us only when a slot's item GUID actually changed
+// (per-node mirror memcmp), so there's no polling and no diff bookkeeping
+// on our side, and the nodes share the engine observers' lifetime (they
+// die with the player object; the setup re-runs each enter-world).
+//
+// `equipmentSlot` is the 1-based Lua inventory slot (1 = head … 19 =
+// 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).
+
+#include "Game.h"
+#include "Offsets.h"
+#include "event/Custom.h"
+#include "unit/Identity.h"
+
+#include <cstdint>
+
+namespace Player::Equipment {
+
+namespace {
+
+constexpr const char *kEvtEquipmentChanged = "PLAYER_EQUIPMENT_CHANGED";
+const Event::Custom::AutoReserve _r{kEvtEquipmentChanged};
+
+using ResolveUnitToken_t = void *(__fastcall *)(const char *token);
+
+// 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) {
+    auto resolve =
+        reinterpret_cast<ResolveUnitToken_t>(Offsets::FUN_RESOLVE_UNIT_TOKEN);
+    auto *player = static_cast<const uint8_t *>(resolve("player"));
+    if (player == nullptr)
+        return false;
+    const uint8_t *invMgr = player + Offsets::OFF_PLAYER_INVENTORY_MANAGER;
+    const uint32_t count = *reinterpret_cast<const uint32_t *>(
+        invMgr + Offsets::OFF_INVMGR_SLOT_COUNT);
+    if (static_cast<uint32_t>(slot0Based) >= count)
+        return false;
+    const uint64_t *guids = *reinterpret_cast<const uint64_t *const *>(
+        invMgr + Offsets::OFF_INVMGR_GUID_ARRAY);
+    return guids != nullptr && guids[slot0Based] != 0;
+}
+
+// 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*/,
+                                   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));
+    }
+    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);
+
+void __fastcall ObserverSetup_h() {
+    g_origSetup();
+    const uint64_t guid = Unit::Identity::PlayerGuid();
+    if (guid == 0)
+        return;
+    auto reg = reinterpret_cast<RegisterObserver_t>(
+        Offsets::FUN_DESC_OBSERVER_REGISTER);
+    for (int slot = 0; slot < Offsets::DESC_PLAYER_EQUIP_SLOTS; ++slot) {
+        reg(Offsets::DESC_OBSERVER_BANK_PLAYER,
+            Offsets::OFF_DESC_PLAYER_EQUIP_FIRST + slot * 8,
+            static_cast<uint32_t>(guid), static_cast<uint32_t>(guid >> 32),
+            /*size*/ 8, reinterpret_cast<const void *>(&EquipSlotChanged_cb),
+            nullptr, nullptr);
+    }
+}
+
+static const Game::HookAutoRegister _setupHook{
+    Offsets::FUN_INV_OBSERVER_SETUP,
+    reinterpret_cast<void *>(&ObserverSetup_h),
+    reinterpret_cast<void **>(&g_origSetup)};
+
+} // namespace
+
+} // namespace Player::Equipment