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