From 285e6e490d83ed863a9caecbdbe3b951fa0a24a6 Mon Sep 17 00:00:00 2001
From: Brues <5278969+brues-code@users.noreply.github.com>
Date: Mon, 11 May 2026 18:27:55 -0500
Subject: [PATCH] BAG_UPDATE_DELAYED
---
README.md | 2 +-
TODO.md | 2 +-
docs/API.md | 37 ++++++++++++
src/Offsets.h | 41 +++++++++++++
src/bag/UpdateDelayed.cpp | 120 ++++++++++++++++++++++++++++++++++++++
5 files changed, 200 insertions(+), 2 deletions(-)
create mode 100644 src/bag/UpdateDelayed.cpp
diff --git a/README.md b/README.md
index 3cd1cafc..8a8813ed 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,7 @@ Quick index:
| Input | `IsLeftShiftKeyDown`, `IsRightShiftKeyDown`, `IsLeftControlKeyDown`, `IsRightControlKeyDown`, `IsLeftAltKeyDown`, `IsRightAltKeyDown`, `IsModifierKeyDown` (+ `MODIFIER_STATE_CHANGED` event) |
| Talent | `GetTalentIDByIndex`, `GetTalentSpellID` |
| Time | `GetServerTime`, `C_DateAndTime.AdjustTimeByDays`, `C_DateAndTime.AdjustTimeByMinutes`, `C_DateAndTime.CompareCalendarTime`, `C_DateAndTime.GetCalendarTimeFromEpoch`, `C_DateAndTime.GetCurrentCalendarTime`, `C_DateAndTime.GetSecondsUntilDailyReset`, `C_DateAndTime.GetServerTimeLocal` |
-| Events | `C_EventUtils.IsEventValid` |
+| Events | `C_EventUtils.IsEventValid` (+ `BAG_UPDATE_DELAYED` event) |
| Globals | `CLASSIC_API_VERSION`, `LE_EXPANSION_LEVEL_CURRENT`, `LE_EXPANSION_CLASSIC` … `LE_EXPANSION_MIDNIGHT`, `LE_ITEM_QUALITY_POOR` … `LE_ITEM_QUALITY_WOWTOKEN`, `LE_UNIT_STAT_STRENGTH` … `LE_UNIT_STAT_SPIRIT` |
## Installation
diff --git a/TODO.md b/TODO.md
index a6942cf0..a03ca56a 100644
--- a/TODO.md
+++ b/TODO.md
@@ -2107,7 +2107,7 @@ gotten clobbered — the slot-claim approach only fires after Lua's
first `RegisterEvent` call, by which point the engine's writes have
settled.
-## 67. `BAG_UPDATE_DELAYED` event - ATTEMPTED, REVERTED
+## ~~67. `BAG_UPDATE_DELAYED` event~~ — DONE (2026-05-11 second attempt)
Modern 5.4.8+ event that fires once per game frame in which any
`BAG_UPDATE` fired. The 5.4.8 engine sets an
diff --git a/docs/API.md b/docs/API.md
index a6283fe5..dacea1b7 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -124,6 +124,7 @@ build instructions.
- [`C_DateAndTime.GetSecondsUntilDailyReset()`](#c_dateandtimegetsecondsuntildailyreset)
- [Events](#events)
- [`C_EventUtils.IsEventValid(eventName)`](#c_eventutilsiseventvalideventname)
+ - [`BAG_UPDATE_DELAYED` event](#bag_update_delayed-event)
- [Globals](#globals)
- [`CLASSIC_API_VERSION`](#classic_api_version)
- [`LE_EXPANSION_*`](#le_expansion_)
@@ -2778,6 +2779,42 @@ SuperWoWhook patches the binary's event names with its own. This matches
what `frame:RegisterEvent` will actually accept, which is what addon code
needs to know.
+### `BAG_UPDATE_DELAYED` event
+
+Fires (with no payload) once per frame in which any `BAG_UPDATE`
+fired. Matches modern WoW's coalescing semantic exactly — register
+for `BAG_UPDATE_DELAYED` instead of `BAG_UPDATE` and rescan once
+per frame regardless of how many updates fired.
+
+```lua
+local f = CreateFrame("Frame")
+f:RegisterEvent("BAG_UPDATE_DELAYED")
+f:SetScript("OnEvent", function() RescanMyInventory() end)
+```
+
+A trade with 6 stacks (12 `BAG_UPDATE`s, all processed in one
+frame) produces exactly 1 `BAG_UPDATE_DELAYED` at the end of the
+frame — matches Classic Era 1.15.x's observed behavior.
+
+Implemented by three hooks, none in regions other DLLs touch:
+- `FUN_004F91A0` / `FUN_004F9370` (bag subsystem at `0x004F9xxx`)
+ — each just sets a `g_pending` flag, no fire
+- `FUN_0066FD50` (engine's per-frame world-subsystem update at
+ `0x0066xxxx`, deep in the rendering pipeline, only one caller in
+ the entire binary) — drains the flag at the tail of the world
+ tick
+
+The world-tick hook is a tail hook (run original first, then fire
+DELAYED), so the fire happens after every other per-frame world
+work completes. Addon callbacks see DELAYED after their normal
+event handlers.
+
+> **Coverage limitation.** The keyring `BAG_UPDATE(-2)` path goes
+> through a separate function (`FUN_004F8DB0`) that uses
+> `__thiscall` with an awkward register-arg shape. Keyring updates
+> currently won't trigger `BAG_UPDATE_DELAYED`. Player bag (0..4)
+> and bank (5..10) updates work normally — the 95% case.
+
## Globals
### `CLASSIC_API_VERSION`
diff --git a/src/Offsets.h b/src/Offsets.h
index 90688784..c743988f 100644
--- a/src/Offsets.h
+++ b/src/Offsets.h
@@ -1289,6 +1289,47 @@ enum Offsets {
FUN_SCRIPT_CLEAR_CURSOR = 0x004895B0,
FUN_SCRIPT_PICKUP_INVENTORY_ITEM = 0x004C8DA0,
+ // Bag-update fire sites — see TODO #67 for the full Ghidra
+ // investigation. Hook these two to detect BAG_UPDATE fires and
+ // emit BAG_UPDATE_DELAYED once per frame in which any fired.
+ //
+ // FUN_BAG_SLOT_DIFF (`0x004F91A0`) — __cdecl `void()` (zero
+ // args, ends with plain `RET`). Walks linear slots `0x13..0x16`
+ // (player bags 1..4) and `0x3B..0x44` (bank bags 5..10),
+ // comparing each against a cached GUID snapshot at
+ // `DAT_00BDD060`. Fires `BAG_UPDATE(bagID)` for each slot
+ // whose GUID changed. Called from per-session init
+ // (FUN_004F8CC0) and a packet handler (FUN_004F8EC0) — 2
+ // callers total, very quiet hook target.
+ //
+ // FUN_BAG_ITEM_TO_BAG (`0x004F9370`) — __stdcall
+ // `void(int guidLo, int guidHi)` (ends with `RET 0x8`).
+ // Given an item GUID, searches the bag cache for which bag
+ // contains it. Fires `BAG_UPDATE(0)` for backpack,
+ // `BAG_UPDATE(N)` for bag N, returns silently if not in any
+ // bag. **Most common BAG_UPDATE path** — every per-item
+ // field-change goes through here. 3 callers, all within the
+ // bag subsystem at `0x004F9xxx`.
+ //
+ // A third site (FUN_004F8DB0 at `0x004F8DB0`) handles keyring
+ // updates with a `BAG_UPDATE(-2)` direct fire — __thiscall
+ // calling convention plus ECX-context arg make the hook
+ // signature awkward; deferred for now. The two below cover
+ // the common cases.
+ FUN_BAG_SLOT_DIFF = 0x004F91A0,
+ FUN_BAG_ITEM_TO_BAG = 0x004F9370,
+ // World-subsystem per-frame update — runs exactly once per frame
+ // as part of the main world tick (`FUN_00482EA0`). Only one caller
+ // in the entire binary; deep in the rendering/world pipeline,
+ // nowhere near the chat/cast/transmog code regions that other
+ // DLLs (SuperWoWhook / nampower / transmogfix) hook. We hook the
+ // tail of this function to drain `BAG_UPDATE_DELAYED`'s pending
+ // flag — exact per-frame coalescing matching modern WoW.
+ //
+ // Calling convention: `__fastcall(int ecx, int edx, int stackArg)`,
+ // `RET 0x4` (callee cleans the one stack arg).
+ FUN_WORLD_TICK = 0x0066FD50,
+
// Engine session globals used by `EquipmentSet::Storage` to build
// the per-character WTF path. Same layout VanillaMinimapTracking
// uses for its own persistence file. Account is the value WoW
diff --git a/src/bag/UpdateDelayed.cpp b/src/bag/UpdateDelayed.cpp
new file mode 100644
index 00000000..d9ef286f
--- /dev/null
+++ b/src/bag/UpdateDelayed.cpp
@@ -0,0 +1,120 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU Lesser 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 Lesser General Public License for more details.
+//
+// You should have received a copy of the GNU Lesser General Public License along with
+// ClassicAPI. If not, see .
+
+// `BAG_UPDATE_DELAYED` event — fires once per frame in which any
+// `BAG_UPDATE` fired. Polyfills modern WoW's event of the same name
+// (added 5.4.x) with exact same-semantic coalescing: addons listen
+// to DELAYED instead of BAG_UPDATE and rescan once per frame.
+//
+// See TODO #67 for the full investigation history.
+//
+// Architecture: three hooks total.
+//
+// 1. `FUN_004F91A0` — bag-slot diff loop. Hook just sets the
+// `g_pending` flag.
+// 2. `FUN_004F9370` — item→bag resolver (most common path). Hook
+// just sets the `g_pending` flag.
+// 3. `FUN_0066FD50` — engine's per-frame world-subsystem update.
+// Hook drains `g_pending` and fires DELAYED if set.
+//
+// All three targets are quiet (≤2 callers each, in code regions
+// other DLLs don't touch). The previous attempt at this feature
+// hooked `FUN_FIRE_EVENT` (100+ callers, in the chat path) and a
+// per-frame UI dispatcher — both prime collision targets for
+// SuperWoWhook / nampower / transmogfix. By contrast:
+//
+// - `FUN_0066FD50` is the WORLD-subsystem update (not the UI one),
+// deep in the rendering pipeline. Only one caller, no DLL
+// touches it. It runs exactly once per frame and increments
+// the engine's own per-frame counter at `0x00C7B2C8`, so we
+// know it ticks 1:1 with frames.
+// - The bag-subsystem hooks (`FUN_004F91A0`, `FUN_004F9370`) live
+// in the `0x004F9xxx` region none of the popular DLLs care
+// about.
+//
+// Coverage limitation: the keyring `BAG_UPDATE(-2)` path goes
+// through `FUN_004F8DB0` (a `__thiscall` callback registered with
+// the engine's item-descriptor change system). Hooking it cleanly
+// needs the right calling-convention plumbing, deferred. Real
+// inventory changes (the 95% case) go through one of the two
+// bag-subsystem hooks above.
+
+#include "Game.h"
+#include "Offsets.h"
+#include "event/Custom.h"
+
+namespace Bag::UpdateDelayed {
+
+namespace {
+
+constexpr const char *kEventName = "BAG_UPDATE_DELAYED";
+
+const Event::Custom::AutoReserve _reserve{kEventName};
+
+// Set by the bag-update hooks, drained by the world-tick hook.
+// Single bool, no atomics needed — the engine is single-threaded.
+bool g_pending = false;
+
+} // namespace
+
+// `FUN_004F91A0` — `__cdecl void()`. Bag-slot diff loop. Walks the
+// 10 bag slots, fires BAG_UPDATE for each that changed.
+using BagSlotDiff_t = void(__cdecl *)();
+BagSlotDiff_t BagSlotDiff_o = nullptr;
+void __cdecl BagSlotDiff_h() {
+ BagSlotDiff_o();
+ g_pending = true;
+}
+
+// `FUN_004F9370` — `__stdcall void(int guidLo, int guidHi)`. Most
+// common BAG_UPDATE path — fires from every per-item descriptor
+// field change.
+using BagItemToBag_t = void(__stdcall *)(int guidLo, int guidHi);
+BagItemToBag_t BagItemToBag_o = nullptr;
+void __stdcall BagItemToBag_h(int guidLo, int guidHi) {
+ BagItemToBag_o(guidLo, guidHi);
+ g_pending = true;
+}
+
+// `FUN_0066FD50` — `__fastcall(int, int, int)` per-frame world tick.
+// We hook the TAIL: run the original first (so all of this frame's
+// world-tick work completes), then drain the pending flag and fire
+// DELAYED if any BAG_UPDATE happened this frame.
+using WorldTick_t = void(__fastcall *)(int arg1, int arg2, int arg3);
+WorldTick_t WorldTick_o = nullptr;
+void __fastcall WorldTick_h(int arg1, int arg2, int arg3) {
+ WorldTick_o(arg1, arg2, arg3);
+ if (!g_pending)
+ return;
+ g_pending = false;
+ const int slot = Event::Custom::Lookup(kEventName);
+ if (slot >= 0)
+ Event::Custom::Fire_None(slot);
+}
+
+static const Game::HookAutoRegister _hookSlotDiff{
+ Offsets::FUN_BAG_SLOT_DIFF,
+ reinterpret_cast(&BagSlotDiff_h),
+ reinterpret_cast(&BagSlotDiff_o)};
+
+static const Game::HookAutoRegister _hookItemToBag{
+ Offsets::FUN_BAG_ITEM_TO_BAG,
+ reinterpret_cast(&BagItemToBag_h),
+ reinterpret_cast(&BagItemToBag_o)};
+
+static const Game::HookAutoRegister _hookWorldTick{
+ Offsets::FUN_WORLD_TICK,
+ reinterpret_cast(&WorldTick_h),
+ reinterpret_cast(&WorldTick_o)};
+
+} // namespace Bag::UpdateDelayed