BAG_UPDATE_DELAYED: close keyring gap with FUN_004F8DB0 hook

Pattern-search of .text confirmed exactly three FUN_FIRE_EVENT(0x148,
"%d", ...) call sites in 1.12.1. Two were already covered; the third
lives inside FUN_004F8DB0 — the bag descriptor change callback. Its
keyring branch (slot range 0x51..0x70) fires BAG_UPDATE directly
without going through FUN_004F9370, which was the documented coverage
gap (CLAUDE.md / TODO #67).

Ghidra decompile gave us the calling convention:
  __thiscall unsigned(void *bagDesc, uint, void *, uint *)

Wired as __fastcall with a dummy EDX param — same trampoline trick
used for Frame::RegisterEvent in DllMain. The non-keyring branch of
FUN_004F8DB0 still calls into FUN_004F9370 which is also hooked, but
double-fire is harmless: g_pending is idempotent until the per-frame
drain clears it.
This commit is contained in:
Brues
2026-05-17 00:12:32 -05:00
parent 2397b683f3
commit b05ff06814
2 changed files with 52 additions and 18 deletions
+15 -6
View File
@@ -1964,8 +1964,11 @@ enum Offsets {
FUN_SCRIPT_PICKUP_INVENTORY_ITEM = 0x004C8DA0, FUN_SCRIPT_PICKUP_INVENTORY_ITEM = 0x004C8DA0,
// Bag-update fire sites — see TODO #67 for the full Ghidra // Bag-update fire sites — see TODO #67 for the full Ghidra
// investigation. Hook these two to detect BAG_UPDATE fires and // investigation. Hook these three to detect BAG_UPDATE fires and
// emit BAG_UPDATE_DELAYED once per frame in which any fired. // emit BAG_UPDATE_DELAYED once per frame in which any fired.
// Pattern-search confirms only three fire sites for `0x148`
// (the BAG_UPDATE event ID) exist in 1.12.1's `.text`, and we
// cover all three.
// //
// FUN_BAG_SLOT_DIFF (`0x004F91A0`) — __cdecl `void()` (zero // FUN_BAG_SLOT_DIFF (`0x004F91A0`) — __cdecl `void()` (zero
// args, ends with plain `RET`). Walks linear slots `0x13..0x16` // args, ends with plain `RET`). Walks linear slots `0x13..0x16`
@@ -1985,13 +1988,19 @@ enum Offsets {
// field-change goes through here. 3 callers, all within the // field-change goes through here. 3 callers, all within the
// bag subsystem at `0x004F9xxx`. // bag subsystem at `0x004F9xxx`.
// //
// A third site (FUN_004F8DB0 at `0x004F8DB0`) handles keyring // FUN_BAG_KEYRING_DESC_CHANGE (`0x004F8DB0`) — __thiscall
// updates with a `BAG_UPDATE(-2)` direct fire — __thiscall // `unsigned(void *bagDesc, uint guidLo, void *guidHi, uint *current)`.
// calling convention plus ECX-context arg make the hook // Bag descriptor update callback. Computes the slot index
// signature awkward; deferred for now. The two below cover // from `((int)this - 0x4a8) >> 3`; for slots `0x51..0x70` (the
// the common cases. // keyring range) fires `BAG_UPDATE` directly. For non-keyring
// slots it delegates to `FUN_BAG_ITEM_TO_BAG`, so we'd
// double-count if we naively hooked both — the keyring branch
// is the only path here that doesn't already go through our
// other hook. Hooking is safe because the `g_pending` drain
// is idempotent (the flag stays true until WorldTick clears it).
FUN_BAG_SLOT_DIFF = 0x004F91A0, FUN_BAG_SLOT_DIFF = 0x004F91A0,
FUN_BAG_ITEM_TO_BAG = 0x004F9370, FUN_BAG_ITEM_TO_BAG = 0x004F9370,
FUN_BAG_KEYRING_DESC_CHANGE = 0x004F8DB0,
// World-subsystem per-frame update — runs exactly once per frame // World-subsystem per-frame update — runs exactly once per frame
// as part of the main world tick (`FUN_00482EA0`). Only one caller // as part of the main world tick (`FUN_00482EA0`). Only one caller
// in the entire binary; deep in the rendering/world pipeline, // in the entire binary; deep in the rendering/world pipeline,
+37 -12
View File
@@ -18,18 +18,21 @@
// //
// See TODO #67 for the full investigation history. // See TODO #67 for the full investigation history.
// //
// Architecture: two MinHooks plus one tick subscription. // Architecture: three MinHooks plus one tick subscription.
// //
// 1. `FUN_004F91A0` — bag-slot diff loop. Hook just sets the // 1. `FUN_004F91A0` — bag-slot diff loop. Hook just sets the
// `g_pending` flag. // `g_pending` flag.
// 2. `FUN_004F9370` — item→bag resolver (most common path). Hook // 2. `FUN_004F9370` — item→bag resolver (most common path). Hook
// just sets the `g_pending` flag. // just sets the `g_pending` flag.
// 3. `Tick::WorldTick::AutoSubscribe` — shared per-frame // 3. `FUN_004F8DB0` — bag-descriptor change callback. Covers the
// keyring `BAG_UPDATE(slot)` direct-fire branch that doesn't
// route through `FUN_004F9370`.
// 4. `Tick::WorldTick::AutoSubscribe` — shared per-frame
// subscription (the engine's world-subsystem update at // subscription (the engine's world-subsystem update at
// `FUN_0066FD50`, single-hooked in `src/tick/WorldTick.cpp`). // `FUN_0066FD50`, single-hooked in `src/tick/WorldTick.cpp`).
// Our callback drains `g_pending` and fires DELAYED if set. // Our callback drains `g_pending` and fires DELAYED if set.
// //
// All three targets are quiet (≤2 callers each, in code regions // All hook targets are quiet (≤3 callers each, in code regions
// other DLLs don't touch). The previous attempt at this feature // other DLLs don't touch). The previous attempt at this feature
// hooked `FUN_FIRE_EVENT` (100+ callers, in the chat path) and a // hooked `FUN_FIRE_EVENT` (100+ callers, in the chat path) and a
// per-frame UI dispatcher — both prime collision targets for // per-frame UI dispatcher — both prime collision targets for
@@ -40,16 +43,16 @@
// touches it. It runs exactly once per frame and increments // touches it. It runs exactly once per frame and increments
// the engine's own per-frame counter at `0x00C7B2C8`, so we // the engine's own per-frame counter at `0x00C7B2C8`, so we
// know it ticks 1:1 with frames. // know it ticks 1:1 with frames.
// - The bag-subsystem hooks (`FUN_004F91A0`, `FUN_004F9370`) live // - The bag-subsystem hooks (`FUN_004F91A0`, `FUN_004F9370`,
// in the `0x004F9xxx` region none of the popular DLLs care // `FUN_004F8DB0`) live in the `0x004F8xxx`/`0x004F9xxx` region
// about. // none of the popular DLLs care about.
// //
// Coverage limitation: the keyring `BAG_UPDATE(-2)` path goes // Coverage verified by pattern-searching the `.text` for every
// through `FUN_004F8DB0` (a `__thiscall` callback registered with // caller of `FUN_FIRE_EVENT(0x148, "%d", ...)` (the BAG_UPDATE
// the engine's item-descriptor change system). Hooking it cleanly // event ID): exactly three sites, all covered by these three
// needs the right calling-convention plumbing, deferred. Real // hooks. Double-fire concern with `FUN_004F8DB0` → `FUN_004F9370`
// inventory changes (the 95% case) go through one of the two // path is moot: `g_pending` is a bool, idempotent until the
// bag-subsystem hooks above. // per-frame drain clears it.
#include "Game.h" #include "Game.h"
#include "Offsets.h" #include "Offsets.h"
@@ -89,6 +92,23 @@ void __stdcall BagItemToBag_h(int guidLo, int guidHi) {
g_pending = true; g_pending = true;
} }
// `FUN_004F8DB0` — `__thiscall unsigned(this, guidLo, guidHi, *current)`.
// Bag descriptor change callback. Wired with `__fastcall` + dummy
// EDX to match the thiscall ABI: ECX takes `this`, EDX unused,
// stack takes the rest, callee cleans 12 bytes. Same trick
// `Frame::RegisterEvent` uses in DllMain.
using KeyringDescChange_t = unsigned(__fastcall *)(void *bagDesc, void *edx_unused,
unsigned guidLo, void *guidHi,
unsigned *currentGuid);
KeyringDescChange_t KeyringDescChange_o = nullptr;
unsigned __fastcall KeyringDescChange_h(void *bagDesc, void *edx,
unsigned guidLo, void *guidHi,
unsigned *currentGuid) {
const unsigned result = KeyringDescChange_o(bagDesc, edx, guidLo, guidHi, currentGuid);
g_pending = true;
return result;
}
// Per-frame drain. Runs at the tail of each world tick (subscribed // Per-frame drain. Runs at the tail of each world tick (subscribed
// through `Tick::WorldTick`, which owns the single hook on // through `Tick::WorldTick`, which owns the single hook on
// `FUN_0066FD50`). All this frame's BAG_UPDATEs have already fired // `FUN_0066FD50`). All this frame's BAG_UPDATEs have already fired
@@ -113,6 +133,11 @@ static const Game::HookAutoRegister _hookItemToBag{
reinterpret_cast<void *>(&BagItemToBag_h), reinterpret_cast<void *>(&BagItemToBag_h),
reinterpret_cast<void **>(&BagItemToBag_o)}; reinterpret_cast<void **>(&BagItemToBag_o)};
static const Game::HookAutoRegister _hookKeyringDesc{
Offsets::FUN_BAG_KEYRING_DESC_CHANGE,
reinterpret_cast<void *>(&KeyringDescChange_h),
reinterpret_cast<void **>(&KeyringDescChange_o)};
static const Tick::WorldTick::AutoSubscribe _tickSub{&OnWorldTick}; static const Tick::WorldTick::AutoSubscribe _tickSub{&OnWorldTick};
} // namespace Bag::UpdateDelayed } // namespace Bag::UpdateDelayed