Files
ClassicAPI/TODO.md
T
Brues 428c3308c6 docs(todo): add #101 Frame:SetOnUpdateMode
Records the engine trail found while evaluating it: the per-frame
dispatcher FUN_0076B2C0 (vtable +0x38, __thiscall(frame, float elapsed),
fires the OnUpdate slot at +0x128) and the walk FUN_00765650, which
iterates nine strata buckets of the frame+0x310 intrusive list with NO
visibility check in either place. Visibility is list membership, and that
list is the render list -- which is what splits the enum: Disabled /
RunWhenVisible / RunWhenVisibleOnce need only a co-hook on the
dispatcher, while RunOnce / RunAlways have to be driven from the
already-owned WorldTick because a hidden frame is not in the list at all
and forcing it in would try to draw it.

Also notes the open question (which elapsed the self-driven modes pass,
and whether WorldTick runs before or after the UI pass), that no loaded
DLL references either function, and that RunAlways is the only genuinely
new capability -- the rest is parity with existing idioms.
2026-09-15 02:16:45 -05:00

3981 lines
188 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ClassicAPI — TODO
Candidates for new DLL functions, prioritized. All are things the
[!!!ClassicAPI](C:\WoW\FrostmourneClient\Interface\AddOns\!!!ClassicAPI) Lua
addon polyfills badly, hackily, or not at all, and where engine access is the
right answer.
## ~~1. `C_QuestLog.IsQuestFlaggedCompleted(questID)`~~ — NOT FEASIBLE in 1.12
The original TODO note ("engine maintains a completed-quests bitfield in
client memory") was based on 3.3.5 / WotLK semantics. Vanilla 1.12 has no
equivalent: neither `QueryQuestsCompleted` nor `GetQuestsCompleted`
exists, the protocol has no `CMSG_QUERY_QUESTS_COMPLETED`, and the
client doesn't track historical completions. The polyfill at
`Util/C_QuestLog.lua:5-8` works on Frostmourne (3.3.5a) where those
functions exist; on the 1.12 Octo client they're absent.
Servers that want to expose this in 1.12 (notably Turtle WoW) do it
via the `CHAT_MSG_ADDON` channel — the addon sends `.queststatus` over
guild/whisper chat and the server replies with addon-channel messages
the addon parses. Fundamentally async, server-specific, and requires
SavedVariables-style persistence across sessions to amortize the
round-trip — all of which belong on the Lua side, not in this DLL.
There's nothing the DLL can usefully add here.
## ~~2. `C_Spell.GetSpellDescription(spellID)`~~ — DONE
Calls the engine's own spell-description formatter at `0x005075F0`,
which reads the description string from `Spell.dbc` (record `+0x228`,
locale-applied) and resolves `$s1`/`$s2`/`$o1`/`$d`-style placeholders
character-by-character. 8 callers in the engine (spell tooltip builder,
talent UI, trainer, etc.); we mirror the simplest one's args
(`contextFlag=0` = "no caster scaling, base-rank values"). Output goes
into a 1024-byte caller-provided buffer that the helper null-terminates.
The interesting find: I expected the description to need a CGUnit
context for substitution, but the engine has a "no scaling" code path
that produces `"14 to 22 Fire damage"` (Fireball Rank 1's actual base
range) without any unit reference. That's the right semantic for
"describe this spell" — modern WoW behaves the same when called outside
a unit context.
Side note: a global at `0x00BE0B80` is the formatter's parser cursor
(it walks the description string char-by-char, advancing the cursor in
place). It's set and managed entirely inside the helper — callers don't
touch it. Lua C functions are single-threaded, so the global state is
safe to share with whatever else might call the formatter (it's all on
the same thread).
See [src/spell/Description.cpp](src/spell/Description.cpp) and the
`FUN_FORMAT_SPELL_DESCRIPTION` block in [src/Offsets.h](src/Offsets.h)
for the full calling convention (8-arg `__fastcall`).
## ~~3. `C_Item.IsBound` / `isBound` from `GetContainerItemInfo`~~ — DONE
Implemented as `C_Item.IsBound(itemLocation)`. Reads the soulbound bit
(`ITEM_FIELD_FLAGS` bit 0) directly off the CGItem's UpdateField
descriptor — no scan-tooltip hack, no string comparison. Accepts the
modern `{equipmentSlotIndex=N}` and `{bagID=B, slotIndex=S}` location
shapes. See [src/item/Bound.cpp](src/item/Bound.cpp) for the soulbound
read; the slot-resolution chain it depends on lives in
[src/item/Location.cpp](src/item/Location.cpp).
## ~~4. `GetSpellInfo` for unlearned spells~~ — DONE
Implemented as the global `GetSpellInfo(spellID)`. Returns the full 9-tuple
matching 3.3.5 semantics, including `true`/`false` for `isFunnel` (verified
against the 3.3.5 client). See [src/SpellInfo.cpp](src/SpellInfo.cpp).
## ~~5. `GetServerTime()`~~ — DONE
Reads year/month/day/hour/minute from the engine's game-time struct at
`0x00CE8538` (populated by `SMSG_LOGIN_VERIFY_WORLD` /
`SMSG_LOGIN_SETTIMESPEED` and advanced by the internal tick handler)
and converts via `_mkgmtime` to a Unix epoch timestamp.
The interesting find: the engine has its own "to seconds since epoch"
helper at `0x00642320` that I almost reused — but decoding the magic
constant `0xC22E4507` after the `_mkgmtime` call revealed the helper
divides the result by `86400` (seconds in a day), so it returns
**days-since-epoch**, not seconds. Rolled our own `_mkgmtime` call
instead.
The 1.12 wire protocol carries time at minute granularity — there are
no seconds in `SMSG_LOGIN_SETTIMESPEED`'s packed gametime field — so
the engine's stored hour/minute steps once per minute. To make the
returned timestamp tick every second (which is what `GetServerTime`
callers actually need), we interpolate within the minute using
`GetTickCount`: whenever the engine's minute changes, we anchor to the
current tick and add `(now - anchor) / 1000` for subsequent calls. The
cold-start value is off by 0..59 seconds since we have no way to know
how far into a minute the engine is the first time we observe it, but
after the first minute rollover the anchor lands at the boundary and
the timestamp is accurate for the rest of the session.
See [src/time/Server.cpp](src/time/Server.cpp) and
`VAR_GAMETIME_STRUCT` / `OFF_GAMETIME_*` in
[src/Offsets.h](src/Offsets.h).
## ~~6. `C_QuestLog.GetTitleForQuestID(questID)`~~ — DONE
Reads the title out of the quest static-info cache at offset `+0x9C`
(inline null-terminated C string within the data block returned by the
cache's `_GetRecord`). Title-offset derivation: traced from the engine's
own quest-log title path at `0x004DF180`, which calls `_GetRecord` and
then does `add eax, 0x9C; ret` — the result is fed directly to
`lua_pushstring`, so `+0x9C` is the C string itself, not a pointer.
The original TODO note "engine has the title in `Quest.dbc`" turned out
to be wrong — there is no `Quest.dbc` in 1.12 (only `QuestInfo.dbc` for
reward types and `QuestSort.dbc` for category headers). All quest static
data is server-authoritative, fetched via `SMSG_QUEST_QUERY_RESPONSE` and
held in the runtime cache at `0x00C0E1B0`. The "async dance" the polyfill
does is the unavoidable cost of that — though now it's just one call to
`C_QuestLog.RequestLoadQuestByID` plus an `OnEvent` listener instead of
a hidden tooltip and a 180-second timeout.
See [src/quest/Title.cpp](src/quest/Title.cpp) and the shared cache
helper at [src/quest/Cache.h](src/quest/Cache.h). The data-block field
offsets (currently just `+0x9C` for title) live in `Cache.h` alongside
the `Lookup`/`Peek` wrappers, so additional cached fields like
description and objectives can be added there as we trace them.
## ~~7. `UnitAuraBySlot` / `UnitAuraSlots`~~ — DROPPED (obviated by `C_UnitAuras`)
Modern's slot system was a Shadowlands-era continuation-token pattern
for huge aura sets — pointless on vanilla where the per-unit aura
array caps at 48 and `C_UnitAuras.GetUnitAuras(unit, [filter])`
returns all of them in one call. `GetAuraDataByIndex` /
`GetUnitAuraBySpellID` / `GetPlayerAuraBySpellID` cover the
lookup-by-index and lookup-by-spellID consumer patterns. The
`Util/Aura.lua` / `Util/AuraUtil.lua` files referenced by the
original TODO no longer exist in the repo.
## ~~8. `GetItemInfo` for uncached items~~ — DONE (via #12 + #13)
The "cache-fill path with a proper async callback so addons stop polling
on a frame timer" goal landed as the request/event pair below:
- **#12** ships `C_Item.IsItemDataCachedByID(item)` /
`C_Item.RequestLoadItemDataByID(item)` (and the ItemLocation
variants), wrapping the engine's existing
`DBCache_ItemStats_C_GetRecord` at `0x55BA30` with a non-NULL callback
to trigger the SMSG_ITEM_QUERY_SINGLE network fetch.
- **#13** ships `ITEM_DATA_LOAD_RESULT(itemID, success)`, fired from our
`__stdcall` callback when the engine drops the response into the
cache (or synchronously if it was already loaded).
Together those replace the polyfill's 180-second polling frame
(`ItemEventListener` in `Util/ItemUtil.lua:254-372`) — addons can now
fire `RequestLoadItemDataByID(id)` and listen for
`ITEM_DATA_LOAD_RESULT` instead.
A single `GetItemInfo(item)` that "returns nil and triggers a load" in
one call (matching modern WoW's `GetItemInfo` semantics for uncached
items) would be a thin convenience wrapper on top, but the modern
preferred pattern is exactly the request/event pair we have, so it's
not pursued separately.
## ~~9. `C_Item.GetItemInfoInstant(item)`~~ — DONE (not in original list)
The always-available subset of `GetItemInfo` — fields that depend only on
classification, not on player-specific state. Accepts itemID or
`item:NNN` link strings (full chat links work too); returns nil for
uncached items rather than blocking on a server query. See
[src/item/Info.cpp](src/item/Info.cpp). Reading `ItemSubClass.dbc` was the
fiddly bit (parallel-storage hack at `+0x00`/`+0x04` for compound-key
lookup, plus a verbose→short locale-name fallback chain) — full notes in
[CLAUDE.md](CLAUDE.md) and [src/Offsets.h](src/Offsets.h).
## ~~10. `C_Item.GetItemID(itemLocation)`~~ — DONE (not in original list)
Returns the itemID for the item at a given equipment slot or bag/slot
tuple. Useful as the input to `GetItemInfoInstant`/`GetItemInfo` when you
only know which slot an item came from. Required factoring out the shared
slot-resolution code from `IsBound` into [src/item/Location.cpp](src/item/Location.cpp);
the GetItemID-specific bit (one extra deref) lives in
[src/item/ID.cpp](src/item/ID.cpp). The non-obvious part: the itemID
isn't in the CGItem's UpdateField descriptor (its `OBJECT_FIELD_ENTRY`
slot is empirically 0), but in a separate instance block at `CGItem+0x08`.
## ~~11. `C_EventUtils.IsEventValid(eventName)`~~ — DONE (not in original list)
Walks the engine's static event-name table at `0x00BE11D8` and returns
`true` if any populated slot contains the queried name. See
[src/event/Util.cpp](src/event/Util.cpp). The interesting bit: third-party
DLLs (notably SuperWoWhook on Turtle clients) inject custom events by
**overwriting `.rdata` event-name strings in place** rather than appending
to the table — so a runtime walk picks up their additions for free. Full
notes in [CLAUDE.md](CLAUDE.md).
## ~~12. `C_Item.IsItemDataCached*` / `RequestLoadItemData*`~~ — DONE (not in original list)
Wraps the engine's existing client-side item cache (`_GetRecord` at
`0x55BA30`, `requestIfMissing` flag). Both `ByID` and ItemLocation
variants ship. See [src/item/Data.cpp](src/item/Data.cpp).
## ~~13. `ITEM_DATA_LOAD_RESULT` event~~ — DONE
Fires with `(itemID, success)` when an item finishes loading after a
`RequestLoadItemData*` call (or synchronously when the data was already
cached). See [src/event/Custom.cpp](src/event/Custom.cpp) for the
custom-event plumbing and [src/item/Data.cpp](src/item/Data.cpp) for
the wiring to the cache callback.
The investigation needed three engine pieces nobody had documented:
- **Dispatcher** at `0x00703F50` — `__cdecl void(int eventID, const char *fmt, ...)`,
149 callers, indexes the table at `[0xCEEF68] + id*16`, walks the
subscriber chain. Format is printf-style (`%s`, `%d`, `%u`, `%f`); no
bool code, pass `%d` with 0/1.
- **Registration table** at `[0xCEEF68]` (count at `[0xCEEF64]`),
16-byte entries, name at `+0x00`, subscriber chain head at `+0x0C`.
`Frame::RegisterEvent` at `0x00702140` strcmps event names against
this table.
- **Teardown landmine.** `FrameScript_Initialize`'s reload path
(`0x00701A40`) calls `SMemFree(entry.name)` on every entry; our static
literals are not Storm-allocated and trip the safety check. There's a
NULL-name shortcut (`jz` at `0x00701A45`) so we null our entries
before the engine sees them.
Full notes in [CLAUDE.md](CLAUDE.md) under "Firing a custom event
end-to-end".
## ~~14. `C_QuestLog.RequestLoadQuestByID` + `QUEST_DATA_LOAD_RESULT`~~ — DONE (not in original list)
Fires `QUEST_DATA_LOAD_RESULT(questID, success)` when quest static info
(description, objectives, reward text) finishes loading. Synchronously
fired when the questID was already in the client cache; asynchronously
fired after `SMSG_QUEST_QUERY_RESPONSE` when the engine has to round-trip.
Implemented as a near-direct mirror of `Item::Data`: the quest cache
`_GetRecord` at `0x00562A40` has the same five-arg shape and the same
`callback != NULL` gate as the item cache `_GetRecord`. The interesting
investigation was confirming that `[0x00BB7480]` (passed as the cache
key in `Script_GetQuestLogQuestText`) is a *questID*, not a struct
pointer — verified by tracing the load site at `0x004DEF5D` back through
`mov eax, [esi + 0x00BB71C0]`, which reads field +0 of a quest log
entry (= questID per the quest log struct). The cache is then keyed by
questID just like the item cache is keyed by itemID.
See [src/quest/Data.cpp](src/quest/Data.cpp) and "Quest static-info
cache" in [CLAUDE.md](CLAUDE.md). The custom-event plumbing
([src/event/Custom.cpp](src/event/Custom.cpp)) is shared with
`ITEM_DATA_LOAD_RESULT` — no new infrastructure needed.
## ~~15. `GetFactionInfoByID` / `GetFactionIDByIndex`~~ — DONE (not in original list)
`GetFactionInfoByID(factionID)` returns the same 11 values as
`GetFactionInfo(factionIndex)` keyed by factionID — implemented as a thin
wrapper that walks the engine's index→ID resolver at `0x004D5FA0` to find
the displayed-list index for the requested ID, then replaces Lua arg 1 and
tail-calls `Script_GetFactionInfo` (`0x004D64F0`). Only works for factions
the player has rep with, matching modern WoW's semantics.
`GetFactionIDByIndex(factionIndex)` exposes the same resolver directly —
returns the factionID for real entries, `0` for headers (normalizing the
engine's mix of `0` for "Other" and `-1` for "Inactive"), `nil` for OOB.
Modern WoW (5.0+, including Classic Era 1.15.x) returns this as the 14th
value of `GetFactionInfo`, but 1.12-3.3.5 don't expose it at all.
See [src/faction/Info.cpp](src/faction/Info.cpp) and "Faction lookups" in
[CLAUDE.md](CLAUDE.md) for the resolver/dual-count details.
## ~~16. `C_Container.GetContainerItemID(bagIndex, slotIndex)`~~ — DONE
Shipped under the modern `C_Container.*` namespace (matching post-MoP
WoW). Wraps the existing bag→CGItem path: a new public
`Item::Location::ResolveBag(L, bagID, slotIndex)` exposes the bag
resolver that was previously private inside the table-shape
`Resolve()`, and a small `ItemIDFromCGItem` helper in
[src/item/ID.cpp](src/item/ID.cpp) factors out the CGItem → instance
block → itemID step now used by both `C_Item.GetItemID` and
`C_Container.GetContainerItemID`.
Note: ships under `C_Container` rather than as the historical legacy
global `GetContainerItemID` since the modern namespace is the canonical
home for bag/container APIs (the global was deprecated in 10.0). If
addons need the legacy global it's a one-line addition.
## ~~17. `GetItemIcon(itemID)` / `C_Item.GetItemIcon(itemLocation)` / `C_Item.GetItemIconByID(item)`~~ — DONE
Three Lua entry points that all share a `PushIconForItemID(L, itemID)`
helper in [src/item/Info.cpp](src/item/Info.cpp). The helper routes
through the existing `FetchItemRecord` (item cache) and `BuildIconPath`
(`ItemDisplayInfo.dbc` lookup at `+0x14`) — same code path
`GetItemInfoInstant` already runs, just stripped to the icon-only return.
The refactor that fell out: extracted `Item::ID::FromCGItem` (the
CGItem → instance-block → itemID step) into [src/item/ID.h](src/item/ID.h)
so both `Item::ID` (for `C_Item.GetItemID` and
`C_Container.GetContainerItemID`) and `Item::Info` (for
`C_Item.GetItemIcon`'s ItemLocation form) can share it. Was static-dup
across two files before this; now it's one definition.
Returns the path string (deviation from modern's `fileID:number` —
1.12 has no fileID system; same call-out as
`C_Spell.GetSpellTexture`'s docs).
## ~~18. `UnitGUID(unit)`~~ — DONE
Returns the unit's 64-bit GUID as `"0xHHHHHHHHLLLLLLLL"` (16 hex
digits, hi dword first). Reads `*(unit + OFF_UNIT_GUID_PTR)` to get
the 8-byte struct, formats with `snprintf`. Lives in
[src/unit/Identity.cpp](src/unit/Identity.cpp).
Two behavioral notes worth flagging in docs:
- **Vanilla format, not modern's prefix shape.** 1.12 GUIDs are plain
64-bit integers (the `"Player-1234-..."` / `"Creature-0-..."`
formatted GUIDs were a 6.0 addition). Addons backporting modern
GUID parsers need to accept the `"0x..."` form.
- **Errors on totally-unknown unit tokens.** `ResolveUnitToken` itself
raises `"Unknown unit name: <token>"` for strings outside the known
unit-ID list. We don't suppress it — matches how every other 1.12
unit-token function (`UnitName`, `UnitAffectingCombat`, etc.)
behaves. Tokens that resolve to "no current unit" (e.g. `"target"`
with nothing targeted) cleanly return nil via the GUID-is-zero
short-circuit.
## ~~19. `IsPassiveSpell` / `C_Spell.IsSpellPassive`~~ — DONE
Reads `Attributes` (+0x18) bit 6 (`SPELL_ATTR_PASSIVE = 0x40`) off the
`Spell.dbc` record — same pattern [src/spell/Info.cpp](src/spell/Info.cpp)
already used for `isFunnel` (AttributesEx bit 6, on a different field).
Shipped both forms with shared `PushIsPassive` back-end:
- `IsPassiveSpell(spellID)` / `IsPassiveSpell(slot, bookType)` — the
3.0-era global, supports both arg shapes via `ResolveLuaArgsToSpellID`
(mirrors `GetSpellInfo` / `GetSpellLink`).
- `C_Spell.IsSpellPassive(spellID)` — the modern 10.0 form (word order
flipped during the `C_Spell` namespace migration). spellID-only.
## ~~20. `GetSpellLink(spellID)` / `C_Spell.GetSpellLink(spellID)`~~ — DONE
Builds `|cff71d5ff|Hspell:ID:0|h[Name]|h|r` via `snprintf` after a
single `Spell.dbc` name read. The trailing `:0` after the spellID
matches modern's hyperlink shape so addons backporting from later
expansions can `gsub` with the standard `|Hspell:(%d+):` pattern; 1.12
ignores it during link parsing.
Both forms shipped:
- `GetSpellLink(spellID)` and `GetSpellLink(slot, bookType)` (global)
return `(link, spellID)`. The slot-and-bookType overload reuses the
same `Spell::Lookup::ResolveLuaArgsToSpellID` helper as
`GetSpellInfo`.
- `C_Spell.GetSpellLink(spellID)` (table) returns just the link string
— the caller already had the spellID on hand.
See [src/spell/Info.cpp](src/spell/Info.cpp) `Script_GetSpellLink` /
`Script_C_GetSpellLink` and the `BuildSpellLink` helper.
## ~~21. `InCombatLockdown()`~~ — DONE
Reads `UNIT_FLAG_IN_COMBAT` (bit 19, `0x00080000`) of the player's
UNIT_FIELD_FLAGS — same bit `Script_UnitAffectingCombat` at
`0x00517E4A`-`0x517E5C` tests via `mov eax, [fields+0xA0]; shr eax, 19;
test al, 1`. Modern WoW's "lockdown" gates secure-frame UI changes;
1.12 has no secure-frame system, so the function reduces to a plain
"is the player in combat" check (equivalent to
`UnitAffectingCombat("player")` but skips the unit-token resolution).
Lives in [src/unit/Combat.cpp](src/unit/Combat.cpp) — first occupant of
the new `src/unit/` directory. Future unit-flag accessors
(`UnitIsAFK`, `UnitIsDND`, `UnitIsFeignDeath`, `UnitClassBase`, etc.)
can land alongside without polluting the per-domain Lua-namespace
directories.
## ~~22. `UnitClassBase(unit)`~~ — DONE
Locale-independent class file string (`"WARRIOR"`, `"MAGE"`, etc.).
Resolves the unit via `FUN_RESOLVE_UNIT_TOKEN`, reads the class
byte from `UNIT_FIELD_BYTES_0` (descriptor `+0x79`, same byte
`Script_UnitClass`'s general-token branch uses), and looks up
`ChrClasses.dbc::Filename` (record `+0x38`) for the english token.
Works for any synced unit — both fields are broadcast UpdateField /
static-DBC data. Returns nil for unresolvable units (empty
`partyN` slot, `target` with no target, out-of-range class byte
for non-player units). Implementation uses the existing
`DBC::StringField` helper so the bounds-checking and locale-array
hairiness stays in one place.
See [src/unit/ClassBase.cpp](src/unit/ClassBase.cpp).
## ~~23. `GetItemSpell(item)`~~ — DONE
Returns `(spellName, spellID)` for the on-use spell attached to an
item (potions, trinkets, scrolls, hearthstone, food/drink), or nil
for items without one. Reads the cached `ItemStats_C` record's
`m_spellId[5]` array at `+0x11C` and `m_spellTrigger[5]` at `+0x130`,
matching the first slot with `trigger == 0` (`ITEM_SPELLTRIGGER_ON_USE`).
Combines with `Spell.dbc.Name[locale]` at record `+0x1E0` for the
spell name.
Offsets computed from VanillaHelpers's fully-decoded
`ItemStats_C` struct; verified empirically against Hearthstone
(itemID 6948, slot-0 spell 8690, trigger 0). Other trigger codes
(`ON_EQUIP`=1, `CHANCE_ON_HIT`=2, `SOULSTONE`=4, `LEARN_SPELL`=6)
are deliberately ignored — matches modern WoW's `GetItemSpell`,
which only reports the on-use spell.
Same auto-warmup pattern as the other cache-backed accessors:
returns nil for uncached items and silently fires the cache fill,
so a follow-up call after `GET_ITEM_INFO_RECEIVED` lands the data.
See [src/item/Spell.cpp](src/item/Spell.cpp).
## ~~24. `GetInventoryItemDurability(invSlot)` / `C_Container.GetContainerItemDurability(containerIndex, slotIndex)`~~ — DONE
Returns `(current, max)` durability for the player's equipped item or
bag/bank slot, or nothing if the slot is empty or the item has no
durability concept (consumables, materials, rings, trinkets, shirts,
tabards). Both forms shipped:
- `GetInventoryItemDurability(invSlot)` — character-pane equipment slot
(1-based, 1..19). Player-only by design, matches modern API; the
original TODO line had `(unit, slot)` but modern
`GetInventoryItemDurability` takes only the slot.
- `C_Container.GetContainerItemDurability(containerIndex, slotIndex)` —
bag/bank slot. Goes through `Item::Location::ResolveBag` →
`PackBagSlot` → `GetItemBySlot`, same chain
`C_Container.GetContainerItemID` already used.
Both share the inner `PushDurabilityForItem` helper — only the
CGItem-resolution path differs. Reads ITEM_FIELD_DURABILITY (+0xA0) and
ITEM_FIELD_MAXDURABILITY (+0xA4) off the CGItem descriptor at `+0x114`
— the same descriptor [src/item/Bound.cpp](src/item/Bound.cpp) reads
FLAGS from. Field offsets verified by decoding
`Script_GetInventoryItemBroken` at `0x004C8590`, which tests
`[descriptor+0x3C] & 0x08` for the broken flag bit AND
`[descriptor+0xA4] > 0 && [descriptor+0xA0] == 0` as a fallback.
Modern semantics confirmed against 3.3.5's
`Script_GetInventoryItemDurability` at `0x005EA170`: returns nothing
(0 values) when max is 0.
See [src/item/Durability.cpp](src/item/Durability.cpp).
## ~~25. `FindSpellBookSlotByID(spellID)`~~ — DONE
Walks the player spellbook at `0x00B700F0` first, then the pet
spellbook at `0x00B6F098`, returning `(slot, bookType)` for the first
match. Bounds at `SPELLBOOK_MAX_SLOTS = 0x400` (the engine's own cap
in `Script_GetSpellName`); empty/zero entries past the populated count
are skipped naturally since spellID 0 doesn't match any positive
input. Result feeds directly into the slot-and-bookType API surface
(`GetSpellName`, `GameTooltip:SetSpell`, etc.).
Logic added to [src/spell/Lookup.cpp](src/spell/Lookup.cpp) as
`Spell::Lookup::FindSpellbookSlot`; the Lua C function lives next to
the other spell registrations in [src/spell/Info.cpp](src/spell/Info.cpp).
## ~~26. `C_Item.IsEquippableItem(item)`~~ — DONE
Cache-record read of `m_inventoryType` at `OFF_ITEMSTATS_INVENTORY_TYPE`.
Non-zero = equippable. Lives in `item/Equipment.cpp` alongside
`OffhandHasWeapon` (which uses the same field) and `IsEquippedItem`.
Synchronous; returns `false` on cache miss without firing a load.
Namespaced under `C_Item` to match Classic Era 1.15.x.
## ~~27. `IsEquippedItem(item)`~~ — DONE
Shipped as `C_Item.IsEquippedItem` in
[src/item/Equipment.cpp](src/item/Equipment.cpp). Walks equipment
slots 1..19, reads each CGItem's itemID, returns true on first match
against the input (accepts itemID, `item:NNN` link, or chat link).
## ~~28. `C_Item.GetItemCount(itemInfo, [includeBank], [includeUses])`~~ — DONE
Total count of an item across the player's bags (and optionally bank).
Walks bags 0..4 always (live walk via `Item::Location::ResolveBag`).
Stack count read directly from `ITEM_FIELD_STACK_COUNT` at descriptor
+0x20 — verified by decoding `Script_GetContainerItemInfo`
(`0x004F9670`), which does `mov eax, [esi+0x114]; fild [eax+0x20]` for
the count return.
**Bank works cold** — no banker visit required. The 1.12 server sends
bank inventory at login (verified empirically on Turtle WoW: fresh
WoW.exe launch + cleared WDB folder shows GUIDs already populated in
main bank slots 39..62 with the gate at `VAR_BANK_GATE_GUID = 0`).
The engine's `GetItemBySlot` (`0x006228A0`) gates bank slots 39..68
on a non-zero banker-GUID at `0x00BDD038` — set when bank window
opens, cleared when it closes — but the underlying GUID data in
`invMgr+0x04` is always present from session start.
Bank-walk path bypasses the gate by reading GUIDs directly out of
the player invMgr's slot array and resolving each via
`FUN_OBJECT_RESOLVE_BY_GUID = 0x00468460` (same function the engine
itself calls inside `GetItemBySlot`, just without the gate wrapper).
Bank bags (slots 63..68) are followed via the bag's vtable +0x10 to
get its own invMgr, then walked by the same direct-read path. Cold
count of a bank-only item now works from login without ever
approaching a banker — confirmed in-game.
The 1.12 STACK_COUNT field index (0x8) puts it *before* the contained/
creator GUIDs, **opposite** the more commonly documented vanilla
layout (which has STACK_COUNT at index 0xE = +0x38). Trust the
binary: 0x20 is what the engine itself reads, and our test (cross-
checked against a manual `GetContainerItemInfo` walk) confirms it.
`includeUses` reads `ITEM_FIELD_SPELL_CHARGES[0]` (signed dword at
descriptor +0x28) and multiplies each match by `max(abs(charges), 1)`
— so a wand with 50 charges contributes 50 instead of 1, while
non-charge items pass their plain stack count through unchanged. The
offset was derived from the descriptor field-name table builder at
`FUN_0047f840`, which iterates `{ name_ptr, ?, count, ?, ? }` entries
at `0x0083a328` — summing the counts in declaration order puts
SPELL_CHARGES at field index 10 (fields 10..14, +0x28..+0x38).
STACK_COUNT/FLAGS/DURABILITY landing on their known offsets
cross-checks the derivation.
See [src/item/Count.cpp](src/item/Count.cpp).
## ~~29. `C_Item.GetItemFamily(item)`~~ — DONE
Returns the BagFamily bitmask for the item, or `nil` if it isn't in
the cache. Reads `m_bagFamily` at +0x1D0 on the cached `ItemStats_C`
record (offset verified by decoding the engine's own
`GetItemBagFamily(itemID)` helper at `0x005DA050`, which calls
`_GetRecord` then `mov eax, [eax+0x1D0]; ret`).
**Encoding-shift gotcha.** 1.12 stores the raw 1-based BagFamily ID
(`arrow=1, bullet=2, soul shard=3, herb=6, …`); modern WoW (Wrath+)
flipped to the bitmask form `1 << (ID-1)` (`arrow=0x1, bullet=0x2,
soul shard=0x4, herb=0x20, …`). Addons backporting from later
expansions expect the bitmask, so we convert on the way out via
`bitmask = id ? (1 << (id - 1)) : 0`. Verified empirically on Turtle
WoW: Soul Shard (item 6265) reads raw 3 from the cache, returns 4
(`1 << 2`) to Lua callers — matches modern.
**Vanilla data sparsity.** 1.12 server data (at least on Turtle WoW)
populates `m_bagFamily` reliably on **individual loot items** but
leaves it 0 on most **bag containers** themselves. Soul Pouch,
Enchanting Bag, Herb Pouch all return 0 even though their
classification clearly implies a family. Only Light Quiver is
populated among the bags we tested. This means
`GetContainerNumFreeSlots`'s second return is reliable only for
quivers; for general bag categorization, addons should fall back to
checking `(class, subClass)` from `GetItemInfoInstant`. The
`GetItemFamily` *item* path is solid for routing loot to the right
specialty bag.
See [src/item/Info.cpp](src/item/Info.cpp).
## ~~30. `IsSpellKnown(spellID, [isPet])`~~ — DONE
Strict spellbook walk via `Spell::Lookup::FindSpellbookSlot`, filtered
by the requested book type. Returns true only when the spell is in
the player's (or pet's) spellbook UI arrays — does NOT cover talent
passives, profession recipes, or anything else that's "known" but not
displayable as a spellbook button.
### How we caught the bug pre-ship
Initially implemented `IsSpellKnown` using the same bitmap as
`IsPlayerSpell`, on the (wrong) assumption that the two functions
were equivalent in 1.12 since the bitmap was the engine's
authoritative knowledge store. Caught in review — `IsSpellKnown`
is meant to be the stricter check, distinct from `IsPlayerSpell`.
Cross-binary lookup confirmed: 3.3.5's `Script_IsSpellKnown` at
`0x0053C3A0` calls an inner helper at `0x0053B4E0` that does a strict
**spellbook array walk** (`[0x00BE6D88]` for player, `[0x00BE7D98]`
for pet) — not a bitmap. Modern WoW deliberately splits the two
functions: `IsSpellKnown` is the strict "spellbook button" check,
`IsPlayerSpell` (added in 5.0) is the broad "any kind of known"
query. We need both with their respective semantics.
### Behavior table (verified in-game)
| Spell type | `IsPlayerSpell` | `IsSpellKnown` |
|------------------------|-----------------|----------------|
| Trained class ability | true | true |
| Active talent grant | true | true |
| Passive talent | true | **false** |
| Profession recipe | true | **false** |
Same split as modern WoW. The cross-binary technique paid off again
— caught the wrong implementation before it shipped.
See [src/spell/Info.cpp](src/spell/Info.cpp) and the worked example
in [CLAUDE.md](CLAUDE.md#cross-binary-reference--finding-112-implementations-via-newer-clients).
## ~~31. Unit flag bundle: `UnitIsAFK` / `UnitIsDND` / `UnitIsFeignDeath`~~ — DONE
All three shipped in [src/unit/Flags.cpp](src/unit/Flags.cpp):
- **`UnitIsAFK(unit)`** / **`UnitIsDND(unit)`** — read PLAYER_FLAGS at
`[unit + 0xE68] + 0x08`, bits 1 (AFK = `0x02`) and 2 (DND = `0x04`).
Works for any player-controlled unit (local self, target, party,
raid, inspect targets). Gated on `UNIT_FLAG_PLAYER_CONTROLLED` first
to avoid the crash hazard on creatures (where `+0xE68` is uninitialized
garbage).
- **`UnitIsFeignDeath(unit)`** — reads `UNIT_FIELD_FLAGS` bit 29
(`0x20000000`) at `[m_objectFields + 0xA0]`. Verified in-game with
a Hunter using Feign Death — the function returns 1 while the
feign-death buff is active, 0 otherwise.
**Where PLAYER_FLAGS lives — and the misleading first guess.** The
field index `0x8A` (= byte offset `0x228` in m_objectFields) is the
"natural" place to look (matches modern WoW's broadcast UpdateField),
but vanilla 1.12 *doesn't* broadcast PLAYER_FLAGS as a UpdateField —
reading `[descriptor + 0x228]` returns a different field entirely.
The actual storage is in a CGPlayer-side sub-struct at `[unit + 0xE68]`,
shared with the visible-items table at `+0x118`. Verified by
disassembling 1.12's nameplate AFK-prefix renderer at `0x005EC9E0`,
which is the *only* C-level code in stock 1.12 that decorates
nameplates with `<AFK>` — and which works for any unit, contrary to
the initial reading where I thought the JNE went the other way.
**Vanilla nameplate display.** Stock 1.12 shows `<AFK>` over **any**
nearby player's head, not just yourself — the function at `0x005EC9E0`
checks `[unit + 0xE68] + 0x08` bit 1 universally and only special-cases
the local player when a global at `[0x00B6E5CC]` is set (probably a
"hide my own AFK indicator" preference toggle). Verified in-game
on a non-Turtle stock 1.12.1 server.
## ~~32. `IsCurrentSpell(spellID)`~~ — DONE (as `C_Spell.IsCurrentSpell`)
Shipped in [src/spell/IsCurrent.cpp](src/spell/IsCurrent.cpp) under
the modern `C_Spell.IsCurrentSpell(spellIdentifier)` name. Checks
three slots: `VAR_CURRENT_CAST_SPELL` (`0x00CECA88` — cast bar),
`VAR_QUEUED_CAST_SPELL` (`0x00CECAA8` — mid-GCD queue), and the
player's `UNIT_FIELD_CHANNEL_SPELL` (`+0x228` — channels). Accepts
the full spellIdentifier shape (number / link / known-spellbook
name) via `Spell::Arg::ResolveSpellID`.
## 33. `C_Reputation.*` cluster — partial DONE
Modern table-shape and ID-based variants of the existing reputation
API. Most are thin wrappers around what we already have — useful for
addons backporting modern Lua-side code that prefers the C_Reputation
namespace.
- ✅ **`C_Reputation.SetWatchedFactionByID(factionID)`** — DONE.
Calls the engine's inner watched-faction setter at
`FUN_PLAYER_SET_WATCHED_FACTION = 0x004D6240` (`__fastcall(ecx =
factionID) → void`) directly, bypassing
`Script_SetWatchedFactionIndex`'s displayed-index round-trip.
Works for unencountered factions too (the rep bar shows nothing
until the player gains rep, then displays normally). factionID 0
clears. Verified: Darnassus → 72 (Stormwind) → 0 (clear) all
reflected by `GetWatchedFactionInfo()` immediately. Lives in
`src/faction/Info.cpp`.
- **`C_Reputation.SetWatchedFactionByIndex(index)`** — modern alias
for `SetWatchedFactionIndex`. One-line registration that points to
the engine function via our existing wrapper.
- **`C_Reputation.GetFactionDataByIndex(index)`** /
**`GetFactionDataByID(factionID)`** — table-returning variants of
`GetFactionInfo` / `GetFactionInfoByID`. Pack the existing 11-tuple
into named fields (`name`, `description`, `reaction`, `barMin`,
`barMax`, `currentStanding`, `atWarWith`, `canToggleAtWar`,
`isHeader`, `isCollapsed`, `hasRep`, `factionID`).
- **`C_Reputation.GetWatchedFactionData()`** — table form of
`GetWatchedFactionInfo` (which 1.12 has natively). The watched
factionID is stored at `[player + 0xE68] + 0x10C4` per the
inner setter's compare-and-skip path — useful if we add a
`IsWatchedFaction(id)` getter too (engine has one at
`0x004D62F0` already).
## ~~34. `C_DateAndTime.GetSecondsUntilDailyReset()`~~ — DONE (see #76)
Shipped as part of the full `C_DateAndTime.*` backport — see #76.
Uses `86400 - (Time::Server::CurrentEpoch() % 86400)` for server-
midnight semantics.
## ~~35. `GetPlayerInfoByGUID(guid)`~~ — DONE
Modern 7-tuple `localizedClass, englishClass, localizedRace,
englishRace, sex, name, realm` for any GUID the engine has cached.
Implementation in [src/player/Info.cpp](src/player/Info.cpp).
### What we ended up using
The original investigation thought the engine's NameCache at
`0x00CE870C` was the only client-side cache, and that it was fed
only by visible objects (which would mean offline friends/guildies
miss). Re-investigation with Ghidra MCP found a **different** cache
— a dedicated player-info cache at `VAR_PLAYER_NAME_CACHE`
(`0x00C0E228`) with lookup helper `FUN_PLAYER_INFO_LOOKUP`
(`0x0055F080`). This one **is fed by SMSG_NAME_QUERY_RESPONSE**
(opcode `0x51` handler at `0x005551A0`), which the engine
auto-fires for any GUID surfacing in chat / raid / guild / etc.
Cache hits give us name@+0x00, realm@+0x30, race@+0x138,
sex@+0x13C, class@+0x140. Race goes through `ChrRaces.dbc`
records (instance `0x00C0DEE0` / count `0x00C0DEE4`,
`Filename@+0x3C` for englishRace and `Name[locale]@+0x44` for
localizedRace). Class similar via `ChrClasses.dbc`.
Sex value: engine stores 0/1, modern Lua API returns 2/3 — we
add 2 to match.
### Coverage
Anyone who's shown up in chat, your raid/party, your guild, or as
a visible nameplate will be in the cache. Cold-target lookups for
"never seen this character" return `nil`. The earlier-investigated
"Path B" (active CMSG_NAME_QUERY firing for cache misses) wasn't
needed because the existing cache populates from passive traffic
broadly enough that the typical "addon wants info for someone in
chat" case Just Works.
### Refactor side effect
`Race::EnglishRaceForID` and the class-string maps in this module
read from DBCs at runtime rather than hardcoding the strings — so
custom-server race additions (Turtle's Goblin/etc.) are picked up
without code changes.
## ~~36. `GetTalentSpellID(tabIndex, talentIndex[, rank])`~~ — DONE
Bridges the talent system to the spell system: once you have the
spellID, every spell API chains naturally (`GetSpellInfo`,
`C_Spell.GetSpellDescription`, `GameTooltip:SetSpellByID`,
`IsPassiveSpell`, `C_Spell.GetSpellLink`, …). 1.12's `GetTalentInfo`
returns `(name, icon, tier, column, currentRank, maxRank, ...)` — no
spellID — so addons used to have to maintain their own
`(class, tab, idx) → spellID` lookup tables.
Reads from the engine's per-tab talent arrays at `[0x00BDCD28]`
(populated at login from `Talent.dbc` filtered by the player's class),
not Talent.dbc directly. Each `TabInfo *` exposes:
- `+0x00` TalentTab.dbc rowID
- `+0x04` pointsSpent
- `+0x08` numTalents
- `+0x0C` `TalentEntry *` array (stride `0x54`)
Each `TalentEntry`:
- `+0x00` talentID (Talent.dbc primary key)
- `+0x10..+0x33` `SpellRank[9]` (rank-N spellID at index N-1; vanilla
uses 0..4, higher slots stay zero)
When `rank` is omitted, default = player's currentRank, derived by
delegating to `Script_GetTalentInfo` and reading its 5th return —
piggybacking on the engine's spell-knowledge logic. If currentRank is
0, falls back to rank 1.
### Two gotchas worth noting
1. **The engine's currentRank loop walks SpellRank backwards** — `lea
edx, [ebx+0x30]` then `sub ecx, 4` per iteration, ending at +0x10.
I initially read +0x30 as the start of `SpellRank[]`; it's actually
the END (slot 9, always zero in vanilla). Confirmed empirically by
a debug build returning 0 from +0x30 vs the right spellID from
+0x10.
2. **Stock 1.12.1's `GetTalentInfo` returns 8 values, not the 6 I
expected** based on naive disassembly. Reading the 5th return uses
`stack[-(n - 4)]` (dynamic from the actual return count) instead of
a hardcoded `stack[-2]`.
See [src/talent/Info.cpp](src/talent/Info.cpp) and the talent block
(`VAR_TALENT_TAB_*` / `OFF_TABINFO_*` / `OFF_TALENT_SPELL_RANK`) in
[src/Offsets.h](src/Offsets.h).
## ~~37. `GetSpellSchool(spellID)`~~ — DONE
Shipped as [src/spell/School.cpp](src/spell/School.cpp). Returns
`(schoolID, schoolName)` where schoolID is 1-based (1=Physical,
7=Arcane) and schoolName is the locale-independent English name.
### Spell.dbc School field — VERIFIED OFFSET
Vanilla 1.12 stores School as a **0-based integer at record `+0x04`**
(NOT the SchoolMask form the original TODO note speculated — that's
TBC+). Verified empirically via the probe Lua functions:
```
/dump _classicapi_FindSpellField(133, 116, 4, 16) -- mask form: empty
/dump _classicapi_FindSpellField(133, 116, 2, 4) -- 0-based int: offset 4 ✓
/dump _classicapi_FindSpellField(133, 116, 3, 5) -- 1-based int: empty
```
Fireball (133) → School=2 (Fire); Frostbolt (116) → School=4 (Frost).
The probe helpers (`_classicapi_ProbeSpellRecord`,
`_classicapi_FindSpellField`) were temporarily exposed to derive the
offset and removed in the same commit that shipped `GetSpellSchool`.
## ~~38. `GetSpellRadius(spellID)`~~ — DONE
Shipped in [src/spell/Radius.cpp](src/spell/Radius.cpp) as
`C_Spell.GetSpellRadius(spellID)` plus the vanilla-positional
`GetSpellRadius(slot, bookType)`. Returns `(baseRadius, modifiedRadius)`,
or `nil` for non-AOE spells. `modifiedRadius` applies the local player's
talent/item radius mods (e.g. Arctic Reach) via the shared `Spell::Mod`
helper — verified in-game: Frost Nova (10230) → `10, 10` without Arctic
Reach, `10, 12` with rank 2 (+20%).
The radius is **per-effect**, not a single spell-level field: `Spell.dbc`
has `EffectRadiusIndex[3]` at record `+0x160` (verified by decompiling
`FUN_006e6350`, which reads `spellRec[+0x160]`/`[+0x164]` for effects
0/1). Each non-zero index resolves into `SpellRadius.dbc` (records
`0x00C0D7B0`, count `0x00C0D7B4`), record shape
`{ id@+0, radius@+4 (f32), radiusPerLevel@+8 (f32), ... }`. We return the
largest base radius across the three effects. Base radius only — the
engine adds `radiusPerLevel * casterLevel`, but that needs a unit context
and modern `GetSpellRadius` reports the base value.
See `OFF_SPELL_RECORD_EFFECT_RADIUS_INDEX`, `VAR_SPELL_RADIUS_RECORDS`,
`OFF_SPELL_RADIUS_VALUE` in [src/Offsets.h](src/Offsets.h).
## ~~39. `GetFactionParentID(factionID)`~~ — DONE
Reads `Faction.dbc` `ParentFactionID` at record `+0x48` via the
existing `Faction::Info::FactionRecord` helper. Returns `0` for
top-level factions, `nil` for invalid IDs. Verified in-game:
`GetFactionParentID(72)` → 469 (Stormwind → Alliance Forces),
`GetFactionParentID(469)` → 0 (Alliance is top-level),
`GetFactionParentID(99999)` → nil.
See [src/faction/Info.cpp](src/faction/Info.cpp) and
`OFF_FACTION_PARENT_ID` in [src/Offsets.h](src/Offsets.h).
## ~~40. `UnitRaceBase(unit)`~~ — DONE
Shipped as sibling to `UnitClassBase` in
[src/unit/RaceBase.cpp](src/unit/RaceBase.cpp). Reads byte 0 of
`UNIT_FIELD_BYTES_0` (descriptor `+0x78`) and looks up
`ChrRaces.dbc::Filename`. Returns `(raceFile, raceID)`.
## 41. `GetActiveTalentGroup()` / `GetCurrentSpec()` — easy
Vanilla has no formal "spec" system but every class has 3 talent tabs
and the player always invests in one primarily. Returns the
1-based tab index (1, 2, or 3) of the tab with the most points spent,
or `0` if the player has no points spent at all (low-level
characters, or after a respec).
Trivial implementation: walk `GetNumTalentTabs()` (= 3), call
`GetTalentTabInfo(tab)` for each, compare `pointsSpent`. Pick max.
No DBC reads, no engine internals — pure Lua-equivalent computation
that's just easier to call than write inline every time.
Modern WoW's `GetSpecialization()` returns 1..4 for the player's
active spec. This is the closest 1.12 analog, useful for class
addons that want to render different UI per spec ("am I tanking?
healing? DPS?") without having to do the talent-counting dance
themselves.
## ~~42. `GetTalentIDByIndex(tabIndex, talentIndex)`~~ — DONE
Reads `TalentEntry+0x00` from the per-tab talent arrays. The
talentID-at-+0x00 offset was already confirmed empirically during
the GetTalentSpellID debug pass (`entryFirstDword=174` matched
Inner Focus's row ID), so this was a 5-line addition piggybacking
on the existing struct walk. Verified in-game:
`GetTalentIDByIndex(1, 9)` → 174,
`GetTalentIDByIndex(1, 1)` → 166.
Unblocks #43 `GameTooltip:SetTalentByID` whenever someone wants the
modern by-ID tooltip dispatcher.
See [src/talent/Info.cpp](src/talent/Info.cpp).
## ~~43. `GameTooltip:SetTalentByID(talentID)`~~ — DONE
Shipped as [src/talent/Tooltip.cpp](src/talent/Tooltip.cpp). Works
for **any class's** talents, not just the player's. Two-tier
resolution:
1. **Player-class fast path** — walks the local player's TabInfo
arrays for a matching talentID (same arrays #42 reads from,
inverted). On hit, dispatches to `Script_GameTooltip_SetTalent`
(registry slot 34, `0x00535170`) with the resolved `(tab, idx)`.
Renders the full talent tooltip with rank counter, prereqs, and
the "click to learn next rank" prompt.
2. **Cross-class fallback via `Talent.dbc`** — vanilla 1.12 only
loads the local player's class talent data into TabInfo, so
other classes' talents aren't findable in tier 1. Tier 2 looks
up the talent record directly in `Talent.dbc` (records pointer
`0x00C0D6E8`, count `0x00C0D6EC`, indexed by talentID), reads
the rank-1 spellID at `+0x10`, and dispatches the spell tooltip
via the same `Spell::Tooltip::ShowByID` helper that
`SetSpellByID` uses. Renders the spell info (cast time, range,
mana cost, description) without talent-specific decorations
(rank counter, prereq lines).
Modern WoW's cross-class tooltip is slightly richer (talent name +
"Rank 0/N" header before the spell description). Building that
would require Lua-level `GameTooltip:AddLine` work; deferred since
the spell tooltip already answers "what does this talent do?".
### Refactoring done as part of this
Extracted `Spell::Tooltip::ShowByID(L, spellID)` into
[src/spell/Tooltip.h](src/spell/Tooltip.h) so the resolve-self +
`BuildSpellTooltip` chain is shared between
`GameTooltip:SetSpellByID` and the cross-class fallback in
`SetTalentByID`. Saves duplicating the
`FrameScript_PushObject`/`GetObject` inline-asm sequence.
### `Talent.dbc` record layout (verified standard vanilla schema)
| Offset | Field |
|--------|-------|
| `+0x00` | `uint32 ID` |
| `+0x04` | `uint32 TabID` |
| `+0x08` | `uint32 TierID` (row, 0-based) |
| `+0x0C` | `uint32 ColumnIndex` (0-based) |
| `+0x10` | `uint32 SpellRank[0..8]` — rank-1 spellID at `+0x10` |
The per-player `TalentEntry` (in `TabInfo->talents[]`) shares the
same `SpellRank` offset, so we reuse `OFF_TALENT_SPELL_RANK = 0x10`
for both. The `TalentEntry` stride (`0x54`) and the Talent.dbc
record stride differ — Talent.dbc records may be larger — but for
our purpose only the rank-1 spellID at `+0x10` matters.
### Verified in-game
Both tiers tested — own-class talents render the full talent
tooltip, cross-class IDs render the corresponding spell tooltip.
## ~~44. `GameTooltip:SetItemByID(itemID)`~~ — DONE
snprintf the hyperlink string and dispatch to the existing
`Script_GameTooltip_SetHyperlink`. Same registration pattern as
`SetSpellByID`.
### Caching gotcha caught in testing
Initial test showed only the item *name*, not the full tooltip, for
arbitrary itemIDs. Cause: 1.12 lazy-loads item data into the
client-side cache (the same cache `C_Item.GetItemInfoInstant` reads).
Items the player has never encountered show only what's in the link
itself (the name) until the cache is populated via
`SMSG_ITEM_QUERY_SINGLE_RESPONSE`. This isn't a bug in our
implementation — it's the same behavior as modern's `SetItemByID`,
which also requires `C_Item.RequestLoadItemDataByID` first for
arbitrary IDs.
Documented the caveat in [docs/API.md](docs/API.md) with the
recommended `IsItemDataCachedByID` / `RequestLoadItemDataByID` /
`ITEM_DATA_LOAD_RESULT` pattern callers should follow.
See [src/item/Tooltip.cpp](src/item/Tooltip.cpp).
## ~~45. `GameTooltip:SetUnitAura(unit, index, [filter])`~~ — DONE
Pure dispatch wrapper. Branches on filter string (`"HARMFUL"` →
`SetUnitDebuff`, anything else → `SetUnitBuff`) and forwards via
the existing script function. `filter` defaults to helpful when
omitted, matching modern.
See [src/unit/Tooltip.cpp](src/unit/Tooltip.cpp) and the
`FUN_SCRIPT_GAMETOOLTIP_SET_UNIT_*` block in
[src/Offsets.h](src/Offsets.h).
## 46. `GameTooltip:SetFrameStack([showHidden])` — deferred (Lua-side fix in place)
Renders a tooltip listing the chain of frames at the mouse cursor,
sorted by strata + level. The 3.0+ debug-tooling primitive used by
Blizzard's `Blizzard_DebugTools` and every layout-debugging addon.
### Current state in this project
Our bundled `DebugTools/` backport ships its own `FrameStackTooltip`
in [DebugTools/DebugTools.lua](DebugTools/DebugTools.lua), driven
by `_CollectFramesUnderMouse`. As of the EnumerateFrames switch,
the iterator walks the engine's own frame list — fast (typically
~hundreds of entries) and includes anonymous frames the engine
sees but a `_G` walk would miss.
What's still missing relative to the real engine `SetFrameStack`:
- **Anonymous-frame display name.** We currently show
`<anonymous>` for frames where `frame:GetName()` returns nil.
The engine's method shows the frame's pointer + the Lua-side
registry-table address. To get there we'd need a Lua-callable
shim that exposes a numeric handle per frame (vftable + Lua-ref
lookup), which is non-trivial.
- **Single-tooltip semantics.** Modern addons can call
`GameTooltip:SetFrameStack(...)` directly on any tooltip;
ours requires the `FrameStackTooltip` we ship in `DebugTools/`.
Most consumers (`Blizzard_DebugTools` ports, layout addons via
`/framestack`) don't care, but a strict polyfill would.
### C++ port from 3.3.5 — kept as a research note
What `Script_GameTooltip_SetFrameStack`
actually does in 3.3.5 (Frostmourne client, registration entry at
VA 0x00AD2CF0 → function VA 0x00626560 → inner builder
`FUN_006230d0`):
- Pulls cursor (in frame space) via `FUN_0047BFF0` from a render-
state global at `[DAT_00B499A8 + 0x1224 / +0x1228]`.
- Walks an intrusive linked list at `[DAT_00B499A8 + 0xCD4]`. Each
frame node reads:
- `[+0x00]` — vftable; `vftable[+0x10]` = "is the frame visible
enough to hit-test" predicate.
- `[+0x0E0]` (`node[0x38]`) = strata; gates `(strata != 0 ||
showHidden)`.
- `[+0x0D0]..[+0x0DC]` (`node[0x34..0x37]`) = frame rect for
hit-test.
- `[+0x0D8]` (`node[0x36]`) flags, bit 2 → visible.
- `[+0x288]` (`node[0xA2]`) = next pointer.
- Per-frame name via `vftable[+0x04]` (a `GetDebugName()`-style
virtual). If the frame is Lua-side (`vftable[+0x10]` returns
type code 5), an extra `lua_rawgeti(L, REGISTRY, frame->luaRef)`
pulls the Lua-table reference for the `"%s: %p (%s)"` format;
otherwise it's `"%s: %p"`.
- Builds into a scratch sort array at `DAT_00C5D370` (entry stride
`0x410`), `qsort` against comparator `FUN_0061A5B0`.
- Header line via `FUN_00819D40("DEBUG_FRAMESTACK", ...)` (Lua
`GetGlobalString`) then per-entry `FUN_0061FEC0` (tooltip
`AddLine` equivalent, takes color codes from a 4-byte-stride
table at `0xAD2DC0` / `0xAD2DB8` / `0xAD2DB0` for
visible/hidden/special states).
For a 1.12 port we'd need to derive:
- The frame-manager global (3.3.5's `DAT_00B499A8` — different VA
in 1.12, different field offsets likely).
- Frame struct offsets for rect, strata, flags, next, name vftable
slot — the layout shifted between 1.12 and 3.3.5 (same way unit
field offsets did, per the `OFF_UNIT_FIELD_HEALTH` discovery in
CLAUDE.md).
- AddTooltipLine engine address (1.12 has it — every
`GameTooltip:SetX` method calls it internally).
- Lua-side reference lookup helper (whatever 1.12 uses to map
frame → Lua table; the `FrameScript_GetObject` chain at
`0x6F3740` is part of this).
### Recommendation
The Lua-side iterator switch is done. The C++ port stays deferred
unless we need the engine frame list for something else
(`GetMouseFocus` polyfill, anonymous-frame inspector with extra
fields beyond what Lua exposes, single-tooltip strict polyfill,
etc.) that would amortize the RE cost.
## ~~47. `IsPlayerSpell(spellID)`~~ — DONE
Single bitmap lookup at `[VAR_PLAYER_SPELL_BITMAP] = [0x00B710FC]`.
The engine maintains a dword bitmap with one bit per spellID — set
when the player learns a spell (any source: training, talent
investment, profession recipe, racial unlock, etc.) and cleared on
unlearn. We just consult the same bit the engine itself reads via
the helper at `0x0060C740`:
```cpp
return (bitmap[spellID >> 5] & (1 << (spellID & 31))) != 0;
```
### How we found it
The naive walk-based implementation (originally drafted) failed for
profession recipes — turns out vanilla 1.12's `VAR_PLAYER_SPELLBOOK`
arrays DON'T contain profession recipe spellIDs (verified
empirically: a tailor with Bolt of Linen Cloth fails
`FindSpellBookSlotByID(2963)`). Surfaced during in-game testing.
To confirm whether 1.12 had a unified spell-knowledge data structure,
I dumped 5.4.8's `Script_IsPlayerSpell` (5.4 = the version where the
function was first added) and saw a clean bitmap pattern:
```
mov ecx, eax
and ecx, 0x1F ; bitPos = spellID & 31
shl edx, cl ; mask = 1 << bitPos
mov ecx, [imm32] ; bitmap base ptr
shr eax, 5 ; idx = spellID / 32
and eax, [ecx + eax*4] ; bitmap[idx] & mask
```
Searched 1.12 for the same pattern → matched at the helper
`0x0060C740`, which `Script_GetTalentInfo` calls for currentRank
derivation. Same shape, same purpose, just at a different bitmap
address (`[0x00B710FC]`).
### Modern-parity semantics
Verified against 1.15.x: only the player's currentRank spellID has
its bit set; lower-rank IDs return false. A 5/5 Unbreakable Will
player sees `IsPlayerSpell(14791)` (rank 5) = true but rank 4 / 3 /
2 / 1 = false — same in 1.12 with our implementation, same in 1.15.
This means our implementation matches modern exactly, including the
"only current rank counts" quirk. Addons backporting from later
expansions that key on currentRank's spellID work unmodified.
### Spillover wins for the rest of TODO
The same bitmap makes #30 `IsSpellKnown(spellID, isPet)` trivial —
ship it as a thin wrapper using the same lookup (or split: player
scan via bitmap, pet via existing pet spellbook walk). The
`Spell::Lookup::FindSpellbookSlot` walk is now only needed for the
slot-and-bookType return shape, not for knowledge queries.
See [src/spell/Info.cpp](src/spell/Info.cpp) and
`VAR_PLAYER_SPELL_BITMAP` in [src/Offsets.h](src/Offsets.h).
## ~~48. `GetSpellCooldown(spellID)` overload~~ — DONE (via `C_Spell.GetSpellCooldown`)
Shipped as the modern table-shape variant in
[src/spell/Cooldown.cpp](src/spell/Cooldown.cpp): `C_Spell.GetSpellCooldown(spellIdentifier)`
accepts number / name / name(rank) / `|Hspell:N|h` link and returns
a `SpellCooldownInfo` table. The original goal — "query cooldowns by
spellID without forcing the caller to resolve a spellbook slot first"
— is covered.
Reads the engine's per-spell cooldown manager at
`FUN_SPELL_QUERY_COOLDOWN` (`0x006E2EA0`), which `Script_GetSpellCooldown`
also goes through internally after its slot-resolution step. Fixed
the `(*outDuration, *outStart)` argument order while doing this —
the typedef in `Spell::Usable` had them reversed (worked anyway
because both fields are 0 off-cooldown, but the var names were
backward).
## ~~49. `IsUsableSpell(spell)` / `C_Spell.IsSpellUsable(spellID)`~~ — DONE
Both shipped. `IsUsableSpell` accepts spellID or `(slot, bookType)`
via the same `Spell::Lookup::SpellbookSlotToID` resolver other
spell-API functions use. Returns `(1, nil)` / `(nil, 1)` /
`(nil, nil)` per legacy convention. `C_Spell.IsSpellUsable` is the
modern shape — same logic, returns proper booleans.
**Reworked for issue #51 (2026-09-12) — it now IS the engine's
verdict.** `IsUsableAction` reads the per-slot cache
(`0x00BC6B60` usable / `0x00BC67A0` noMana, reader `FUN_004E5230`),
which the recompute `FUN_004E5050` fills per slot. For a player spell
slot that recompute is one call: `FUN_SPELL_IS_USABLE(record,
&noMana)` (`0x006E3D60`). For a pet spell slot it is `FUN_PET_ACTIONS_
USABLE()` then the pet's power vs `FUN_GET_SPELL_COST(spellID, 0)`.
`Spell::Usable` now runs exactly those two paths live (plus a
knowledge gate on `VAR_PLAYER_SPELL_BITMAP`, since the helper is also
fed item on-use spells and never checks knowledge). Verified check
list of the helper is on `FUN_SPELL_IS_USABLE` in `Offsets.h`.
**The first version hand-rolled five checks instead** (known, alive,
off cooldown, power, reagents) and diverged from `IsUsableAction`
exactly where the helper does more or less — the issue #51 repro
(Warrior, Whirlwind):
| State | `IsUsableAction` | old `IsUsableSpell` |
|---|---|---|
| Berserker, 0 rage, on CD | `nil, 1` | `nil, nil` (we tested cooldown first — the engine never does) |
| Battle Stance, 25 rage | `nil, nil` | `1, nil` (we never tested stance) |
Cooldown is deliberately NOT part of usability: FrameXML greys
(`IsUsableAction`) and swipes (`GetActionCooldown`) as two separate
states, and the engine helper has no cooldown branch. Rule #1 case:
`Item::Usable` had been calling the helper all along.
**Two engine-cache approaches investigated and discarded before the
first version** (still true, kept for the record):
1. **Per-spell cache at `0x004F0F40` returning fields at +0x564
/ +0x568** — initially looked promising (the action-bar
dispatcher at `0x004E5BA0` reads these), but the writers
(`0x004EFF17` cluster) showed they're parsed config integers,
not real-time usability bools. False trail. (Later identified as
the macro entry's cached primary spell — see the `#showtooltip`
notes.)
2. **Action-bar per-slot caches at `0x00BC67A0` (noMana) and
`0x00BC6B60` (usable)** — these ARE real-time, but only updated
for the 120 action-bar slots. Spells off the bar stay
uninitialized. Action-bar-only is the wrong abstraction since
modern `IsUsableSpell(spellID)` is action-bar-agnostic. The fix
above sidesteps this by calling what FILLS the cache, not the
cache.
**Important offset correction along the way.** Initial implementation
read POWER1 at descriptor `+0x5C` based on the CMaNGOS-documented
field index `0x17`. That was *max* mana — current was at `+0x44`
(field index `0x11`, six fields earlier than the standard layout).
The whole UNIT_FIELD layout in 1.12.1 is shifted 0x18 / 6 fields
earlier than CMaNGOS documents:
| Field | CMaNGOS docs | 1.12.1 actual |
|---------------|-------------:|--------------:|
| HEALTH | +0x58 | +0x40 |
| POWER1 (mana) | +0x5C | +0x44 |
| POWER2..5 | +0x60..+0x6C | +0x48..+0x54 |
| MAXHEALTH | +0x70 | +0x58 |
| MAXPOWER1..5 | +0x74..+0x80 | +0x5C..+0x6C |
| LEVEL | +0x88 | +0x70 |
| FLAGS | +0xA0 | +0xA0 ✓ |
FLAGS still lands at +0xA0 (verified separately by
`Script_UnitPlayerControlled` and `Script_UnitAffectingCombat`).
Trust the binary, verify with `_classicapi_DescDump` if you need
to derive new ones.
See [src/spell/Usable.cpp](src/spell/Usable.cpp).
## 50. Cross-binary technique applications worth picking up — meta
The `IsPlayerSpell` discovery proved out the cross-binary disassembly
technique (documented in [CLAUDE.md](CLAUDE.md#cross-binary-reference--finding-112-implementations-via-newer-clients)).
Other pending TODOs that look like good fits for the same approach:
- **#7 `UnitAuraBySlot` / `UnitAuraSlots`** — modern slot-based aura
iteration. Aura state is in CGUnit's UpdateField data; modern
`UnitAura` reads slot offsets we can decode from 5.4.8 and use in
1.12.
- **#32 `IsCurrentSpell(spellID)`** — runtime cast-state global. The
engine has a "currently casting spellID" global (the cast-bar UI
reads it). Modern's `IsCurrentSpell` reads the same value.
- **#42 `GetTalentIDByIndex`** — already easy with the talent struct
we now know (talentID at TalentEntry+0x00); cross-binary not needed
here but could verify against 5.4.8's `GetTalentInfoByID` for
semantics.
Tag here so we remember the technique exists when picking up these
items.
## ~~51. `C_Container.GetContainerNumFreeSlots(bagID)`~~ — DONE
Returns `(numberOfFreeSlots, bagType)` for the player's backpack
(`bagID = 0`) or one of the four equipped bag slots (`bagID = 1..4`).
`bagType` is the BagFamily bitfield — vanilla 1.12 has only three
non-zero families (quiver=1, ammo pouch=2, soul shard bag=4); modern
expansions added 20+ more, but reading the bitfield gives addons a
forward-compatible shape regardless. Always returns two values, falling
back to `(0, 0)` for unsupported bag IDs (bank/keyring/out-of-range) —
matches 3.3.5's behavior.
Implementation walks the bag and counts empties via
`Item::Location::ResolveBag`. Bag metadata (slot count + BagFamily) for
real bags 1..4 comes from the equipped bag's `ItemStats_C` cache
record: `m_containerSlots` at +0x64, `m_bagFamily` at +0x1D0. Backpack
short-circuits to `(16, 0)` since vanilla's main backpack is fixed-size
and unfamilied. Field offsets derived from VanillaHelpers's
`struct ItemStats_C` layout, cross-checked against the existing
`m_stackable` at +0x60 (already in `Offsets.h`).
The slot-walk uses ResolveBag, which clobbers Lua stack[1]/[2] each
call (a requirement of the engine's `PackBagSlot`). That's safe here —
we own the stack inside the callback and the user's bagID arg is
copied to a local before the loop. Cross-checked in-game against a
manual `GetContainerItemID` walk; counts match for all five bags.
**bagType return is sparse on vanilla data.** Empirically, only Light
Quiver carries a non-zero `m_bagFamily` field among the bags we tested
on Turtle WoW; Soul Pouch, Enchanting Bag, Herb Pouch all return 0.
The same field on individual items (arrows, shards, herbs) is
reliable — see TODO #29's notes. Addons that need bag-category
discrimination should look at `(class, subClass)` from
`GetItemInfoInstant` rather than `bagType`. The conversion from
1.12's raw-ID encoding to the modern bitmask
(`1 << (ID-1)`) still applies for the rare populated cases.
See [src/item/Bag.cpp](src/item/Bag.cpp).
## ~~52. `C_Container.PlayerHasHearthstone()` / `C_Container.UseHearthstone()`~~ — DONE
Modern convenience pair for the most-used bag walk in addons. Walks
bags 0..4 looking for the hearthstone (vanilla itemID 6948 — the only
one in 1.12; modern WoW recognizes many hearthstone-toy itemIDs but
none exist in this client). Stops on first match.
`PlayerHasHearthstone()` returns the itemID (always 6948 or nil).
`UseHearthstone()` invokes the engine's `Script_UseContainerItem`
(`0x004FA0E0`) with `(bagID, slot)` set up on the Lua stack — same
secure-action path a regular `UseContainerItem(bag, slot)` Lua call
would take, so cooldown / combat / movement-cancel handling is
identical. Returns `true` if a hearthstone was found and the call
dispatched, `false` otherwise (the cast itself can still fail
downstream — same caveat as manually calling `UseContainerItem`).
Walking helper is shared between the two via `FindHearthstone(L,
*outBag, *outSlot)`. Slot counts come from delegating to the engine's
own `Script_GetContainerNumSlots` (`0x004F9560`) rather than a
hardcoded vanilla cap, so custom servers with larger-than-24-slot
bags work without code changes.
See [src/item/Hearthstone.cpp](src/item/Hearthstone.cpp).
## ~~53. `LE_EXPANSION_*` constants~~ — DONE
Twelve expansion-level enum globals (`LE_EXPANSION_CLASSIC` through
`LE_EXPANSION_MIDNIGHT`) plus `LE_EXPANSION_LEVEL_CURRENT`, all
matching the canonical retail `Enum.ExpansionLevel` table values.
On 1.12, `LE_EXPANSION_LEVEL_CURRENT` resolves to
`LE_EXPANSION_CLASSIC` (= 0). Lets addons backported from later
expansions use the modern `if LE_EXPANSION_LEVEL_CURRENT < ...`
gating idiom without conditionally defining the constants
themselves.
Set via the same Lua C API path `CLASSIC_API_VERSION` uses (no
`FrameScript_Execute` source). One per entry, written to
`_G[name] = value` from the module's `RegisterLuaFunctions` hook
which fires after the engine's `LoadScriptFunctions` boot phase.
See [src/expansion/Constants.cpp](src/expansion/Constants.cpp).
## ~~54. `C_AddOns.*` namespace — convenience wrappers~~ — DONE (Tier 2)
Modern WoW (10.x) moved most addon API into the `C_AddOns` namespace.
1.12 already exposes most of the underlying functions as globals;
we deliberately do *not* duplicate them under `C_AddOns` (Tier 1 in
the prior version of this entry — pure namespace mirror, low value).
What's worth adding is the post-vanilla *new* functionality.
### Tier 1 — DROPPED
Bulk wrapping of 17 existing 1.12 globals (`IsAddOnLoaded`,
`LoadAddOn`, etc.) under `C_AddOns.*`. Skipped — addons that need
the namespace can `C_AddOns = C_AddOns or {} ; C_AddOns.IsAddOnLoaded
= IsAddOnLoaded` themselves in two lines.
### ~~Tier 2 — convenience wrappers around `GetAddOnInfo`~~ — DONE
Shipped as `src/addons/Info.cpp`. Six wrappers, all bypassing
`Script_GetAddOnInfo` and reading directly from the engine's
addon-registry helpers we found at `0x0051DF00..0x0051E050`:
- `C_AddOns.GetAddOnName(indexOrName)` — direct via `GetByIndex`
(numeric: returns the entry's inline name buffer; string:
echoes the input after validating existence).
- `C_AddOns.GetAddOnTitle(indexOrName)` — calls
`GetTitleByName` (`0x0051DF20`) directly.
- `C_AddOns.GetAddOnNotes(indexOrName)` — calls
`GetNotesByName` (`0x0051E050`) directly.
- `C_AddOns.IsAddOnLoadable(arg [, character, demandLoaded])` —
returns `(loadable, reason)`. Still dispatches through
`Script_GetAddOnInfo` (5th + 6th return) because the engine's
per-field accessor is buried behind a locale-derived field key.
Gated on a `ResolveAddOnName` existence check first to avoid
the `lua_error` `Script_GetAddOnInfo` raises for out-of-range
numeric indices.
- `C_AddOns.GetAddOnSecurity(indexOrName)` — same dispatch
shape as `IsAddOnLoadable`.
- `C_AddOns.DoesAddOnExist(indexOrName)` — direct via
`ResolveAddOnName`; correctly returns `false` for unknown
names rather than the dispatch-based heuristic which
false-positived on garbage strings (engine echoes the input
back as ret1 even on miss).
The underlying `FUN_ADDON_GET_BY_INDEX` / `_TITLE_BY_NAME` /
`_NOTES_BY_NAME` accessors share a hash-table walk: they take a
char* name (entry pointer doubles as a name string thanks to
the inline 12-byte buffer), hash it to find the registry entry,
then walk a per-entry metadata hash table keyed by the field
name (`"Title"`, `"Notes"`) to extract the value. We piggyback
on the same name → entry lookup for all wrappers.
Notable bug caught in testing: the original implementation used
`PushValue` + `Insert(L, 1)` + `SetTop(L, 1)` to pull the
desired return down to the bottom of the stack. That combo
silently returned the LAST pushed value of `Script_GetAddOnInfo`
regardless of `returnPos` — same family of broken-stack-state
issues as the `RegisterTableFunction` gotcha in CLAUDE.md.
Replacing with `SetTop(L, 1 + returnPos)` (truncate to keep
the desired return on top, return 1 to Lua) fixed it.
### Tier 3 — research / new work
- **`GetAddOnInterfaceVersion(index)`** — reads `## Interface:` from
the .toc. The engine parses this at addon-load time; we'd need
to find where it stores the per-addon value. (Note: vanilla also
exposes `GetAddOnMetadata(name, "Interface")` natively, which
may already cover this — verify before implementing.)
- **`GetAddOnLocalTable(index)`** — NOT FEASIBLE in 1.12. The
modern API returns the addon's private namespace passed as the
second `...` arg to each addon file (`local name, addon = ...`).
Verified empirically: vanilla 1.12 calls `lua_pcall(L, 0, 0, -2)`
on every addon chunk — `nargs = 0`, so `...` is always empty.
Confirmed at four pcall sites in the addon-loader region
(0x704B68, 0x704D22, 0x704E79, 0x705199), all with the same
`xor edx, edx; mov ecx, L; call lua_pcall` pattern. The
convention was added in 3.0+ when WoW moved to Lua 5.1; the
underlying engine machinery (per-addon table allocation,
vararg injection) doesn't exist in 1.12. Adding it would
require hooking the pcall sites to inject args AND maintaining
a per-addon-name table map ourselves — a feature add, not just
an API exposure. Skip unless an addon explicitly needs it.
- **`DoesAddOnHaveLoadError(index)`** — load-error tracking. May
not exist in 1.12 in a queryable form.
- **`IsAddOnDefaultEnabled(index)`** — initial-enabled state from
the .toc `## DefaultState:` tag (not in 1.12 .toc syntax).
### Skip
- `GetScriptsDisallowedForBeta` — beta-specific; no 1.12 analogue.
### Why this is worth doing
Almost every modern addon released in the last few years uses
`C_AddOns.IsAddOnLoaded` instead of the global. Backporting an
arbitrary modern addon to 1.12 currently means find/replace
across the codebase. Tier 1 alone (one afternoon) makes that
unnecessary for the most common 17 entry points.
### Investigation findings — direct AddOnInfo struct reads (deferred)
**Goal:** make Tier 2 convenience wrappers (GetAddOnName/Title/
Notes/Loadable/Security/DoesAddOnExist) read directly from the
engine's per-addon struct instead of dispatching to
`Script_GetAddOnInfo` and discarding 6 of 7 returns. **Status:
deferred** — struct layout is more complex than a clean inline-
string packing, and time-to-derive exceeds the perf upside for
the typical caller.
**What we learned:**
- Addon **array** lives at `[0x00BE1B94]` (pointer to array of
4-byte pointers) and **count** at `[0x00BE1B90]`. Confirmed
via `Script_GetAddOnInfo` disassembly: lookup is
`if (idx >= [0x00BE1B90]) return null; return ((void**)
[0x00BE1B94])[idx];`.
- Each entry points to a per-addon struct (heap-allocated, sized
per-addon).
- **Struct fields we identified (relative to struct base):**
| Offset | Content |
|-------------|---------------------------------------------------|
| `+0x00..+0x0B` | Name buffer — inline, 12 bytes, null-terminated. Both 8-char "Atlas-TW" and 9-char "aux-addon" fit. |
| `+0x0C` | Heap pointer (Storm allocator addr like `0x29B4D908`) **OR** null. Non-null for Atlas-TW; null for aux-addon. Derefs to non-printable bytes — likely a struct/array, not a direct string. |
| `+0x10..+0x17` | Often zeros across multiple addons. |
| `+0x18` | Constant `0x909` across all addons probed. Format/version marker? |
| `+0x1C` | Constant `5` across all addons probed. Schema version? |
| `+0x20+` | Variable — for shorter addons this is unrelated adjacent heap memory (saw "ItemSync" appear once and "Notes" appear in another session for aux-addon, both clearly not part of aux-addon's data). |
- **Title and Notes are NOT inline-packed** at the start of the
struct as I initially hypothesized. Atlas-TW's actual title is
`"Atlas-TW"` (matches name) and notes is the long
`"Atlas-TW: instance Map Browser..."` string. Neither appears
in the first 0x60 bytes of the struct except where the inline
*name* field happens to look like the title.
- **The pointer at `+0x0C`** is the most likely indirection to
the title/notes data, but it points to a binary blob (non-
ASCII first bytes), suggesting another layer of indirection
(struct of pointers, or a tagged section list). Would require
a second-level scan to chase.
- **Engine helper functions** for field extraction live around
`0x0051DF00`–`0x0051E0xx` (LookupByIndex, GetTitle, GetNotes,
etc.), reachable via call-target arithmetic from
`Script_GetAddOnInfo`. Initial decoding was confused by
off-by-one arithmetic on my part — the targets land on what
appear to be mid-instruction addresses, suggesting the
helpers may use non-standard prologues or are tail-call
thunks. Worth tracing more carefully.
- **Diagnostic that worked:** `_classicapi_AddonStructDump(idx)`
with SEH-wrapped pointer deref (the bare pointer-deref
approach crashes with `0xC0000005` when interpreting inline
string bytes as pointers — `"s-TW"` happened to fall in
`0x10000000..0xF0000000` range and AVed). The
`SafeReadAsciiString` helper using `__try`/`__except` is the
pattern to keep if we resume this work.
**Recommended next step** if revisiting: extend the diagnostic
to recursively chase the `+0x0C` pointer (read 32 bytes there,
check if any look like further string pointers), and trace
1.12's `Script_GetAddOnMetadata` (`0x0048E530`) which is more
self-contained than `GetAddOnInfo` and might reveal a cleaner
field-access pattern.
Tier 3 (interface version, addon local table, etc.) still
deferred — none of those have a proven 1.12 storage location.
## ~~55. `IsMounted` / `IsStealthed` / `IsFalling` / `IsSwimming`~~ — DONE
Shipped as `src/unit/State.cpp`. Modern globals that 1.12
doesn't bind to Lua, despite the underlying state being tracked
by the engine. All four read directly off the local player
struct or its descriptor — no dispatch:
- `IsMounted()` — checks `UNIT_FIELD_MOUNTDISPLAYID` at
descriptor `+0x1FC`. Non-zero means the engine is rendering
a mount.
- `IsStealthed()` — checks bit `0x02` of the player visibility
byte at descriptor `+0x17C`, AND-gated with `MountDisplayID
== 0` (mount also sets that bit). May false-positive on
shapeshift/possess/etc. — untested, fix by walking the
player's aura list looking for the actual stealth/prowl
spell if it turns up in practice.
- `IsFalling()` — checks `MOVEFLAG_FALLING | MOVEFLAG_FALLING_FAR`
(`0x2000 | 0x4000`) on the local player's movement-flags u32
at `+0x9E8`. This is client-side state (outbound MSG_MOVE_*
data), not broadcast — only meaningful for the local player.
- `IsSwimming()` — same movement-flags word, `MOVEFLAG_SWIMMING`
(`0x200000`).
### How we found the offsets
A general-purpose probe system in `src/debug/` (Probe.cpp +
Log.cpp + Log.h) writes labeled descriptor / player-object
snapshots to `<WoW dir>\Logs\classicapi_debug.log` (alongside
the engine's `FrameXML.log`, `Sound.log`, etc.). Path is
resolved at runtime via `GetModuleFileNameA(nullptr)` so the
DLL works against any client install. User runs
`_classicapi_DescLog("baseline", 0, 0x100)` then
`_classicapi_DescLog("mounted", 0, 0x100)` etc.; agent reads
the log file directly and diffs.
Findings:
- **MountDisplayID** found by diffing baseline vs mounted
descriptor — only `+0x1FC` changed from 0 to a creature
display ID like `0x4306`.
- **Stealth bit** found by diffing baseline vs stealthed —
`+0x17C` byte 0 went `0 → 0x02`. Mounted state went
`0 → 0x1A` (= bits 1, 3, 4). Bit 1 is shared, bits 3+4
are mount-specific.
- **Movement flags** found by diffing standing/swimming/falling
player-object dumps. `+0x9E8` went `0 → 0x200000` (swimming)
and `0 → 0xE001` (falling: bits 0x1 FORWARD + 0x2000 FALLING
+ 0x4000 FALLING_FAR + 0x8000 PENDING_STOP). Bit values
match documented vanilla `MOVEFLAG_*` constants exactly.
The probe helpers (`_classicapi_DescDump`, `_classicapi_PlayerDump`,
`_classicapi_DescLog`, `_classicapi_PlayerLog`,
`_classicapi_LogClear`, `_classicapi_LogAppend`,
`_classicapi_LogPrintf`, `_classicapi_HexDump`) are kept in
the build as a reusable offset-finding scaffold. They write
labeled blocks to `<WoW dir>\Logs\classicapi_debug.log`,
sharing the location convention engine logs and other
injected DLLs (nampower, etc.) use. Path is computed at
runtime — no hardcoded install location.
The C++ `Debug::Log` API (in `src/debug/Log.h`) backs the
Lua bindings and is available to any module via
`#include "debug/Log.h"`:
- `Debug::Log::Clear()` — truncate the file.
- `Debug::Log::Append(label, content)` — labeled block, content
written verbatim. Best for snapshot diffs.
- `Debug::Log::Printf(fmt, ...)` — printf-style one-line trace.
Auto-newlines if the caller didn't include one.
- `Debug::Log::HexDump(label, ptr, len, [base])` — xxd-style
hex+ASCII dump of a memory range, 16 bytes per row, with
the offset column showing `base + i`. SEH-wrapped: if a row
faults (page boundary, freed memory) the dump stops cleanly
and notes the failed offset rather than crashing the host.
`HexDump` is the most useful for arbitrary-VA inspection — call
it on a struct pointer to scan layouts, or from Lua via
`_classicapi_HexDump(label, addr, len)` to inspect engine
globals without a per-investigation probe module.
## ~~56. `OffhandHasWeapon()`~~ — DONE
Shipped as `src/item/Equipment.cpp`. Resolves the off-hand
equipment slot (slot 17) via `Item::Location::ResolveEquipmentSlot`,
reads the cached `ItemStats_C` record's `m_inventoryType` at
`+0x2C`, and returns true iff it's `INVTYPE_WEAPON` (13) or
`INVTYPE_WEAPONOFFHAND` (22). Shields, holdables (tomes/orbs),
empty slots, and uncached items all return false.
No async load is fired — modern API behavior matches; if the
off-hand item isn't cached the function silently returns false
until something else warms the cache. Typically only matters on
first login before the player's own gear is in the cache, which
in practice is loaded eagerly anyway.
## 57. `IsFlying()` — TESTED, DROPPED
Modern `IsFlying()` returns true when on a flying mount. Vanilla
1.12 has no flying mounts, so the closest semantic mapping is
"on a flightpath" (i.e., `UnitOnTaxi("player") == 1`).
Initial implementation tested `MOVEFLAG_FLYING = 0x01000000` on
the local movement-flags word at `[CGPlayer + 0x9E8]`. The bit
is documented in CMaNGOS as `MOVEMENTFLAG_FLYING`, but verified
empirically that 1.12 does NOT set it during taxi flights —
`/dump IsFlying()` stayed false through an entire flightpath
on which `/dump UnitOnTaxi("player")` correctly returned 1.
Vanilla taxi rides are server-driven splines that animate the
mount/character without flipping a local movement-flag bit;
the FLYING bit only ever gets set on flying mounts (which
don't exist) or possibly GM fly mode (untested). Bit 0x01000000
in vanilla may instead be `MOVEMENTFLAG_SPLINE_ENABLED` per
some references, but if so, that bit also stays clear during
normal taxi.
Conclusion: there is no useful interpretation of `IsFlying()`
in vanilla. `UnitOnTaxi("player")` covers the only flight-like
state the client tracks. Function and `MOVEFLAG_FLYING`
constant both removed; `Offsets.h` carries a comment noting
the empirical result so this doesn't get re-attempted.
## ~~58. `FillLocalizedClassList(table [, isFemale])`~~ — DONE
Shipped as `src/classes/Info.cpp`. Iterates `ChrClasses.dbc`
records and writes `tbl[classToken] = localizedClassName` for
each, returning the same table for chaining.
ChrClasses record layout (derived from `Script_GetSelectedClass`
at `0x004716E0`):
- `+0x14` — `char *Name[9]` localized class names (one per locale)
- `+0x38` — `char *Filename` class token (`"WARRIOR"`, `"MAGE"`, etc.)
Vanilla 1.12 has no separate female-name array — `Name[9]` is
exactly the 36 bytes between `+0x14` and `+0x38` (= 9 locales × 4
byte ptr), with the token immediately after. The modern
`isFemale` arg is accepted for signature parity but ignored;
same names returned regardless. Most locales (English included)
don't differentiate gender forms anyway, so callers won't typically
notice. Sparse classIDs (vanilla skips classID 6 — Death Knight
didn't exist) have NULL records and are silently skipped.
Stack discipline: takes the table at idx 1, drops any extra args
via `SetTop(L, 1)`, then loops `PushString(token); PushString(name);
SetTable(L, 1)` per record. `SetTable` consumes both stack values
so the table sits alone at idx 1 throughout the loop. Returns 1
to push the (same) table back to Lua.
## ~~59. `C_Item.EquipItemByName` cursor-free path~~ — DONE
The current implementation in
[src/item/Equipment.cpp](src/item/Equipment.cpp) is a cursor-state
guard: refuses to operate when `CursorHasItem()` is true. Modern
WoW's `EquipItemByName` silently preserves the cursor by routing
through an engine-internal "swap by GUID" helper. With Ghidra on
the right binary we found that helper.
### The primitive: `FUN_005E0C40`
`Script_EquipCursorItem` at `0x00489660` calls `FUN_005E0C40` —
the engine's own swap-and-send function. Signature decoded by
reading the call site and the function body:
```c
void __thiscall FUN_005E0C40(
CGPlayer *this,
u32 srcItemGuidLo, u32 srcItemGuidHi,
u32 srcContainerGuidLo, u32 srcContainerGuidHi,
u32 srcLinearSlot,
u32 dstContainerGuidLo, u32 dstContainerGuidHi,
u32 dstLinearSlot,
int flag); // 0 = normal path
```
Internal behavior:
1. Validates source/dest containers (player invMgr vs CGContainer
bag) — looks up `FUN_00468460` to resolve container by GUID.
2. Picks the opcode based on swap type:
- **`0x10D` (`CMSG_SWAP_INV_ITEM`)** — same-container swap.
Payload `{src_slot, dst_slot}`. Used when both src and dst
resolve to the player's direct invMgr.
- **`0x10C` (`CMSG_AUTOEQUIP_ITEM`)** — cross-container swap.
Payload `{dst_bag, dst_slot, src_bag, src_slot}`. Used when
src or dst is in a CGContainer (equipped bag).
3. Writes the packet via `FUN_00418190(opcode)` + `FUN_00418070(byte)…`
into the same buffer at `PTR_LAB_007FF9E4` that every real
network packet flows through.
4. Sends via `FUN_005AB630` — **the actual send call the previous
investigation couldn't find**.
### Why this bypasses the cursor
`Script_EquipCursorItem` reads cursor state via `FUN_00494C80`
before passing it to `FUN_005E0C40`, but `FUN_005E0C40` itself
neither reads nor writes the cursor globals at `[0xBE0810]` /
`[0xBE0814]`. The dead-code packet builder at `0x005E0B50` was
unrelated; the real production path is just `FUN_005E0C40`. We
hand it the right args and it sends the packet — no cursor touch.
The previously-identified gate at `0x501130` was the **right-click
"use item from cursor"** path (opcode `0x276`), not the swap path.
Different concern entirely.
### Linear-slot encoding
The engine's linear slot:
| Linear slot | Container | What |
|---:|---|---|
| `0..18` | player invMgr | paperdoll slots 1..19 (subtract 1 from Lua slot) |
| `19..22` | player invMgr | equipped bag containers (bag IDs 1..4) |
| `23..38` | player invMgr | backpack (bag ID 0) contents, 1-based slot S → linear = 22+S |
| `0..N-1` | bag CGContainer | slot inside the bag (subtract 1 from Lua slot) |
For destination paperdoll equip: `dstContainer = player`, `dstSlot = paperdollSlot - 1`.
For source:
- Item in paperdoll slot N → `srcContainer = player`, `srcSlot = N - 1`
- Item in backpack slot S (bagID 0) → `srcContainer = player`, `srcSlot = 22 + S`
- Item in equipped bag B (bagID 1..4) slot S → `srcContainer = bag GUID`,
`srcSlot = S - 1`. Bag GUID read off its CGItem instance block at `+0x8`.
### Risk assessment
The previous TODO worried about hand-built packets disconnecting
the client. **We never build a packet** — we hand off high-level
args and the engine's own builder/sender runs verbatim. Same code
path drag-and-drop equip uses. Only risk is bad GUIDs / slot
indices, validated client-side before the call.
### Cross-reference
2.4.3 has `ItemMgr::EquipByGUID` at `0x5E8310` (`__thiscall(this=invMgr,
guidLo, guidHi, dstSlot, 0)`) which bundles find-by-GUID + swap.
1.12's equivalent is split: find-by-GUID is our existing
`Item::Location::FindByGUID` + `Locations::FindGUID`, swap is
`FUN_005E0C40`.
### Implementation plan
[src/item/Equipment.cpp](src/item/Equipment.cpp) `Script_C_Item_EquipItemByName`:
1. Find the item by name (existing `FindItemInBags`).
2. Resolve source location via the table above → `(containerGuid, linearSlot)`.
3. Compute target paperdoll slot (explicit arg, or auto-pick from
`m_inventoryType` for the no-slot form).
4. Read player GUID off the CGPlayer instance block at `+0x8`.
5. Call `FUN_005E0C40(player, itemGuid, srcContainer, srcSlot,
playerGuid, playerGuid, dstSlot-1, 0)`.
6. Drop the cursor-guard. Cursor state is now irrelevant.
## 60. `GameTooltip:AddSpellByID(spellID)` — easy/medium
Modern method that **appends** spell info to the current tooltip
without clearing existing lines — natural pair to `SetSpellByID`,
which clears + rebuilds. Lets callers compose tooltips like
"talent name (line 1) + AddSpellByID(rankSpell) (rest)".
Direct upgrade for our cross-class `GameTooltip:SetTalentByID`
fallback (#43): the current tier-2 path renders just the spell
tooltip, losing the talent name. With `AddSpellByID` we could do
`ClearLines + AddLine(talentName) + AddDoubleLine("Rank 0/N", "")
+ AddSpellByID(spellID)` to match modern's richer cross-class
tooltip exactly.
Implementation question: 1.12's `BuildSpellTooltip` (the inner
helper at `0x0052E610` we use for `SetSpellByID`) almost certainly
clears the buffer first. We'd need a different entry point that
appends, OR find where the line-emission helper sits inside
`BuildSpellTooltip` and call that directly.
Approach: disassemble `Script_GameTooltip_SetSpell` (`0x00532D10`)
and `BuildSpellTooltip` to identify the "ClearLines" prologue and
the "emit description / cost / range / cooldown" loop. If those
are factored apart, the loop is callable standalone and `AddSpellByID`
is a thin wrapper. If they're inlined, we'd either need to skip
the clear ourselves (call after some no-op state setup) or
manually call the line-emission primitives.
## ~~61. `GameTooltip:GetItem()` / `GetSpell()` / `GetUnit()`~~ — `GetItem` + `GetSpell` DONE; `GetUnit` skipped
Modern query methods that return what the tooltip is currently
showing:
- `GetItem()` → `(name, link, itemID)` — DONE
- `GetSpell()` → `(name, rank, spellID)` — DONE
- `GetUnit()` → `(name, unitToken)` — skipped intentionally
Each Set* path stashes a "currently displayed" field on the tooltip
frame instance, and the per-tooltip Clear at `FUN_00530050` zeroes
the full set on Hide/before-redraw. Verified offsets:
| Field | Offset | Written by | Cleared by |
|---|---:|---|---|
| Item ID | `+0x398` | `BuildItemTooltip` (0x0052B6FE) | `FUN_00530050` |
| Spell ID | `+0x39C` | `BuildSpellTooltip` (0x0052E6D5) | `FUN_00530050` |
`GetSpell` reads `+0x39C`, looks up the Spell.dbc record, and pushes
the localized name + rank + spellID. Returns nothing if the slot is
zero (no spell tooltip displayed). See [src/spell/Tooltip.cpp](src/spell/Tooltip.cpp).
`GetItem` reads two fields: itemID at `+0x398`, item GUID at
`+0x380/+0x384`. When the GUID is non-zero (any path with a real
CGItem — `SetBagItem`, `SetInventoryItem`, `SetLootItem`,
`SetMerchantItem`, etc.) we resolve to a CGItem and dispatch to the
engine's own per-instance link builder at `FUN_0052AE00` — same
helper `Script_GetContainerItemLink` (0x004F9930) uses after
resolving its slot-form args. That produces the fully dressed link
with enchant ID, random-suffix factor, unique ID, and decorated
name. When the GUID is zero (`SetItemByID` / `SetHyperlink` with no
instance data), we fall back to a basic colored link built from
itemID + cached quality + cached name. Returns `(name, link,
itemID)` — the third return is non-modern but saves callers a
gsub. See [src/item/Tooltip.cpp](src/item/Tooltip.cpp).
`GetUnit` was prototyped two ways (token-walk over 92 hardcoded
tokens; MinHook on `Script_GameTooltip_SetUnit` + side-map) and
both scrapped. The 1.12 engine drops the token string immediately
after converting it to a GUID at `+0x368/+0x36C`, so there's no
clean way to return the original token. The walk-list approach is
brittle (misses any future-added token); the hook approach works
but adds collision surface with other Octo DLLs on a high-traffic
function. Modern WoW (3.3.5+) added a dedicated "current unit
token" field on the tooltip frame for exactly this reason — 1.12
just doesn't have the storage. Re-investigate if a low-collision
path emerges (e.g. a write site we haven't seen in 1.12 that
already preserves the string).
## ~~65. `hooksecurefunc(name|table, [name,] callback)`~~ — DONE
Shipped as [src/HookSecureFunc.cpp](src/HookSecureFunc.cpp). Pure C
implementation using a `lua_pushcclosure` with two upvalues
(`orig`, `callback`). The wrapper calls orig with `LUA_MULTRET`,
then callback (returns discarded), then returns orig's full result
list with no count cap.
### Why pure C, not embedded Lua
Originally drafted as a Lua source string executed via
`FrameScript_Execute` at boot. Reworked to pure C to keep all
implementation in one language and avoid embedded source strings;
the refactor added three Lua C API offsets we hadn't wrapped before
(`lua_gettop` at `0x6F3070`, `lua_remove`, `lua_call` at
`0x6F4180`), plus the `LUA_UPVALUEINDEX(i) = GLOBALS_INDEX - i`
helper.
### Lua API offset corrections discovered along the way
While diagnosing why `hooksecurefunc("GetSpellInfo", fn)` was returning
"target field is not a function", a series of `_classicapi_*Probe`
helpers traced the failure to **three misidentified offsets** in
`docs/LuaCAPI.md` (and `Offsets.h`):
| VA | Doc'd as | Actually is |
|----|----------|-------------|
| `0x006F30D0` | `lua_pushvalue` | **`lua_remove`** (shift-down loop + decr_top) |
| `0x006F32B0` | `lua_remove` | **`lua_replace`** (TValue copy + decr_top) |
| `0x006F3350` | `lua_replace` | **`lua_pushvalue`** (TValue copy → top + incr_top) |
How we caught it: `_classicapi_PushValueProbe` showed `GetTop` going
from `1 → 0` after `PushValue(L, 1)` — the supposed `lua_pushvalue`
was actually popping (lua_remove behavior). Disassembly of `0x6F30D0`
confirmed the shift-down loop + `add [ecx+8], -0x10`, vs `0x6F3350`
which has the standard `add [ecx+8], 0x10` incr_top after a single
TValue copy.
`Offsets.h` and `docs/LuaCAPI.md` both updated. The misidentified
offsets had no observable effect previously because no code in the
project used `PushValue` outside `HookSecureFunc.cpp` — every
existing call path uses `PushString`/`PushNumber` for fresh pushes
and `SetTable`/`GetTable` for stack manipulation.
### Why 1.12 needs this even without taint
Modern's "secure" label is about taint propagation in 3.x+ protected
frames. 1.12 has no taint system; the function is functionally a
plain after-hook with return preservation. We ship it for **modern
API parity** — addons being backported from later expansions
frequently use `hooksecurefunc(GameTooltip, "SetInventoryItem", ...)`
and similar patterns, expecting the original to run first and their
callback to fire afterward. Both forms (global by name, table+method)
are supported.
### Unhookable globals
Patch 11.0.0 (The War Within, 2024-07-23) made `hooksecurefunc` refuse a
fixed set of names with a "Cannot hook function" error, to keep callers
from clobbering language primitives or breaking taint propagation. No
earlier client has the restriction (3.3.5, 4.3.4 and 5.4.8 carry no such
string), so 11.0's published list is the reference — and it is NOT the
engine's base-library table (`0x00811E28`, 36 entries, catalogued in
`BlizzardScriptAPI.md` §3): 11.0 leaves `tostring`/`error`/`loadstring`
hookable and includes secure-family names that are not base functions. We
mirror the 11.0 list verbatim with a name blacklist in
`Script_HookSecureFunc` that fires `lua_error` with
`"hooksecurefunc: function is unhookable"`
when the two-arg form targets one of: `getfenv`, `getmetatable`,
`hooksecurefunc`, `ipairs`, `issecurevalue`, `issecurevariable`, `next`,
`pairs`, `pcall`, `pcallwithenv`, `rawget`, `rawset`, `scrub`,
`securecall`, `securecallfunction`, `secureexecuterange`, `select`,
`setfenv`, `setmetatable`, `type`, `unpack`, `wipe`, `xpcall`.
Three-arg form (table + name + callback) is exempt: hooking
`MyLib.pairs` is fine even if `_G.pairs` is not — the blacklist is
specifically about replacing functions on the globals table. A user who
passes `_G` explicitly as the table target is opting in deliberately.
### Cross-version reference
2.4.3 has the strings `hooksecurefunc`/`securecall`/`issecure`
clustered together at `FO=0x4D2CF8`/`0x4D2D08`/`0x4D2D28` in `.rdata`,
suggesting they're a "secure environment helpers" string table for
the engine's taint-propagation code. The `hooksecurefunc` Lua
implementation itself is in `FrameXML/RestrictedFrames.lua` even in
modern WoW — the engine never had an internal C version we could
mirror.
## ~~63. `GameTooltip:SetInventoryItemByID(itemID)`~~ — DONE
Shipped in [src/item/Tooltip.cpp](src/item/Tooltip.cpp).
Confirmed empirically distinct from `SetItemByID`: with run-speed
enchanted boots equipped, `SetInventoryItemByID` shows the
enchant line; `SetItemByID` shows the base item only.
Implementation walks character-pane slots 1..19 looking for an
equipped item matching `itemID`; on hit, dispatches to the
engine's existing `Script_GameTooltip_SetInventoryItem` (registry
slot 19, `0x00532EE0`) with `("player", slot)` rewritten onto the
Lua stack. Silent no-op when the item isn't currently equipped —
caller falls back to `SetItemByID` for unworn items.
### Duplicate-item slot ordering — verified
When the player has duplicates of the same itemID equipped, modern
client renders the **lower-numbered slot** first: MAINHAND (16)
before OFFHAND (17), FINGER1 (11) before FINGER2 (12), TRINKET1
(13) before TRINKET2 (14). Our ascending 1..19 walk + first-match-
break naturally produces the same ordering — lucky, since the
INVSLOT constants happen to be ordered with the "primary" slot
numbered lower than its peer. Locked in with a code comment so
the loop direction doesn't accidentally drift in future refactors.
## 64. `OnTooltipSetItem` / `OnTooltipSetSpell` / `OnTooltipSetUnit` script handlers — DEFERRED, scoped
Modern WoW fires `OnTooltipSetItem` / `Spell` / `Unit` script handlers
on `GameTooltip` after each `SetX` finishes filling the tooltip. The
canonical addon pattern:
```lua
GameTooltip:HookScript("OnTooltipSetItem", function(self)
local _, link = self:GetItem() -- depends on TODO #61
-- augment tooltip
end)
```
1.12 has the tooltip script-handler infrastructure but only fires
**three** specific names: `OnTooltipAddMoney`, `OnTooltipCleared`,
`OnTooltipSetDefaultAnchor`. The modern set is missing.
### Architecture (verified)
- 1.12 has **`GetScript` (`0x00774780`) and `SetScript` (`0x007748D0`)**
natively, but **no native `HookScript`**. Addons polyfill `HookScript`
Lua-side — confirmed via:
- `!!!ClassicAPI/api/api.lua:458`
- `pfUI/modules/eqcompare.lua:224`
Both polyfills compose through `GetScript` + `SetScript`, so
hooking those two makes every existing `HookScript` polyfill in
the wild work for our new names. We don't need to write one
ourselves.
- The script-name → handler-storage mapping lives in a virtual
method on `GameTooltip` (resolved via `vtable[?]`), pointed at by
one entry in `.rdata` at `FO=0x408F6C` → matcher function at
`0x005295D0`. The matcher's body:
```
push 0x7FFFFFFF; push "OnTooltipSetDefaultAnchor"; push scriptName
call SStrCmpI → if match: lea eax, [frame+0x444]; ret
push 0x7FFFFFFF; push "OnTooltipCleared"; push scriptName
call SStrCmpI → if match: lea eax, [frame+0x44C]; ret
push 0x7FFFFFFF; push "OnTooltipAddMoney"; push scriptName
call SStrCmpI → if match: lea eax, [frame+0x454]; ret
xor eax, eax; ret // unknown name
```
Frame storage layout: 8 bytes per script handler slot (probably
`{lua_func_ref, flags}`).
- `GetScript`'s "doesn't have a 'X' script" error fires when this
matcher returns 0 AND the name isn't in the standard frame
scripts (OnEvent, OnEnter, etc.).
### Implementation plan
**Phase 1 — Script handler intercept** (~half-day)
- MinHook on `Script_GetScript` (`0x00774780`) and
`Script_SetScript` (`0x007748D0`). Both are real functions
(already addressable, not just registry slots).
- For each:
1. Read scriptName from Lua stack.
2. If name ∈ `{"OnTooltipSetItem", "OnTooltipSetSpell", "OnTooltipSetUnit"}`:
- Validate stack[1] is a frame.
- For Set: store handler in our registry table.
- For Get: push from our registry table or `nil`.
- Return without invoking original.
3. Else: tail-call original.
- Storage: Lua registry table (allocated once at boot, kept alive
via a known registry index). Keys: `frame_va * "/" * scriptName`.
Handler lookup is `lua_gettable(L, our_table_idx)`.
- Lua ref management: 5.0 uses `lua_ref`/`lua_getref`/`lua_unref`.
Need to find these in the binary (probably near the existing
Lua C API offsets at `0x6F3xxx`); else use a pure Lua-table
approach (set `our_table[key] = function`, retrieve with
`lua_gettable`).
**Phase 2 — Fire from our existing entry points** (~1 hour)
After `Spell::Tooltip::ShowByID` and `Item::Tooltip::Set*ByID`,
call a `FireTooltipScript(L, frame, "OnTooltipSetItem")` helper
that does `lua_gettable` for the handler and `lua_pcall(L, 1, 0)`
with `frame` as arg.
This gives a working but incomplete OnTooltipSetItem — fires for
our two ByID functions but not for the engine's
`SetInventoryItem`/`SetBagItem`/etc.
**Phase 3 — Cover engine `Set*Item` functions** (~2-4 hours)
Either hook each individually (~19 `Script_*Item` functions in 1.12,
list in `docs/raw_methods.txt`) or find a unified inner builder:
- Item: no unified `BuildItemTooltip` apparent — each
`Script_GameTooltip_Set*Item` builds independently. Hooking each
via MinHook is straightforward but adds 19 hook points.
Alternative: find the deeper inner helper they all converge on.
The Set*Item functions all have similar prologues; trace one
thoroughly to find the shared call.
- Spell: **`BuildSpellTooltip` at `0x0052E610`** is the unified
builder (we already use it from `SetSpellByID`). Single hook.
- Unit: find inner of `Script_GameTooltip_SetUnit`
(slot 31, `0x005349B0`).
**Phase 4 — GetItem/GetSpell/GetUnit** (TODO #61, related)
For handlers to be useful, addons typically need to know *what*
was set. Find frame state offsets where the engine stores the
current item/spell/unit. Approach:
1. Set known value via `SetItemByID(6948)` / `SetSpellByID(133)` /
`SetUnit("player")`.
2. Dump GameTooltip frame instance memory.
3. Search for `6948` / `133` / player GUID.
4. Each match reveals the offset for that state field.
Once located, `GetItem()`, `GetSpell()`, `GetUnit()` are trivial
deref+push. Implementation roughly the same as `OffhandHasWeapon`
or `IsEquippedItem` patterns.
### Risks
- **Hot-path hooks:** `GetScript` and `SetScript` are called by
every frame for every script registration. Mistakes in our hooks
can break the entire UI. Test extensively before shipping.
- **Lua ref leaks:** if a frame is destroyed while we hold a ref
to its handler, we leak. Need a "frame destroyed" hook (or
rely on garbage collection of a weak-keyed table).
- **Engine internals path:** finding the unified item builder
(Phase 3) might require deep RE; falling back to 19 individual
hooks is safe but ugly.
### Alternative deferred design — Option B (in case Phase 1 turns
out unworkable in practice)
Skip the SetScript/GetScript intercept entirely. Provide:
```lua
GameTooltip.OnTooltipSetItem = function(self) ... end
```
(field-assignment, no HookScript polyfill needed). We fire from
all the same places as Phase 2-3, but instead of `lua_gettable`
on our registry table, we do `lua_getfield(frame, "OnTooltipSetItem")`
directly off the frame's Lua table. Simpler, but doesn't compose
with `HookScript` polyfills automatically (each addon would
clobber the previous).
## ~~66. Left/right modifier keys + `MODIFIER_STATE_CHANGED` event~~ — DONE
Shipped in [src/input/Modifier.cpp](src/input/Modifier.cpp). Adds
the seven query functions (`IsLeftShiftKeyDown`, `IsRightShiftKeyDown`,
`IsLeftControlKeyDown`, `IsRightControlKeyDown`, `IsLeftAltKeyDown`,
`IsRightAltKeyDown`, `IsModifierKeyDown`) plus the 2.4.3+
`MODIFIER_STATE_CHANGED(key, down)` event. All seven match the
modern WoW return shape (`1` for down, `nil` for not-down).
### Why this needed a Win32 hook
The engine has **no L/R distinction anywhere in its state**. 1.12's
own `IsShiftKeyDown` chain bottoms out at `GetKeyState(VK_SHIFT)` —
the merged virtual key `0x10` — at `0x00436024`, never the L/R-aware
`VK_LSHIFT` / `VK_RSHIFT` (`0xA0` / `0xA1`). Helper3 at `0x00436D80`
returns a struct with only 3 modifier slots (shift/ctrl/alt), confirmed
by inspection. No amount of digging in engine memory finds L/R state
because **it never existed there**.
There IS a 6-bit field at `[*[0x00C0ED38] + 0x269C]` that looks
structurally identical to 2.4.3's L/R modifier bitmask at `[+0x130]`
— same shift-and-mask helper at `0x005936C0`, same 6-bit dispatch
limit. We chased it for a while. Empirically the field is something
else entirely (some kind of input-device-flags bitmask) — it stays at
`0x3BF` regardless of which modifier is held. The 2.4.3 → 1.12
structural similarity is misleading; the field's meaning evolved.
The OS-level keystate **does** have the L/R distinction (VK_LSHIFT /
VK_RSHIFT etc.), and 1.12 already uses Win32 `GetKeyState` for its own
modifier checks — so calling `GetAsyncKeyState(VK_LSHIFT)` ourselves
is the same primitive the engine already uses, just with the L/R-aware
VK codes.
### Why a `WH_GETMESSAGE` hook over `SetWindowLongPtr` subclass
We initially subclassed WoW's `WNDPROC` (via `EnumWindows` to find the
`GxWindowClassD3d`/`GxWindowClassOpenGl` HWND, then `SetWindowLongPtrA`
to install a wrapper). Worked for L/R queries and the event. Then the
user toggled vsync and the event went silent — WoW destroys and
recreates its main window on some renderer state changes, so the
subclass was left dangling on a destroyed HWND.
Switched to `SetWindowsHookExA(WH_GETMESSAGE, ..., GetCurrentThreadId())`.
The hook is per-thread, not per-HWND, so it survives any number of
window recreations. Decodes `WM_KEY{,SYS}{DOWN,UP}` messages,
maintains a 6-bit cached bitmap that the queries read, and fires
`MODIFIER_STATE_CHANGED` on transitions.
### L/R decoding from WM_KEY messages
- `VK_SHIFT` (the merged virtual key the OS delivers for either key)
→ `MapVirtualKeyA(scancode, MAPVK_VSC_TO_VK_EX)` returns
`VK_LSHIFT` or `VK_RSHIFT` based on the hardware scancode.
- `VK_CONTROL` / `VK_MENU` → the `KF_EXTENDED` flag (bit 24) of
`lParam` discriminates: extended = right, plain = left.
- `VK_L*` / `VK_R*` delivered directly (some keyboards, SendInput) →
accepted as-is.
### `MODIFIER_STATE_CHANGED` and the custom-event saga
Documented as part of the broader event-table investigation in
CLAUDE.md's "Events" section. Short version: we tried three approaches
to inject custom event names into the engine's event table.
**Approach A — slot-claim (original Event::Custom)**: walk the live
table for NULL slots, write our `SMemAlloc`+memcpy'd name. Works.
Downside: first NULL slots were near the head of the table (slot 1
got `MINIMAP_BLIP_TRACKING_CHANGED` from VanillaMinimapTracking,
which felt off).
**Approach B — rebuild-hook + tail-injection**: hook
`RebuildEventTable` at `0x00703D90`, pad the input array to 1024
entries, place our names at the tail (slots 1020+). Engine's own
SStrDup handles allocation, so we never write to engine memory.
Worked for a single DLL. **Crashed when SuperWoWhook, nampower,
transmogfix, and VanillaMinimapTracking all hooked the same
function**: their layered modifications to `(names, count)` produced
a count→buffer-size mismatch, and the engine's fill loop wrote off
the end of the allocated buffer on its last iteration.
**Approach C — slot-claim + backward walk (final)**: same as A but
walk the table from `count-1` downward looking for NULL slots, so
high indices are claimed first. Each DLL works on the table
independently — no hook chaining, no argument modification, no
crashes. Custom events naturally group at the tail (verified: slots
695..699 with all five custom events when ClassicAPI +
VanillaMinimapTracking are both loaded). Also swapped
`SMemAlloc + memcpy` for the engine's own `SStrDup` at `0x0064A620`
— cleaner allocator, exactly matches what the engine's bulk
rebuild does.
The intermediate rebuild-hook approach also uncovered the engine's
**hardcoded post-rebuild slot writes**: the bulk rebuild populates
slots 0..548 from its `0x00BE1198` name array, then engine code
writes specific events to hardcoded slot indices in the 549..699
range (`SPELL_DAMAGE_EVENT_SELF` at slot 549,
`SPELL_DAMAGE_EVENT_OTHER` at 550, etc.). Documented in CLAUDE.md.
This is why claiming slots from low indices early-on would have
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~~ — 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
`m_bagUpdateDelayedPending` flag from the bag-change pipeline and
drains it from `CContainerMgr::Update` (its per-frame routine),
producing exactly-one coalesced fire per frame.
### What we tried
A pure C++ hook chain:
- Naked thunk over `FUN_FIRE_EVENT` (`0x00703F50`) — peek at the
event ID, set a pending flag on match against the cached
`BAG_UPDATE` slot, `jmp` to the trampoline so the variadic stack
passes through untouched.
- Normal `__thiscall`-style hook over the per-frame OnUpdate
dispatcher at `0x00772890` — drain the pending flag and fire
`BAG_UPDATE_DELAYED` once per frame.
Reservation via the existing `Event::Custom::AutoReserve` slot-claim
machinery. The DLL compiled cleanly and registered the event;
`IsEventValid("BAG_UPDATE_DELAYED")` returned `true`.
### Why we reverted
The DLL crashed during the login-screen XML load — `EIP=0x15FF075B`
inside MinHook trampoline space, with zero bytes at that address,
`ESP=0x001AEFEB` (misaligned), and stack ret-addr `0x00772954` inside
the patched function. Classic signature of a corrupted MinHook
trampoline.
The user's Octo install loads SuperWoWhook, nampower, transmogfix,
UnitXP_SP3, VanillaHelpers, VanillaMinimapTracking, and
VanillaMultiMonitorFix alongside ours. Each links its own MinHook
copy. Hooking high-traffic engine functions like the event dispatcher
or per-frame OnUpdate sits squarely in the path where trampoline
regions can collide between DLLs — same class of problem as the
`RebuildEventTable` hook-chaining failure we already documented in
CLAUDE.md.
We removed `src/bag/UpdateDelayed.{cpp,h}`, the two `HOOK_FUNCTION`
calls in `DllMain.cpp`, and `FUN_FRAMESCRIPT_FRAME_ONUPDATE` from
`Offsets.h`.
### Earlier dead end: Lua-source bootstrap from C++
Before the hook attempt, I shipped a version that used
`FUN_FRAME_SCRIPT_EXECUTE` (`0x00704CD0`) to inject a Lua snippet
creating a hidden frame with `RegisterEvent("BAG_UPDATE")` /
`SetScript("OnUpdate", ...)`. The user pushed back: embedding Lua
source in the DLL is architecturally wrong for this project. The
right answer is always a C++ engine hook. `FUN_FRAME_SCRIPT_EXECUTE`
is gone from the codebase; pretend it doesn't exist. (See the
saved feedback memory.)
### Ghidra investigation (2026-05-11) — actual fire-site map
Disassembling 1.12 reveals **three call sites** of
`FUN_00703F50(0x148, "%d", bagID)` (event ID `0x148` = 328 =
BAG_UPDATE — derived from the BAG_UPDATE name pointer's position
in the input array at `0x00BE16B8`, offset `0x520` from array
base, divided by stride 4):
1. **`FUN_004F91A0`** — bag-slot diff loop (2 callers — quiet).
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. Also fires event `0x149`
(BAG_CLOSED) when a bag is removed. Called from the per-session
init (`FUN_004F8CC0`) and from packet-handler `FUN_004F8EC0`.
2. **`FUN_004F8DB0`** — item-descriptor-change callback (4
callback registrations, all in init helpers). Direct
`FUN_00703F50(0x148, "%d", -2)` for slot range `0x51..0x70`
(keyring). Other slot ranges delegate to `FUN_004F9370`.
3. **`FUN_004F9370`** — item→bag resolver (3 callers, all inside
the bag subsystem). Given an item GUID, searches `DAT_00BDD060`
for a match. Fires `BAG_UPDATE(0)` if the item belongs to the
player (backpack), `BAG_UPDATE(N)` if it's in bag N, returns
silently if not found in any bag. This is the **most common
path** — every "item moved within bags" event flows through
here.
All three targets are quiet (≤4 callers each, all inside the bag
code region `0x004F8DB0..0x004F94D0`). None overlap with the
hot-loop hook targets the previous attempt collided on
(`FUN_FIRE_EVENT`, the per-frame OnUpdate).
### Revised implementation plan
**Approach: hook all three fire sites + read engine's per-frame
counter to coalesce.**
The engine maintains a monotonic frame counter at `0x00C7B2C8`,
incremented once per world tick from `FUN_0066FD50` (the world-
subsystem update). Only **two writers** in the binary —
`FUN_0066F6C0` zeros it on world load, `FUN_0066FD50`
increments it +1 per frame. Reading it tells us, exactly,
"are we in a new frame since the last observation?"
```cpp
constexpr uintptr_t VAR_WORLD_FRAME_COUNTER = 0x00C7B2C8;
uint32_t g_lastSeenFrame = 0;
void EmitDelayedOnFrameBoundary() {
const uint32_t now = *reinterpret_cast<uint32_t *>(VAR_WORLD_FRAME_COUNTER);
if (now == g_lastSeenFrame) return; // same frame — coalesce
g_lastSeenFrame = now;
const int slot = Event::Custom::Lookup(kBagDelayedEvent);
if (slot >= 0) Event::Custom::Fire_None(slot);
}
void __cdecl Bag_004F91A0_h() {
g_004F91A0_orig();
EmitDelayedOnFrameBoundary();
}
// Same wrapper pattern for FUN_004F8DB0 (__thiscall taking
// `(int slotID, GUIDlo, GUIDhi, int *cachedGUID)` per the
// decompile) and FUN_004F9370 (cdecl `(int lo, int hi)`).
```
Properties:
- **Exact frame coalescing** — multiple BAG_UPDATEs in the same
frame produce exactly one BAG_UPDATE_DELAYED, regardless of how
close they are in wall-clock time.
- **No time math, no arbitrary threshold** — the engine's own
frame counter is the source of truth.
- **No new hook on a per-frame routine** — we *read* the counter,
not hook the writer. Zero MinHook footprint outside the three
bag-subsystem targets.
- **No glue-screen activity** — `DAT_00C7B2C8` doesn't increment
before the player enters world, which is fine since BAG_UPDATE
doesn't fire there either.
**Why this avoids the previous attempt's crash:** none of these
three targets are common hook destinations for other DLLs. The
problem before was hooking `FUN_FIRE_EVENT` (100+ callers,
trafficked by every event) and `FUN_FRAMESCRIPT_FRAME_ONUPDATE`
(per-frame dispatcher) — both prime collision targets for
SuperWoWhook / nampower / transmogfix. The bag subsystem
internals at `0x004F9xxx` aren't touched by those DLLs (none of
them care about bag-update timing), and the per-frame counter
at `0x00C7B2C8` is a pure memory read with no hook at all.
**Semantic match vs modern:** modern coalesces at exact end-of-
frame; we coalesce within a single world-tick frame using the
same counter the engine itself uses to drive the framerate
sampler. Equivalent in practice — addons doing "rescan
inventory on BAG_UPDATE_DELAYED" see exactly one fire per frame
in which any bag activity occurred.
### Fallback if even three quiet hooks collide
Drop to hooking only `FUN_004F9370` (the most common path).
Misses bag-equip-itself and keyring cases but covers the 90%
case of "user picked up an item / moved an item in bag." Single
hook, lowest collision risk.
### Honest fallback
If both hook plans collide, document the limitation — addons
that want this behavior on Octo-style multi-DLL clients can
fall back to debouncing `BAG_UPDATE` themselves via an
`OnUpdate` timer.
## ~~68. `UnitChannelInfo(unit)` / `UnitCastingInfo(unit)`~~ — DONE
Shipped in [src/spell/Cast.cpp](src/spell/Cast.cpp): `UnitCastingInfo`,
`CastingInfo`, `UnitChannelInfo`, `ChannelInfo`. Verified in-game —
Blizzard channel `(…, 907894314, 907902314, …, 10187)` (8s), Conjure Food
cast `(…, 907928268, 907931268, …, 28612)` (3s), `GetTime()*1000` falls
between start/end.
**The start/end-time hunt resolved with a firm negative**, confirmed via
the cross-binary technique. 3.3.5's `Script_UnitCastingInfo`
(`0x00611DF0`) / `Script_UnitChannelInfo` (`0x00612090`) read cast times
from **per-unit CGUnit fields** (cast `+0xa6c/+0xa78/+0xa7c`, channel
`+0xa80/+0xa84/+0xa88`) — TBC/WotLK additions that don't exist in the
1.12 CGUnit (the tell: 1.12's *player* cast spellID is a global,
`VAR_CURRENT_CAST_SPELL`, not a unit field). 1.12 stores no cast times
anywhere readable; the cast bar is Lua-driven off `SPELLCAST_START`, and
remote units' casts are transient spell-visual objects
(`FUN_0060d7c0`), not a queryable record. The cast-timer globals at
`0x00cee8d4..e4` are a shared visual-system slot (written for *any*
channeling unit via `FUN_00612a30 → FUN_0060d7c0`), so they're not
player-safe.
So timing is **self-tracked for the local player** on `WorldTick`:
- cast: `VAR_CURRENT_CAST_SPELL` 0→nonzero → `startMs = FUN_OS_TICKCOUNT_MS`,
`endMs = start + SpellCastTimes base ms`. Instant casts (cast time 0)
and channels are filtered out of the cast path.
- channel: player's broadcast `UNIT_FIELD_CHANNEL_SPELL` (`+0x228`),
`endMs = start + SpellDuration base ms`.
`FUN_OS_TICKCOUNT_MS` shares `GetTime()`'s epoch (×0.001), so the ms
values feed addon progress math directly. Other units: channel
spellID/name/texture from the broadcast `+0x228` (no times); regular
casts return nil (no vanilla data).
`isTradeskill` is real — `SPELL_ATTR_TRADESPELL` (Attributes bit 0x20,
the version-stable bit 3.3.5's Script_UnitCastingInfo reads). Verified:
Rough Blasting Powder (Engineering) → true, Conjure Food → false.
Cast time is the **effective** time, not base: we call the engine's
cast-time helper `FUN_006e3340` (base + level scaling + cast-time SpellMod
op 10 + the caster's haste/cast-speed multiplier at descriptor +0x22c) —
the same helper the engine's own cast-start uses, so our end time matches
the cast bar. Verified: talented Frostbolt (Improved Frostbolt -0.5s)
reads 2.5s, not the 3.0s base. (Calling the helper beats replicating op 10
via `Spell::Mod`, which would miss the cast-speed multiplier.)
**Follow-up:** `delayTimeMs` pushback tracking (currently 0).
Companion field (`desc 0x1320`, prior channeled spell) — see entry #71.
## 69. `IsGathering()` — easy (local player only)
No-arg local-player boolean that fires while the player is
mid-gather: herb pick, ore mine, fishing-bobber-loot, lockpicking,
skinning. Modern WoW doesn't expose this exact concept but addons
that care (auto-attack suppression, mouse-look reversion, autorun
toggles) reverse-engineer it from `LOOT_OPENED` /
`UNIT_SPELLCAST_*` events. A direct read is cleaner.
State machine from the `IsAssistingRitual` session, verified by
diffing the player while gathering:
- `[player + 0x1D28]` / `[player + 0x1D2C]` — 64-bit GUID of the
GameObject the player is gathering from. `0xF110xxxx` high half
= vanilla GameObject prefix. Set when the gather animation
starts, cleared when it ends or breaks.
- `[player + 0xD48]` — small int, `0` baseline, `1` during gather.
Confirmed for herb gather; mining sets the same field. Cleanest
single-bit signal we have.
- `UNIT_FIELD_FLAGS` (descriptor `+0xA0`) bit `0x1000` is cleared
during gather — unclear what the bit semantically means (other
emulator sources don't agree on this bit's name in vanilla), but
it's another way to detect the state.
Three implementation options worth picking between:
1. **`IsGathering()`** boolean, `[player+0xD48] != 0`. One line.
2. **`GatheringObjectGUID()`** returning `(lo, hi)` from
`[player+0x1D28]/+0x1D2C`. Lets addons distinguish herb-from-
herb / chest-from-chest. Modest extra surface.
3. **Family of `IsHerbing()` / `IsMining()` / `IsFishing()`** —
requires looking up the GameObject's type/sub-class from its
GUID, which means walking the engine's GO cache. Significantly
more work; defer unless someone has a use case.
Fishing is the trickiest case — `/cast Fishing` is a regular spell
cast (sets UNIT_CHANNEL_SPELL = 7620), the bobber sits in water
during a separate wait phase (UNIT_CHANNEL_OBJECT = bobber GUID),
then the right-click bobber action triggers the gather/loot
machinery (sets `[player+0x1D28]/+0x1D2C` to the bobber GUID, but
NOT `0xD48`). So `[player+0xD48]` is "gather-cast active"
(herbing/mining), and `[player+0x1D28]` is the broader "engaged
with a lootable GO" pointer. Pick which semantic you want before
naming.
## ~~70. `UnitStandState(unit)`~~ — DONE
Modern `GetUnitStandStateValue(unit)` or `UnitStandState(unit)` (the
name varies by expansion) returns an integer describing whether
the unit is standing / sitting / sleeping / kneeling. Vanilla 1.12
exposes only `IsSitOrStanding()` (local boolean) and lacks any
"is target sitting" check.
Verified directly via the `IsAssistingRitual` session: descriptor
`+0x210` is `UNIT_BYTES_1` (CMaNGOS field 132 in the 1.12.1
layout). The standstate is the **low byte** of that u32. Observed
transition during a `/sit` on a chair: `0xEE00 → 0xEE05`,
i.e. low byte 0 → 5 (`STANDSTATE_SIT_MEDIUM_CHAIR`).
Vanilla standstate enum (from emulator sources, low byte of
`UNIT_BYTES_1`):
| Value | Meaning |
|------:|---------------------|
| 0 | STANDING |
| 1 | SITTING |
| 2 | SITTING_CHAIR |
| 3 | SLEEPING |
| 4 | SITTING_LOW_CHAIR |
| 5 | SITTING_MEDIUM_CHAIR|
| 6 | SITTING_HIGH_CHAIR |
| 7 | DEAD |
| 8 | KNEELING |
Implementation: resolve unit → descriptor → `[+0x210] & 0xFF`.
Broadcast field, so it works for any synced unit (player, target,
party/raid, inspect targets) — not local-only.
While we're documenting `UNIT_BYTES_1`, the other bytes of the same
u32 are worth deriving when needed (CMaNGOS docs say byte 1 =
`PetTalents`, byte 2 = `VisFlag`, byte 3 = `AnimTier`), but none
have an obvious modern-API hook in vanilla.
## ~~72. `C_EquipmentSet.*` namespace — DONE
Full backport of modern's equipment-set API on top of a client-side
persistent store at `WTF\Account\<acct>\<realm>\<char>\
ClassicAPI_EquipmentSets.txt`. 18 functions including `Create`,
`Save`, `Modify`, `Delete`, `Use`, `GetItemLocations`, plus the
ignored-slot quartet. Identity is by item GUID — `Locations::FindGUID`
walks the player invMgr's flat GUID array for paperdoll / backpack /
main bank, and reaches bag contents (player bags 1..4 and bank bags
5..10) via each bag's CGContainer→invMgr through `vtable[+0x10]`.
Same direct-read technique `C_Item.GetItemCount` uses, so bank items
resolve without the bank window being open.
Also exposes the `ITEM_INVENTORY_LOCATION_PLAYER` / `_BAGS` / `_BANK`
/ `_BAG_BIT_OFFSET` / `_BANK_BAG_OFFSET` constants as Lua globals so
addon code copy-pasted from modern FrameXML's
`EquipmentManager_UnpackLocation` works unchanged. Fires
`EQUIPMENT_SETS_CHANGED` (no payload) on any mutation and
`EQUIPMENT_SWAP_FINISHED(success, setID)` at the end of
`UseEquipmentSet`. See `docs/API.md` and `src/equipmentset/`.
## ~~73. `C_EquipmentSet.UseEquipmentSet` — proper swap-cycle resolution~~ — DONE
`UseEquipmentSet` currently walks slots in order and does a
pickup→equip pair per item. If two items in the set want each other's
slots (e.g. ring A in slot 11 wants slot 12, ring B in slot 12 wants
slot 11), the first pickup succeeds, the equip drops it correctly,
but the second pickup picks up B and `EquipCursorItem` swaps it
into the now-occupied slot — leaving one ring stashed on the cursor
which our cleanup `ClearCursor` either drops back or routes to a free
bag slot. Re-running `UseEquipmentSet` finishes the job, but it
shouldn't take two calls.
### Solution: same primitive as #59
`FUN_005E0C40` (decoded in #59) is the engine's atomic swap-and-send.
Replacing the pickup+equip pair with a direct `FUN_005E0C40` call
fixes the cycle case naturally: each swap is one server packet that
atomically exchanges two slots. The classic 2-cycle "A in 11, B in
12, want A in 12, B in 11" resolves in a single call —
`FUN_005E0C40(player, A, player, 10, player, player, 11, 0)` sends
opcode `0x10D {src=10, dst=11}` and the server swaps both slots.
Longer chains (3+ items rotating) are rare with 1.12's equipment
slot set — the realistic conflicts are 2-cycles between paired
slots (rings 11/12, trinkets 13/14, weapons 16/17). One swap each.
For sequential non-cycle moves (item from bag → empty slot), the
swap is still atomic and doesn't touch the cursor. The catch is
that consecutive `FUN_005E0C40` calls in the same frame queue at
the server before any inventory update arrives — so subsequent
iterations see stale local state. For independent moves this is
fine (each swap target is different); for chains it can produce
no-op or undo behavior.
### Implementation plan
[src/equipmentset/Api.cpp](src/equipmentset/Api.cpp)
`Script_UseEquipmentSet`:
1. Drop the `ClearCursor()` calls at start and end — irrelevant now.
2. Replace the per-slot pickup+equip pair with a single
`FUN_005E0C40` call:
- srcItem GUID: read off the CGItem at the resolved
`Locations::FindGUID` location
- srcContainer + srcLinearSlot: from `loc` decode per the table
in #59
- dstContainer = player, dstSlot = `targetSlot - 1`
3. Keep the existing skip-conditions: GUID empty/ignored, already
in target slot, in bank, etc.
The bank-skip stays: vanilla server rejects equip-from-bank, and
no client-side workaround changes that.
Same shared helper between #59 and #73: an `Item::Swap::EquipByGuid`
or similar that takes (CGItem*, dstPaperdollSlot) and handles the
container-guid + linear-slot resolution. Implement once, use in
both call sites.
## ~~74. `EQUIPMENT_SWAP_PENDING` event~~ — DONE
Fires `(setID)` at the start of `UseEquipmentSet` right after the
set-exists check, before any pickup/equip work. Skipped when the
set doesn't exist (only FINISHED with `success=false` fires
there). Added `Event::Custom::Fire_D` (single-int variant) to
support the one-arg signature.
## 75. Bank-bag walk — extract shared helper
`Item::Count::CountInBankBags` and `EquipmentSet::Locations` both
walk bank-bag contents via the same pattern: read GUID at linear
slot 63..68 of player invMgr → `FUN_OBJECT_RESOLVE_BY_GUID` with
`OBJ_TYPE_CONTAINER` → invoke `vtable[+0x10]` to get the bag's own
invMgr → walk that invMgr's flat GUID array at +0x04. Same
boilerplate twice. If a third caller needs it, extract to
`Item::Inventory::WalkBagsByGUID(callback)` or similar in a shared
header. Not worth the refactor for two callers yet.
## 77. `IsLoggedIn()` — skipped
WotLK addition. Returns `true` if the player is in the world,
`false` at character select / login screen.
Prototyped twice and pulled both times:
1. **World-only registration** (via the regular module-register
hook) — implementation was trivial (`FUN_RESOLVE_UNIT_TOKEN("player")
!= nullptr`), but the function only existed in the world Lua
state. Glue-screen Lua couldn't reach it, so addons that gate
on the world transition would see `attempt to call a nil value`
pre-login.
2. **Glue + world** (added a MinHook on the glue script registration
at `FUN_0046DDF0`) — crashed on the "Tiny" 1.12.1 build with an
access violation at the patched bytes. The glue-register
function is too small (~9 byte prologue) for a stable 5-byte
JMP across binary variants and likely overlaps with another
loose-loader DLL's hook.
For now, addons that need login-state gating can use the
`PLAYER_LOGIN` / `PLAYER_ENTERING_WORLD` events (both fire
in-world reliably). Revisit if a safer glue registration path
surfaces.
## ~~83. `C_Item.GetWeaponEnchantInfo()`~~ — DONE
Vanilla 1.12's global `GetWeaponEnchantInfo` returns 8 values
(has/expire/charges per weapon slot) but **no enchant IDs**.
WotLK+ extended the signature to 12 returns by inserting the
temp-enchant ID after each weapon's data. We provide the modern
12-tuple in the `C_Item` namespace, leaving the vanilla global
intact for addons that depend on its position layout.
Reads `ITEM_FIELD_ENCHANTMENT` slot 1 (descriptor `+0x4C..+0x54`,
the TEMPORARY enchantment slot) for mainhand / offhand / ranged
equipment slots — the same slot the engine drains as the
oil/stone/poison expires. The permanent enchant (Crusader,
Mongoose, etc. in slot 0 at `+0x40`) isn't reported here; modern's
`GetWeaponEnchantInfo` is specifically about temp data.
See [src/item/WeaponEnchant.cpp](src/item/WeaponEnchant.cpp).
## ~~78. `GetCVarBool(cvar)`~~ — DONE
Dispatches the engine's `Script_GetCVar` at `0x00488BA0` to read
the cvar's string value, then coerces: non-zero numeric or
`"true"` (case-insensitive) → `true`; `"0"` / empty / nil /
unknown cvar → `false`. Exposed as `C_CVar.GetCVarBool(cvar)`.
See [src/cvar/Bool.cpp](src/cvar/Bool.cpp).
## 79. `IsTrialAccount()` / `IsVeteranTrialAccount()` — trivial
WotLK additions. Always returns `false` on 1.12 — vanilla
predates trial accounts (introduced 5.x). Modern addons gate
features on these and crash without them. One-liner.
## ~~80. `IsHelpfulSpell(spell)` / `IsHarmfulSpell(spell)`~~ — DONE
Reads `Spell.dbc.AttributesEx` (`+0x1C`) bit `0x80` —
`SPELL_ATTR_EX_NEGATIVE` (CMaNGOS' `SPELL_ATTR_EX_NEGATIVE_1`).
Same bit the engine uses to classify auras into the debuff slot
range, so it's reliable for combat spells.
The earlier TODO note about `AttributesEx2` bits `0x10` / `0x20`
turned out to be wrong — those bits are `CANT_REFLECTED` and
`AUTO_REPEAT` per CMaNGOS, not helpful/harmful. The right flag is
the single `NEGATIVE` bit in `AttributesEx`.
Helpful side: "spell exists in Spell.dbc and isn't marked negative"
— vanilla has no dedicated positive-spell flag, so utility spells
that aren't harmful read as helpful. Approximation; close enough
for most addon use cases. Strict modern semantics (where some
spells return false for both) would require parsing every effect's
implicit target — deferred.
Four Lua surfaces: `IsHelpfulSpell(spell)`, `IsHarmfulSpell(spell)`
(global, accepts `spellID` or `(slot, bookType)`), and
`C_Spell.IsSpellHelpful(spellID)` / `C_Spell.IsSpellHarmful(spellID)`
(C_Spell namespace, takes numeric ID only).
See [src/spell/Info.cpp](src/spell/Info.cpp).
## 81. `GetItemUniqueness(item)` — easy
Returns `(limitCategory, maxCount)` — used by stack-aware addons
(BankItems, ARL) to know whether an item is "unique" (max 1 in
inventory) or "unique-equipped" (max 1 equipped).
Reads from ItemStats record's flag field. Vanilla items have a
simpler binary "unique" flag; the modern Limit Category system
(`ItemLimitCategory.dbc`) was added in TBC and may not exist in
1.12. Implementation: return `(0, 1)` for items with the unique
flag set, `(0, 0)` otherwise.
## 82. `GetItemCooldown(itemID)` — medium
Returns `(startTime, duration, enable)` for an item's
on-use cooldown — the standard cooldown tuple. Different from
`GetContainerItemCooldown` (which takes bag+slot); modern addons
use the itemID form because they don't always know where the
item lives.
Implementation: items with on-use spells map to spell cooldowns
via `Item::Spell::OnUseSpellIDForItemID` (already wired for
`Hearthstone`/`GetItemSpell`). From the spellID, query the engine's
spell-cooldown machinery — same function `Script_GetSpellCooldown`
uses internally.
## 83. `GetItemStats(itemLink, [statTable])` — medium-hard
Returns a `{ ITEM_MOD_STAMINA_SHORT = 5, ITEM_MOD_STRENGTH_SHORT = 10, ... }`
table for the item. Heavy addon dependency — Pawn, AtlasLoot,
GearScore, and every gear-comparison TSM-style addon use it.
ItemStats record carries up to 10 stat-type/stat-value pairs at
fixed offsets. 4.3.4 implementation at `0x0044C200` parses the
itemLink (for enchant + gem deltas) then walks those 10 slots and
emits a table keyed by stat-type-id-string.
In vanilla, enchant IDs from itemLinks need lookup via
`SpellItemEnchantment.dbc` to add their stat deltas. Gems are N/A
(no socket system in vanilla — drop that branch). The base
ItemStats walk is the main work.
## 84. `IsUsableItem(item)` — medium
Returns `true` if the item is currently usable by the player —
considers level requirement, class restriction, race restriction.
Used by tooltip code and "use item" buttons to gray themselves
out for unusable items.
Vanilla itemstats has `m_requiredLevel`, `m_allowableClass`, and
`m_allowableRace` fields. Implementation: peek the cache, check
those three against player's level/class/race (race is in
`UNIT_FIELD_BYTES_0`, already read in `GetPlayerInfoByGUID`).
## 85. `IsSpellInRange(spell, unit)` / `SpellHasRange(spell)` — medium
Range-check predicates. `SpellHasRange` is a Spell.dbc
`RangeIndex != 1` check (range index 1 is "Self Only").
`IsSpellInRange(spell, unit)` requires:
1. Resolving spell name to spellID (lookup is already in
`Spell::Lookup`)
2. Reading `RangeIndex` from Spell.dbc (already wired in
`Spell::Info` for the range column)
3. Looking up `minRange`/`maxRange` from `SpellRange.dbc` (already
in `OFF_SPELLRANGE_*` constants per `Offsets.h`)
4. Computing 3D distance between player and unit
5. Returning `1` if inside range, `0` if outside, `nil` for
invalid unit (can't get position)
Step 4 needs the engine's unit position read primitive — we have
no offset for that yet. CGUnit has a position field at some
descriptor offset; finding it is an hour's work.
## 86. `GetMirrorTimerInfo(index)` / `GetMirrorTimerProgress(label)` — DONE
Implemented in [src/unit/MirrorTimer.cpp](src/unit/MirrorTimer.cpp).
The vanilla engine fires `MIRROR_TIMER_START` / `_PAUSE` / `_STOP`
events with the full payload but doesn't cache the state, so we hook
the SMSG handler at `FUN_005E7990`, peek the packet via cursor
save/restore on the CDataStore at `+0x14`, and build a 3-slot side
cache. `GetMirrorTimerInfo` returns the snapshot; `GetMirrorTimerProgress`
interpolates against engine ticks for the live value. Type names are
`"EXHAUSTION"` / `"BREATH"` / `"FEIGNDEATH"` (engine wording — modern
uses `"FATIGUE"` for the off-map one; we preserve what the engine
actually returns).
## 87. `GetMacroSpell(macroIndex)` — DONE
Implemented in [src/macro/Spell.cpp](src/macro/Spell.cpp). Turned out to
be a one-read job: the vanilla engine already walks every macro body
at create / edit / refresh via `FUN_MACRO_PARSE_PRIMARY_SPELL`
(`0x004EFE00`) and caches the resolved spellID on the macro struct at
`+OFF_MACRO_PRIMARY_SPELL` (`+0x564`). `GetMacroSpell` reads the cache
via `FUN_MACRO_SLOT_TO_ENTRY` (`0x004F0E40`), translates `0` /
`0xFFFFFFFF` sentinels to "no match," and looks up name + rank from
`Spell.dbc` for the resolved ID. Returns `(name, rank, spellID)`
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~~ — 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,
tooltip-decoration, and stat-sheet addons. **The single highest-
value event missing from vanilla** — backporting it would
unblock dozens of addons that gate refresh logic on it.
Vanilla fires `UNIT_INVENTORY_CHANGED` for the player when any
slot changes, but doesn't say WHICH slot. Implementation: cache
the player invMgr's GUID array for slots 0..18 at our hook
point, diff against last snapshot, and fire
`PLAYER_EQUIPMENT_CHANGED(slot, hasItem)` once per changed slot
via `Event::Custom`.
### Investigation history (2026-05-22)
User strongly prefers an event-driven hook over per-frame
polling. Multiple promising targets tried; **none fired on
user-driven equip/unequip actions in the Octo build**.
**`FUN_004F8DB0`** (the bag/inventory descriptor-change callback)
— our existing `BAG_UPDATE_DELAYED` hook target. Empirically only
called for backpack contents (offsets `0x560..0x5D9`, slots
23..38) and keyring (offsets `0x730..0x829`, slots 81..112). The
`FUN_004F8CC0` registration setup confirms there is **no
registered per-slot descriptor-change callback for equipment
slots 0..18** (offsets `0x4A8..0x53F`). Equipment slot descriptor
writes happen silently during SMSG_UPDATE_OBJECT processing.
**Three direct `push 0xBA; call FUN_00703F50` sites** found for
`UNIT_INVENTORY_CHANGED`:
- `0x004C710B` and `0x004C72DB` (both in `FUN_004C7180`,
`__cdecl(uint guidLo, uint guidHi)`, 5 callers in the
`0x5D8xxx-0x5D9Bxx` SMSG region).
- `0x004C8504` (in `FUN_004C84F0`, 0 direct callers — vtable or
dead).
**Two `mov edx, 0xBA; call FUN_00515E50` sites** at `0x0051BD73`
and `0x005D85FE`. `FUN_00515E50(guid, eventID)` is the
**unit-event firer** — walks the GUID→token reverse resolver
(`FUN_00515C50`) and fires `(eventID, "%s", token)` for each
matching unit token. 37 callers across many event IDs — direct
hook is too generic / high traffic.
`FUN_005D8440` (containing `0x5D85FE`) is the item-update
post-processor — `__fastcall(void *cgItem)`, 2 callers, fires
UNIT_INVENTORY_CHANGED via `FUN_00515E50(itemGUID, 0xBA)` for
the affected item.
**Hook attempts that did NOT fire on equip/unequip:**
- `FUN_004F8DB0` via `Bag::InvDescChange` dispatcher subscription
— slot range is backpack + keyring only, never equipment.
- `FUN_004C7180` direct hook — function's preconditions
(visible-item filter, slot-range gate) bail before FIRE_EVENT
on plain bag↔equipment swaps.
- `FUN_005D8440` direct hook — debug log never printed despite
the user confirming `UNIT_INVENTORY_CHANGED` fires.
**Open question:** if all three known 0xBA-firing functions are
hooked and none of our hooks trigger on equip, then either:
(a) the hooks aren't being installed for some reason (collision?
some Octo modification?), or (b) the event fires through a
mechanism we haven't found — possibly via the LUA-side
`FrameScript_FireEvent("UNIT_INVENTORY_CHANGED", "player")`
called from another function we haven't traced.
**Next steps to try:**
- Add `_classicapi_DumpHook` or similar diagnostic that confirms
the hook is actually in place after `MH_EnableHook` returns.
Maybe Octo or another DLL is unhooking us.
- Search the binary for `"UNIT_INVENTORY_CHANGED"` string
references — if the event name is referenced in code (not just
in the boot-time table), there's a string-based firing path
we missed.
- Investigate the `mov ecx, 0xBA` sites at `0x60341B` and
`0x604F77` — both call `FUN_005AB650`/`FUN_005AB670` (packet
handler registration), so `0xBA` there is a server OPCODE, not
an event ID. Confirm and rule out.
- Try hooking one tier higher: `FUN_005AB650(opcode, handler)`
callers in the SMSG_UPDATE_OBJECT region might give us the
actual update path.
- Alternative architecture: skip event-driven entirely and use
`Tick::WorldTick` polling. Per-frame cost is 19 itemID reads
+ 19 compares (~negligible). User pushback on polling was
philosophical, not perf-based; might be acceptable as a
fallback if a clean hook can't be found.
### Side benefit shipped during this investigation
`Bag::InvDescChange` shared dispatcher (`src/bag/InvDescChange.{h,cpp}`)
modeled on `Tick::WorldTick::AutoSubscribe`. `Bag::UpdateDelayed`
now subscribes to it instead of owning the `FUN_004F8DB0` hook
directly. **Currently has a single subscriber so adds no value
on its own — revert if not needed for resumed work.**
### Bonus (deferred until base event works)
Same diff feeds `EQUIPMENT_SETS_CHANGED` /
`EQUIPMENT_SWAP_FINISHED` for our existing `C_EquipmentSet`
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~~ — 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
type addons and durability HUDs to avoid polling.
### Field layout (verified)
CGItem descriptor `[item + 0x114]` has:
- `+0xA0` — `ITEM_FIELD_DURABILITY` (field index `0x28`)
- `+0xA4` — `ITEM_FIELD_MAXDURABILITY` (field index `0x29`)
Both already read by `Script_GetInventoryItemBroken`
(`0x004C8590`) and by ClassicAPI's existing
`Script_GetInventoryItemDurability` in
[src/item/Durability.cpp](src/item/Durability.cpp) — so the
**read path** is mature; only the **change-detection path**
remains.
Field name strings `"ITEM_FIELD_DURABILITY"` (`0x0083D9FC`) and
`"ITEM_FIELD_MAXDURABILITY"` (`0x0083D9E0`) each have exactly
one xref — into a metadata table at `0x0083A414` (see below).
### 4.3.4 firing mechanism (won't transfer directly)
Confirmed by reading the 4.3.4 binary: there is **exactly one**
firing site for `UPDATE_INVENTORY_DURABILITY` (eventID `0x1BA`)
in Cataclysm, and it's purely server-driven:
```c
// FUN_00551580 — SMSG packet handler:
read_u32(&ctx);
read_u32(&selector);
if (ctx == 0) {
switch (selector) {
case 1: dispatch(0x1BA); // UPDATE_INVENTORY_DURABILITY
case 2: dispatch(0x1BB); // UPDATE_TRADESKILL_RECAST
case 3: dispatch(0x1BC); // OPEN_MASTER_LOOT_LIST
case 4: dispatch(0x1BD); // UPDATE_MASTER_LOOT_LIST
}
}
```
The 1.12 server doesn't send this opcode, so we can't mirror
it. The event's semantics are just "refresh durability UI" with
no payload — addons handle it by iterating equipment slots and
calling `GetInventoryItemDurability`. So we don't need to know
*which* item changed; we just have to fire when *any* equipped
item's durability changes.
### How 1.12 fires similar per-field events (open question)
`ITEM_LOCK_CHANGED` (eventID 188, slot `0xBE1488` in the input
names array) is the closest model — it fires when
`ITEM_FIELD_FLAGS` changes. Searched the binary for both `push
188 (imm8)` and `push 188 (imm32)` followed by call to the
event dispatcher at `0x00703F50` — **zero hits**. Confirms
1.12 has a generic per-field event-fire mechanism that doesn't
push the eventID as a literal.
The per-field metadata table at `0x0083A414` looks like the
right structure:
| Field | Idx | Leading dword | Other bytes |
|-----------------|-------:|--------------:|------------:|
| `ITEM_FIELD_DURABILITY` | `0x28` | `0x04` | `1, 1` |
| `ITEM_FIELD_MAXDURABILITY` | `0x29` | `0x14` | `1, 1` |
| (idx `0x27`) | `0x27` | `0x04` | `1, 1` |
| (idx `0x26`) | `0x26` | `0x01` | `1, 1` |
| (idx `0x25`) | `0x25` | `0x01` | `1, 1` |
Entry layout: `{leading_dword, name_ptr, field_idx, ?, ?}`
(stride `0x14` = 20 bytes). The leading dword varies per
entry — could be an event-fire flag, broadcast scope, or
network-stream type code. Need to find the consumer function
(table base `0x0083A414` has zero direct VA refs, so it's
consumed via base+index relative to a CGItem `m_objectFields`
metadata pointer somewhere — we don't have that pointer's
addr yet).
### Three implementation paths
1. **Per-frame snapshot polling.** Hook a per-frame engine
tick, walk 19 equipped slots each frame, hash durability,
compare, fire on change. Modest cost (19×2 reads/frame).
Hardest part: finding a clean per-frame hook point that's
not in the JIT-collision-risk class. Candidate: hook the
network packet-flush boundary (one-off per game tick,
cheaper than per-render-frame).
2. **`SMSG_UPDATE_OBJECT` handler hook.** Hook the packet
handler that applies UpdateField changes to objects.
Snapshot durabilities before, check after; fire when
different. More targeted than (1) — only fires when there's
a network reason for state to have changed. Needs the
opcode handler VA; not yet pinned down.
3. **Decode the per-field metadata table.** Reverse-engineer
the `0x0083A414` table layout to understand what the
leading dword means. If it's the event-fire mechanism the
engine already uses for `ITEM_LOCK_CHANGED` / `UNIT_HEALTH`
etc., we patch the `ITEM_FIELD_DURABILITY` /
`ITEM_FIELD_MAXDURABILITY` entries to fire our reserved
`UPDATE_INVENTORY_DURABILITY` slot. Cleanest end state,
deepest spelunking — may hit a dead end if the table's
consumer isn't where we expect.
The MinHook collision-risk memory note ("hooking high-traffic
engine functions risks JIT/trampoline corruption from
SuperWoWhook/nampower/etc.") argues against (2) since
`SMSG_UPDATE_OBJECT` is one of the hottest opcode handlers.
That pushes us toward (1) or (3). Of those, (3) is the right
end state — no per-frame overhead, fires exactly when the
engine sees a field change — but (1) is a defensible ship-
now answer with a clear migration path to (3) later.
### Cross-binary reference
When picking this back up, the 5.4.8 client (`C:\WoW\World of
Warcraft 5.4.8\Wow.exe`) is the cleanest reference — it has
the same client-side detection (UpdateField → event) but with
post-vanilla code structure. The 4.3.4 packet-driven path is
a Cataclysm-specific oddity and won't reflect what 1.15.x or
modern does.
## 90. Revisit `BAG_UPDATE_DELAYED` (TODO #67 was REVERTED)
Modern event that fires once after a storm of `BAG_UPDATE`s
settles (typically inside a single frame). Lets addons debounce
inventory-scan work without each one rolling its own timer.
Previous attempt: see #67. Reverted because the implementation
hooked something hot and caused issues. Re-attack with the
hook installed at `Frame::FireEvent` (the dispatcher we already
know) — count consecutive `BAG_UPDATE` fires per frame, and on
the first frame that has zero, fire `BAG_UPDATE_DELAYED`.
Lower risk than the previous approach since we're observing
fires rather than hooking the update path. `Event::Custom`
machinery is more mature now and matches what the EquipmentSet
module already does.
## 91. `UNIT_SPELLCAST_SENT(unit, target, castGUID, spellID)` event
The modern per-cast notification with unit + target + spellID.
Vanilla ships `SPELLCAST_START` for the player only, with just
the spell *name* — modern addons want spellID and unit info.
Player-only backport is feasible without wire-protocol work:
hook `SPELLCAST_START` fires (or the underlying engine path that
sends them), translate name→spellID via `Spell::Lookup`, pass
through with `"player"` and the current target token. Cross-unit
(party member casting) requires SMSG_SPELL_GO observation —
defer that to a "Phase 2" or skip permanently.
If we ship the player-only version, document the limitation
prominently — addons that rely on `unit ~= "player"` events
won't get them, but everything that only cares about the local
player works.
## 92. `IsItemInRange(itemID, unit)` — medium
5.4.8-era addition. Range check based on the item's "range
modifier" — long-range items (rifles, throwing weapons) report
true when the target is in firing range. Used by hunter / rogue
addons to gate ability use on item range.
Implementation: read ItemStats range index, look up in
SpellRange.dbc (already wired in `Spell::Info`), compute 3D
distance to `unit`. Same machinery as TODO #85 (IsSpellInRange)
but item-keyed instead of spell-keyed.
If we wire up the unit-position read primitive for either of
these, the other comes nearly free.
## ~~76. `C_DateAndTime.*` namespace — DONE (7 of 8)
Backport of modern's date-math namespace. Six functions are pure
`<ctime>` arithmetic over a CalendarTime table; the seventh
(`GetSecondsUntilDailyReset`) reads `Time::Server::CurrentEpoch()`
and returns `86400 - (epoch % 86400)`. Server midnight semantics
work naturally because `CurrentEpoch` treats the engine's server-
time components as UTC for the epoch conversion — day boundaries
in epoch math align with server-clock midnight.
`GetSecondsUntilWeeklyReset` deliberately omitted — vanilla has no
server-broadcast weekly reset schedule, and Turtle realms vary, so
any hardcoded weekday/hour would be wrong somewhere. Addons that
need it can compute their own value (e.g. "next Tuesday at server
midnight") via `GetCurrentCalendarTime` + `AdjustTimeByDays`.
Side effect: refactored `Time::Server::CurrentEpoch()` out of
`Script_GetServerTime` so the C++ helper is reusable.
## 71. Descriptor `+0x1320` — "last channeled spell" parking lot
During the `IsAssistingRitual` investigation, the player's
descriptor showed `+0x1320` flip from `0` to `0x2BA` (= 698 =
Ritual of Summoning) **immediately after** the channel ended,
where the active channel was at `+0x228`. So `+0x228` =
UNIT_CHANNEL_SPELL (live), and `+0x1320` looks like a "previously
channeled" stash that's populated on transition-to-zero.
Not enough data to commit to a semantic yet. Open questions:
- Does it also stash for fishing / lockpicking / mining channels?
We have one data point (the portal click) showing the behavior.
- Does it clear, and if so when? (`/reload`? Next channel? Never?)
- Is it a broadcast UpdateField or local-only?
If it turns out to be a stable "last completed channel" field, it
unlocks polyfills for the modern `UNIT_SPELLCAST_CHANNEL_STOP`
event payload (which carries the spellID that just ended) without
hooking the channel-stop code path. Lower-priority; useful but
not load-bearing for any specific API in the polyfill addon
today.
Investigation plan when picked up: snap `+0x1320` before any
channeled action, perform a clean channel, snap again immediately
after channel end (use `_classicapi_DescDump(0x1320, 4)` for a
targeted read). Repeat across several channel types and confirm
the pattern.
## 93. `C_MerchantFrame.SellAllJunkItems` — explicit cursor clear when holding junk — low
Currently, if the player has a junk item picked up on their cursor
when calling `SellAllJunkItems`, the item still sells (the CGItem
remains in its bag slot internally; we walk and find it, the sell
fires, and the engine clears the cursor as a side effect of the
item being destroyed). For non-junk on the cursor, the cursor is
left alone. The incidental behavior is actually pretty good
already — junk gets cleared, non-junk preserved.
The "clean" version would explicitly call `Script_ClearCursor`
(`0x004895B0`) at the start of `SellAllJunkItems` *iff* the cursor
is currently holding a junk item. The cursor-type global at
`[0x00B4D900]` (1 = item, 3 = ?, 9 = ?) gates "is the cursor
holding anything," but the cursor's actual itemID / GUID / bag-slot
reference isn't sitting in an obvious adjacent global — the
neighboring globals at `+0x04` / `+0x08` are unrelated floats and
pointers, not item identifiers.
Vanilla has no `GetCursorInfo` (only `CursorHasItem`), so there's
no Lua-visible accessor to crib from. Finding the cursor item
state means tracing through `Script_PickupContainerItem`'s 200+
bytes of arg-validation to locate where it stashes the picked-up
(bag, slot) tuple after pickup. Probably an hour of recon.
Defer until either:
- a user actively reports the current behavior as annoying, or
- the cursor state needs to be read for some other purpose
anyway (e.g. a `GetCursorInfo` polyfill).
## ~~94. Glue-side bindings: `GetSavedCharacterOrder` / `SetSavedCharacterOrder`~~ — DONE
Two glue-only globals for persisting the character-select reorder UI
(GlueXML port of Blizzard's anniversary drag-to-reorder). Vanilla 1.12
glue has no general-purpose persistence API — only
`GetSavedAccountName` / `SetSavedAccountName`, which is saturated by
the autologin system.
### As shipped
API (registered on the **glue** Lua state only — in-world Lua sees a
nil global, by design):
```
GetSavedCharacterOrder(realm) -> string -- "" when missing, never nil
SetSavedCharacterOrder(realm, order) -- order="" clears the entry
```
Storage: `WTF\Account\<account>\ClassicAPI.txt`, one `CharacterOrder.<realm>=<order>`
line per realm. Account scope is implicit via the file path; realm scope
is explicit via the line key. The `<order>` payload is opaque (the
GlueXML side uses pipe-delimited names). Implementation lives in
[src/charlist/Order.cpp](src/charlist/Order.cpp).
### Registration mechanics
Required three pieces of new infrastructure, all in their own commits:
1. **Glue Lua state hook** — `FUN_0046ABB0` is the master glue init
(linear caller of all 5 glue batch trampolines, single caller,
35-byte body). Hooked in [src/DllMain.cpp](src/DllMain.cpp). Fires
once per glue boot (launch + every world→glue return). Earlier
attempt at inner trampoline `FUN_0046DDF0` crashed on Octo —
smaller target, sibling-DLL collision. The linear caller is
structurally identical to our existing in-game `FUN_LOAD_SCRIPT_FUNCTIONS`
hook and has none of those problems.
2. **`Game::GlueModuleAutoRegister`** ([src/Game.h](src/Game.h)) —
parallel of the in-game `ModuleAutoRegister`. Modules opt into
glue exposure with a file-scope static. `Game::Lua::RegisterGlueFunction`
is an alias of `RegisterGlobalFunction` (the engine reads
`VAR_LUA_STATE` to route, and that pointer is the glue state for
the duration of our hook).
3. **`Settings::Account` registry** ([src/settings/Account.h](src/settings/Account.h))
— shared per-account persistence file. NameCache and Order both
register reset/serialize/parse sections; the registry handles load,
save, and account-change detection (re-loads on autologin switch
from the glue screen) in one place. Avoids each module managing
its own `WTF\Account\<acct>\*.txt` file.
### Notes for callers
- `FUN_GET_LOGIN_ACCOUNT_NAME` (`0x005ABDC0`) is misnamed in
`Offsets.h` — it actually returns `VAR_CHARACTER_NAME`. The real
account name pointer is `VAR_ACCOUNT_NAME_PTR` (`0x00BE1C0C`), which
is what Order and NameCache use.
- WoW.cfg was considered for persistence and rejected: extending the
cfg parser is more invasive than a self-managed file under WTF,
and we already have the `Settings::Account` shape.
## 95. `C_CharacterList.*` — removed; notes for a future pickup
We shipped `C_CharacterList.GetNumCharacters` /
`GetCharacterInfo(index)` / `GetCharacters()` for a while —
exposing the realm's character list (name, class, race, level,
area, sex, GUID) from anywhere in the game, not just the glue
char-select screen. The implementation was removed because the
single addon driving the need moved off it; keeping a binding
nobody calls is dead weight, and the engine-hook surface (the
char-list teardown function) is the kind of thing better owned by
whichever DLL actually uses it. The history is preserved in git
(see commits around `src/charlist/Cache.cpp`).
If another project picks this up, the work is straightforward —
no novel reversing needed:
### What the binding looked like
Three Lua entry points, all under `C_CharacterList`:
- `GetNumCharacters() -> n`
- `GetCharacterInfo(index) -> name, localizedRace, localizedClass, level, areaName, englishRace, sex, guid`
- `GetCharacters() -> { { name=, localizedRace=, englishRace=, localizedClass=, level=, areaName=, sex=, guid= }, ... }`
`guid` was the 64-bit character GUID formatted with our
`Guid::FormatAsString` helper (16 hex digits, `"0x"` prefix —
matches `UnitGUID`'s convention). `areaName` was nil when the
character's last-known area wasn't in `AreaTable.dbc`.
### Why it needed a DLL hook
Vanilla 1.12's `GetCharacterInfo` / `GetNumCharacters` are
registered on the **glue** FrameScript engine and the underlying
data at `VAR_CHARLIST_ARRAY` (`0x00B42144`) /
`VAR_CHARLIST_COUNT` (`0x00B42140`) is freed by the
char-list teardown function during the glue→world transition. By
the time addons run in-world, the array is gone and the globals
are zeroed.
The DLL hook took a snapshot of the records before the engine
freed them.
### Implementation summary
1. **Hook the teardown.** `FUN_CHARLIST_FREE` at `0x00472090` —
`__cdecl void()`, single caller (`FUN_0046AC90`, the
glue-shutdown wrapper that runs on world transition). Very
quiet hook target. Pre-hook (snapshot before the original runs);
the original then zeros the globals.
2. **Iterate the record array.** Flat array, stride `0x120`
bytes. Field offsets within each record (derived from
`Script_GetCharacterInfo` disassembly at `0x004732A0`):
| Offset | Field | Type / notes |
|--------|-------|---------------|
| `+0x00` | GUID | u64 (verified via `Script_RenameCharacter` at `0x00473520`) |
| `+0x08` | name | inline `char[]`, max 12 + NUL |
| `+0x3C` | areaID | u32, indexes `AreaTable.dbc` |
| `+0x100` | raceID | u8, indexes `ChrRaces.dbc` |
| `+0x101` | classID | u8, indexes `ChrClasses.dbc` |
| `+0x102` | sex | u8 (0/1) |
| `+0x108` | level | u8 |
3. **Cache memory-only.** Every game launch hits char-select
before world-enter, so the cache is naturally rebuilt every
session. No filesystem persistence, no staleness across
restarts, no deleted-character bookkeeping (a server-side
delete drops the entry from the next `SMSG_CHAR_ENUM`).
4. **Edge case.** If the DLL is injected mid-session
post-world-enter, the cache stays empty until the player
returns to char-select. Under normal VanillaFixes load order
that's not a concern (DLL loads before any Lua runs).
### Why we used a memory-only cache, not the persistent file
`Settings::Account` (the per-account WTF-file mechanism that backs
`GetSavedCharacterOrder`) is the wrong shape: it persists across
sessions, which would mean stale entries surviving server-side
deletes, and the data is already authoritative on each launch.
Memory-only is simpler and self-correcting.
## 96. EditBox `OnArrowPressed` script handler (+ `SetCursorPosition`) — medium
The 1.12 EditBox widget offers two arrow-key modes via the
`ignoreArrows` attribute, and both are bad for a developer console:
- `ignoreArrows="true"` — widget consumes all four arrows and uses
UP/DOWN to walk its internal `AddHistoryLine` ring. LEFT/RIGHT
then can't move the text cursor. This is what
`ChatFrameEditBoxTemplate` does, which is why you can't move the
cursor inside a WoW chat input.
- `ignoreArrows="false"` — LEFT/RIGHT move the cursor; UP/DOWN do
nothing, and there's no Lua-visible event when UP/DOWN are
pressed. The focused EditBox consumes key events before the
parent's `OnKeyDown` can fire, and no `OnArrowPressed` handler
exists on the 1.12 widget (verified in
`Blizzard-WoW-Interface/1.12.1/FrameXML/UI.xsd` — no element,
and zero hits across all of Blizzard's 1.12 FrameXML).
So Lua-driven history navigation is impossible: there's no way to
intercept UP/DOWN without also losing LEFT/RIGHT.
### Driving use case
`Octo/Interface/GlueXML/GlueConsole.lua` — the in-glue Lua console
used during glue-side development. Wants the obvious developer-
console UX: UP/DOWN to walk through recently-submitted commands,
LEFT/RIGHT to edit. An in-game Lua console (probable future
addition) wants the same thing.
### What the binding should expose
Mirror modern WoW's `OnArrowPressed` script handler:
```lua
editBox:SetScript("OnArrowPressed", function(self, key)
-- key = "UP" | "DOWN" | "LEFT" | "RIGHT"
end)
```
Fires when an arrow key is pressed while the EditBox has focus,
regardless of `ignoreArrows`. The widget's normal handling still
runs after — for `ignoreArrows="false"`, LEFT/RIGHT continue to
move the cursor; for `ignoreArrows="true"`, the built-in history
walk still happens (or we can drop the built-in history entirely
once Lua can drive it). The XML element also needs to be
registered under `EditBoxType` so `<OnArrowPressed>...</OnArrowPressed>`
parses alongside `SetScript`.
### Pair with `SetCursorPosition` / `GetCursorPosition`
After UP swaps a history line into the editbox, the Lua side
wants to drop the cursor at end-of-text rather than position 0.
3.3.5 exposes `editBox:SetCursorPosition(n)` and
`editBox:GetCursorPosition()`
([Blizzard-WoW-Interface/3.3.5/FrameXML/AutoComplete.lua:249,289](file:///c:/WoW/Blizzard-WoW-Interface/3.3.5/FrameXML/AutoComplete.lua));
1.12 has neither (zero hits anywhere in
`Blizzard-WoW-Interface/1.12.1`). Same widget, presumably the
same internal cursor field — worth exposing in the same change as
`OnArrowPressed` since the navigation UX is broken without it
(history line appears with cursor at column 0).
### Engine side — not yet researched
Likely path: hook the EditBox key-handler dispatch (whatever
function decides "is this key consumed by the widget? does it
affect the text? move the cursor?"). When key ∈ {UP, DOWN, LEFT,
RIGHT} and the EditBox has focus, fire the new `OnArrowPressed`
script before the default behavior runs.
`SetCursorPosition` is presumably a thin write to a cursor-index
field on the EditBox struct (plus whatever invalidation forces
the caret to redraw at the new position). `GetCursorPosition` is
the matching read. Both should be straightforward once the field
offset is identified — 3.3.5's `Script_*` equivalents are a good
starting point for what the parameter shape and bounds-clamp
behavior should be.
## ~~97. Lift GameTooltip's 30-line cap~~ — DONE
Shipped as [src/tooltip/LinePool.cpp](src/tooltip/LinePool.cpp): pure C++,
no addon Lua. Co-hooks the XML-OnLoad region scan (FUN_00529650, vtable
slot 9) via `Game::HookAutoRegister`; after the engine sets up the
template's 30 lines it creates `TextLeft/Right 31..60` in C++ (alloc →
ctor → name → font-copied-from-prev → anchor, offsets scaled pixel →
internal like Script_SetPoint) and appends them to the tooltip's three
line arrays, bumping `numLinesAllocated`. Runs once per GameTooltip-family
frame at creation + per `/reload`, so it auto-covers GameTooltip,
ShoppingTooltip1/2, ItemRefTooltip, AtlasLootTooltip, WorldMapTooltip, …
Verified in-game: AtlasLoot tooltip rendered a 31st line correctly. Cap is
`kMaxLines = 60`. The design notes below record the RE trail; Approach A
(hook AddLine) / Approach B (addon Lua) were both explored and dropped in
favor of the scan-hook.
Vanilla 1.12's `GameTooltip:AddLine` silently drops any line past the
pool of `TextLeftN`/`TextRightN` FontStrings the XML template
pre-declares (30). Modern (3.3.5+) engines grow the pool on demand.
Addons that append comparison summaries, item-info footers, or aura
details to a full item tooltip get their tail chopped. Practical
example — pfUI's eqcompare block (base-stat deltas inline + extended
stats appended at the bottom) hits the cap on stat-heavy items where
the vendor tooltip already has ~22 lines and the compare block adds
another 10; extended-stat rows past line 30 disappear silently.
Also affects `ShoppingTooltip1`/`ShoppingTooltip2` (same
`GameTooltipTemplate`).
### Root cause (verified in Ghidra on the 1.12 Octo binary)
`AddLine` internal impl at `FUN_00530270` — the shared body called
from both `Script_GameTooltipAddLine` (`FUN_00531630`, method ptr
stored in the GameTooltip method table alongside the `"AddLine"`
string at `0x00854560`) and `Script_GameTooltipAddDoubleLine`:
```c
void FUN_00530270(int this, char *leftText, char *rightText,
colorLeft, colorRight, wrapFlag) {
if ((*(int *)(this + 0x31c) != *(int *)(this + 0x320)) && anyHasText) {
// set leftText on textLeft[numLines_used],
// set rightText on textRight[numLines_used],
// wrapFlag[numLines_used] = wrapFlag,
// ++numLines_used
}
// else: silently drop the line
}
```
`0x320 == 800` decimal, matches decompile. Pool exhausted ⇒ nothing
happens.
### CGameTooltip struct offsets (1.12)
Derived from `FUN_00530270` and the pool-init at `FUN_00529650`:
| Offset | Field |
|--------|----------------------------------------------------|
| `+0x31c` | `numLines` — current write index (0-based) |
| `+0x320` | `numLinesAllocated` — pool size (30 default) |
| `+0x328..+0x32c` | `textLeft[]` — array of `CSimpleFontString *`, count `+0x320` |
| `+0x334..+0x338` | `textRight[]` — same, symmetric right column |
| `+0x340..+0x344` | `wrapFlag[]` — per-line wrap bool |
Actual layout of the array slots: `+0x328` is the first ptr in an
external heap block whose base is `param_1[0xcb]` = `+0x32c`. The
init function reallocates all three arrays whenever `numLinesAllocated`
would change — see `FUN_00536c80` (the reallocator) and `FUN_004368c0`
(a matching alloc for the wrap-flag array of a different element size).
### The pool-init function
`FUN_00529650` — walks `%sTextLeftN` / `%sTextRightN` FontString names
from the FrameXML-declared pool, counts them, reallocates the three
arrays, stores the pointers. Called via vtable slot at `0x00808f84`
(only xref) — likely `SetOwner` or an equivalent virtual reset method
runs it. It's the natural growth path — if we can force it to see a
larger pool of Lua-visible FontStrings and trigger it, the arrays
resize themselves.
### The 3.3.5 reference (already REd)
3.3.5's `GameTooltip::AddLine` at `0x0061fec0` has the grow-on-demand
branch we want to backport. Shape:
```c
if (currentLine == numLinesAllocated - 1) {
format(buf, 256, "%sTextLeft%d", tooltipName, currentLine + 1);
auto *fs = SimpleFontString::create(this, /*layer*/2, /*subLayer*/1);
fs->setName(buf);
fs->setFontObject(prevLeft->fontObject);
fs->anchor(TOPLEFT, prevLeft, BOTTOMLEFT, 0.0, calculatedYOffset);
// ... mirror for TextRight ...
// ... append fs to textLeft[]/textRight[] at [numLinesAllocated],
// then ++numLinesAllocated.
}
// fall through to the existing "set text on line[currentLine]" path
```
3.3.5 helpers (offsets 3.3.5-specific — 1.12 equivalents need to be
re-derived):
- `FUN_00485240` — SimpleFontString constructor `(parent, layer, sublayer)`
- `FUN_0048b6c0` — set-name helper (registers under global `_G[name]`)
- `FUN_0048a260` — anchor helper `(this, anchorPoint, relativeTo, relativePoint, xoff, yoff)`
Struct offsets in 3.3.5 were `+0x2a4` (numLines) / `+0x2a8` (numAlloc) /
`+0x2b4` (textLeft) / `+0x2c0` (textRight) / `+0x2cc` (wrapFlag). All
shifted vs. 1.12 (see above), unsurprising given TBC/WotLK bloat.
### Implementation plan
**Approach A — pre-hook AddLine with a grow-if-needed prelude
(preferred)**:
1. Locate the 1.12 equivalents of the three 3.3.5 helpers. Trace them
from existing `CSimpleFontString`-creating sites in the engine —
the CreateFontString API dispatch is a good starting point (it's
Lua-visible and calls the same constructor).
2. Locate the array reallocators used by `FUN_00529650`
(`FUN_00536c80` for the two pointer arrays, `FUN_004368c0` for the
wrap-flag byte array).
3. MinHook `FUN_00530270`. Pre-hook body:
- If `numLines != numLinesAllocated`, call original — done.
- Otherwise: realloc the three arrays to `numLinesAllocated + 1`,
create two new `CSimpleFontString` (left + right), name them
`"%sTextLeft%d"` / `"%sTextRight%d"` with `tooltip->GetName()` and
the new index, anchor each below the prior-slot FontString on the
same side, use the prior FontString's `fontObject` (`+0xd8` in the
3.3.5 layout — confirm on 1.12) as the default, write the pointers
into `textLeft[numLinesAllocated]` / `textRight[numLinesAllocated]`,
zero-init `wrapFlag[numLinesAllocated]`, and bump
`numLinesAllocated`.
- Then tail-call the original — it now succeeds normally.
**Approach B — pre-declare a wider pool via Lua** (fallback if the
constructor helpers turn out to be too tangled):
1. In `!!!ClassicAPI` addon, at load time, call
`GameTooltip:CreateFontString("GameTooltipTextLeft" .. i, "ARTWORK",
"GameTooltipText")` for `i = 31..60`, plus `TextRightN`, plus set
anchors matching the pattern in the template.
2. Force the engine's pool-init to re-scan. If we can't reach the
vtable trigger cleanly, expose a small C entrypoint that walks the
pool the same way `FUN_00529650` does — takes `tooltip` as arg,
reallocates arrays, refills.
Approach B is less code but ties the cap to a fixed number (60 lines
is enough for pfUI's use case but arbitrary). Approach A grows on
demand like retail and has no ceiling.
### Testing
- Hover a random-suffix weapon with several equip-spell bonuses (Krol
Blade, Ironfoe, any ZG/AQ trinket) — tooltip should render >30 lines
without truncation.
- Hover an item that produces a 40+ line tooltip when pfUI's eqcompare
block is enabled (Priest Judgement Set chest against another
Judgement chest: item tooltip ~22 lines + compare block ~10 lines).
- Verify no crash / no visual glitches on:
- ShoppingTooltip1/2 (same class, same `GameTooltipTemplate`)
- Rapid re-hovers (create/destroy pressure on the added FontStrings)
- Item tooltips that stay under 30 lines (pre-existing behavior unchanged)
### Risks
- If the array reallocation logic in `FUN_00536c80` doesn't null-out
the tail on grow, `textLeft[N]`/`textRight[N]` might contain
garbage for a frame — anchor before write, or memset to zero.
- FontString lifetime: 3.3.5 leaks the extras for the tooltip
lifetime (they stay hidden when unused). GameTooltip is a
singleton, so leak is bounded. Fine.
- Interaction with `pfUI`'s existing tooltip skinning (frame borders,
status bar reposition, etc.): the layer we're modifying is beneath
the skinning; shouldn't touch anything visible unless anchor math
is wrong.
### Related
If we ever consider dropping the whole "GameTooltipTemplate declares
30 FontStrings in XML" scheme and instead having the engine start
with 0 and grow entirely on demand — that would be even cleaner, but
requires patching every consumer of the initial pool (there aren't
many, but they need audit). Filed for future if the incremental grow
turns out to be fragile.
### Investigation update (resolved unknowns)
Traced the pool machinery end-to-end. The open questions above are now
answered, and they point away from both the AddLine hook (Approach A)
and the "trigger the engine's scan" idea — a **hybrid** is cleaner than
either.
**The scan is virtual slot 9, run only at XML-template instantiation.**
`FUN_00529650` is slot 9 (`vtable+0x24`) of the CGameTooltip vtable
(base `0x00808f60`; the null at `0x00808f5c` is the boundary, and slot 2
`0x005368d0` is the `tooltip:method()` dispatcher — confirms the class).
The two vtable-base xrefs are the constructors `FUN_00529240` /
`FUN_00529480`. The scan's prologue calls
`FUN_0076a2f0(node) → FUN_0076a060(node)`, which reads the XML
`"inherits"` attribute and child `"Frames"` — i.e. the scan is the
frame's **XML OnLoad / region-setup** virtual. It runs once when
`GameTooltip` is built from `GameTooltipTemplate` (and again per
`/reload`), **not** on `SetOwner`/show. So we can't cheaply re-trigger
it — the `node` arg is a live XML-parse handle we don't have, and
calling it with a bogus node runs the inherits/Frames path on garbage.
**The scan finds lines by `_G[name]`, so Lua-created FontStrings count.**
`numLinesAllocated` (`+0x320`) is literally "how many contiguous
`%sTextLeftN` **and** `%sTextRightN` exist by name": pass 0 counts (stop
at the first missing index), pass 1 reallocs the three arrays to that
count and fills the pointers. The name lookup `FUN_0076c760` does
`lua_pushstring(name); gettable(_G); if type==TABLE: FrameScript_GetObject`
— a plain `_G[name]` resolve, so a FontString made with
`GameTooltip:CreateFontString("GameTooltipTextLeft31", …)` **is**
visible to it. (Names must be contiguous and exist in *both* columns.)
**The array reallocators are simple and callable from C.**
`FUN_00536c80` (pointer arrays) and `FUN_004368c0` (wrap-flag array) are
the same routine with different SMem tags:
`__thiscall(descriptor, newCount)` where the descriptor is
`{ count@+0x0, cap@+0x4, data@+0x8 }` — reallocs `data` to `newCount*4`
and copies the old contents. In the tooltip the three descriptors are:
| Descriptor `this` | count / cap / data | array |
|-------------------|--------------------|-------|
| `tooltip + 0x324` | `+0x324 / +0x328 / +0x32c` | `textLeft[]` (`CSimpleFontString*`) |
| `tooltip + 0x330` | `+0x330 / +0x334 / +0x338` | `textRight[]` |
| `tooltip + 0x33c` | `+0x33c / +0x340 / +0x344` | `wrapFlag[]` (int, 4-byte) |
`numLinesAllocated` (`+0x320`) is a separate field the scan sets equal
to the count; AddLine (`FUN_00530270`) gates on
`numLines(+0x31c) != numLinesAllocated(+0x320)`.
**Recommended approach — Lua creates FontStrings, C grows the arrays
(no hook, no XML re-run).** Replicate the scan's pass 1 directly:
1. **Lua (`!!!ClassicAPI`), at load / `PLAYER_LOGIN`:** for each frame on
`GameTooltipTemplate` (`GameTooltip`, `ShoppingTooltip1/2`,
`ItemRefTooltip`, …), create `<name>TextLeft31..N` and
`<name>TextRight31..N` via `frame:CreateFontString(nm, "ARTWORK",
"GameTooltipText")`, each anchored `TOPLEFT`/`TOPRIGHT` to the prior
line's `BOTTOMLEFT`/`BOTTOMRIGHT` (mirror the template's chain).
This avoids re-deriving the 1.12 FontString ctor / setName / anchor
helpers that Approach A needed — Lua already wraps them.
2. **C entrypoint** `GrowTooltipPool(tooltipObj, newCount)` (expose as a
Lua global, called once per frame right after step 1):
- `FUN_00536c80(tooltip+0x324, newCount)`; set `+0x328 = newCount`.
- `FUN_00536c80(tooltip+0x330, newCount)`; set `+0x334 = newCount`.
- `FUN_004368c0(tooltip+0x33c, newCount)`; set `+0x340 = newCount`.
- for `i` in `[oldAlloc, newCount)`: resolve `<name>TextLeftN`/
`RightN` via the `_G[name]` dance (same as `FUN_0076c760`), and if
either is missing stop at `i`; else write the two pointers into the
new `textLeft`/`textRight` data slots and zero `wrapFlag[i]`.
- set `numLinesAllocated (+0x320) = i`.
Resolve `tooltipObj` from the Lua frame the same way our other
tooltip methods do (`FrameScript_GetObject`).
Runs once per frame per session (re-runs on `/reload`, which recreates
the frames → scan resets to 30 → our addon re-creates + re-grows). No
per-line hook (dodges the MinHook-collision risk on a moderately hot
function), no XML-node fabrication.
Remaining risk to validate in-game: whether AddLine's downstream layout
/ `Show` sizing walks `numLines` FontStrings by their anchors (expected)
vs. any hidden fixed-30 assumption elsewhere; and that the Lua-created
lines inherit height/spacing identical to the template's 1..30 so the
tooltip grows seamlessly. Both are observable on the first >30-line
hover.
## 98. `UnitThreatSituation` / `UnitDetailedThreatSituation` / `GetThreatStatusColor` — NOT FEASIBLE in a client DLL
Modern (WotLK+) exposes three threat APIs:
[`UnitThreatSituation`](https://warcraft.wiki.gg/wiki/API_UnitThreatSituation)
(unit → 0..3 aggro status),
[`UnitDetailedThreatSituation`](https://warcraft.wiki.gg/wiki/API_UnitDetailedThreatSituation)
(isTanking, status, threatPct, rawThreatPct, threatValue), and
[`GetThreatStatusColor`](https://warcraft.wiki.gg/wiki/API_GetThreatStatusColor)
(status → RGB). None of them can be backed by ClassicAPI, because
**the underlying data does not exist on the 1.12 client** — not in a
form a DLL can read, and not by any amount of RE.
### Threat is 100% server-authoritative in vanilla; no threat opcode exists
Vanilla 1.12's threat lives entirely inside the server's
`ThreatManager` (per-creature `ThreatList` of `HostileReference`s —
see Turtle's
[`src/game/Threat/ThreatManager.cpp`](C:\Git\turtle-wow\Dumps\Source%20Code\16%20-%20Development_server\patch_1172\src\game\Threat\ThreatManager.cpp)).
The 3.3.5 client can show a threat meter because WotLK added
`SMSG_THREAT_UPDATE` / `SMSG_HIGHEST_THREAT_UPDATE` (and the client
keeps a per-unit threat table those packets feed). **1.12 has no such
opcode** — the protocol never transmits per-unit threat values, so
there is nothing in client memory to read. This is the same class of
limitation as `C_QuestLog.IsQuestFlaggedCompleted` (TODO #1): the
client simply isn't told. Unlike cast timing (TODO #91, recoverable
from `SMSG_SPELL_START`) or aura casters (recoverable from
`SMSG_SPELL_GO`), there is **no incidental packet** that leaks threat
either — the server computes tanking/aggro decisions internally and
broadcasts none of the numbers.
### How Turtle actually does it — a *server-side* addon-channel protocol
TWThreat (`C:\WoW\Octo\Interface\Addons\TWThreat`) is not reading
client memory; it round-trips through a **custom server patch**:
1. Client → server: the addon `SendAddonMessage("TWT_UDTSv4"[.._TM],
"limit=NN", "PARTY"/"RAID")` — a normal `CMSG_MESSAGECHAT` addon
message (`TWThreat.lua:1207` `TWT.UnitDetailedThreatSituation`).
2. Server intercepts the prefix in
[`ChatHandler.cpp:1051`](turtle-wow\Dumps\Source%20Code\16%20-%20Development_server\patch_1172\src\game\Handlers\ChatHandler.cpp)
(`strstr(msg, "TWT_UDTSv4")`), validates
`GetSelectedCreature()->CanHaveThreatList()`, and calls
`ThreatManager::UnitDetailedThreatSituation(creature, player, limit,
tankMode)`.
3. That serializer (`ThreatManager.cpp:441`) walks the real
`getThreatList()` and builds a `TWTv4=name:pct:threat;…` string,
then `SendAddonMessage`s it back.
4. Client parses it in `CHAT_MSG_ADDON` → `TWT.handleThreatPacket`
(`TWThreat.lua:790`).
Every threat number the meter shows originated on the server and was
put on the wire by a server-side code change ClassicAPI has no
counterpart to. A client DLL cannot manufacture data the server never
sends.
### Even where a server *does* expose it, the transport is async
The Turtle path is a request/response over the addon chat channel —
fundamentally asynchronous (poll on `OnUpdate`, handle the reply on a
later frame). It cannot back a **synchronous** `UnitThreatSituation()`
that returns a value in the same call, which is exactly why TWThreat is
structured around events and a cached `TWT.threats` table rather than a
blocking query. A ClassicAPI shim would at best have to fake a
synchronous return from a stale cache, and the cache only exists if a
Turtle-style server is feeding it — i.e. the shim would add nothing the
addon isn't already doing in Lua.
### `GetThreatStatusColor` is the only client-pure piece — and it's trivial Lua
`GetThreatStatusColor(status)` is just a fixed 0..3 → RGB map (grey /
yellow / orange / red); no engine data involved. But it's meaningless
without a real `status` to feed it, and it's a two-line Lua table
lookup — no reason to spend a DLL global on it. If we ever ship a
threat polyfill it belongs beside the (Lua, server-dependent) status
source, not in the DLL.
**Verdict:** skip all three. The data is server-only with no vanilla
opcode, the only working implementation (Turtle) is a server patch plus
an async addon-channel protocol that lives correctly in Lua, and the
one client-pure function is a trivial color table. Nothing here is a
client-DLL problem.
### If we synthesized it anyway
"Can't read it" and "can't estimate it" are separate claims. We can't
read threat (above); *estimating* it is possible, but it splits into two
tiers, and neither one is a DLL feature.
**Tier 1 — client-only proxy from the mob's target (small, honest,
nearly useless).** The one threat-correlated fact vanilla *does* sync to
the client is the creature's current target (`UNIT_FIELD_TARGET` in the
descriptor — the same field `"<mob>target"` / `targettarget` reads). A
mob attacks its highest-threat valid target, so `mobTarget == unit` ≈
"unit is tanking". That yields:
- `UnitThreatSituation(unit, mob)` → `3` when the mob targets `unit`,
else `nil`. It **cannot** produce `1` ("higher than tank, about to
pull") or distinguish `2` from `3` — those are numeric comparisons and
we have no numbers.
- `UnitDetailedThreatSituation` → `isTanking` only; `status` degenerate,
`threatpct` / `rawthreatpct` / `threatvalue` all unavailable.
- Laggy: it changes only when the mob switches target (a descriptor
update), so it *trails* real threat and gives zero predictive warning
— the entire reason a threat meter exists.
This needs no DLL: `UnitIsUnit("<mob>target", unit)` already does it in
pure Lua. Shipping it under the real API names would be actively
misleading (callers expect the 0–3 gradient plus percentages), so it's
not worth it even as a stub.
**Tier 2 — a real threat model (accurate-ish, huge, cooperative, ~95%
Lua).** This is what KTM / KLHThreatMeter / vanilla-Omen actually do, and
the only synthesis that fills the percentage/prediction dimensions the
API is *for*:
1. **Model your own threat.** Parse your outgoing combat events and
convert them to threat via a per-spell coefficient database (damage ≈
1 threat per point, healing ≈ 0.5/HP applied to *every* mob in combat,
flat-threat abilities like Sunder Armor / Demo Shout, per-spell
bonus/penalty coefficients), then apply your active multipliers —
stance/form (Defensive 1.3×, Berserker 0.8×, Bear/Cat), Righteous Fury
(+Holy threat), Blessing of Salvation (0.7×), threat-reduction
trinkets — and handle the sets/wipes: taunt (sets you to current top),
Feign Death, Vanish, Fade, Cower.
2. **Broadcast** your per-mob estimate over `SendAddonMessage` and
**aggregate** everyone else's broadcasts into a per-mob table.
3. Derive `isTanking` / `status` / the percentages by comparing each
member to the current tank against the **110% melee / 130% ranged**
pull threshold — the exact constants both Turtle's server serializer
(`ThreatManager.cpp:494`, `threatValue*100 / (tankThreat * (isMelee ?
1.1 : 1.3))`) and TWThreat's client fallback (`TWThreat.lua:932`)
use. Worth stealing verbatim so a synthesized `threatpct` lines up
with what real-threat clients show.
Why it isn't ours to build:
- The coefficient DB is **game-knowledge, not in the binary** — you
cannot RE it out of the client; it's the classic hand-maintained
Threat-1.0/KTM data. The parsing, broadcast, and aggregation are all
Lua. The talent/aura/stance *inputs* are already exposed by existing
ClassicAPI functions (`GetTalentInfo`, the aura APIs, `IsPlayerSpell`,
the spell-mod reads). **None of it is a client-DLL problem.**
- **Cooperative-only.** You can precisely model only members running the
same addon and broadcasting; a non-participating tank is invisible (the
original KTM caveat). The intuitive objection — "I can see everyone's
damage in the combat log, why can't I model them from one client?" —
fails for three compounding reasons, none liftable by the DLL:
1. **You don't actually see everyone's events.** Vanilla's combat log
is visibility/range-gated — the server only broadcasts combat events
for units near you, not the whole raid. A stacked 5-man logs most of
it (so a single-observer model degrades *gracefully* in dungeons); a
spread 40-man leaves you blind to the ranged camp, the back-line
healers, anyone outside your bubble. The DLL can't recover these —
the server never sends the packets, so there's nothing to hook.
2. **Threat ≠ damage, and the missing factor is hidden.** Threat is
`damage × stance × talents × buffs`, not 1:1. The talent factor
(Defiance, Subtlety, Feral Instinct, Shadow Affinity, Frost
Channeling — the passive threat-mod talents) is **unreadable for
other players in vanilla**; there's no inspect path to it. Stance /
Blessing of Salvation / Fade are at least observable auras when the
unit is in range, but talents are pure hidden state, so an observer
can't derive a stranger's coefficient from their damage.
3. **Much threat has no attributable log line.** In-combat healing
generates threat on *every* mob the healer is engaged with (not the
mob the heal touched); buffs / HoTs / PW:Fortitude, flat-threat
abilities, and pet threat either don't appear in the log or can't be
pinned to the right mob from a single line.
Broadcasting sidesteps all three because each client computes threat
from *private, authoritative* knowledge — its own exact casts, its own
talents, its own active stance/buffs — then shares the finished number.
The Tier-1 mob-target read is worth keeping here *only* as a cross-check
— it reveals who actually holds aggro regardless of who's broadcasting.
- **It's an estimate that drifts.** Addon threat models desync from the
server's true numbers (rounding, unmodeled effects, out-of-range or
missed events). That drift is precisely why Blizzard later added
`SMSG_THREAT_UPDATE` and why Turtle chose a server serializer over
blessing an addon guess.
**The only DLL-shaped angle — and it's an *input*, not threat.** The one
place a DLL beats Lua is the feed: vanilla's combat log is localized text
keyed by unit *name* (ambiguous with duplicate names, breaks per-locale).
Hooking the damage/heal packet handlers (`SMSG_SPELLNONMELEEDAMAGELOG`,
`SMSG_ATTACKERSTATEUPDATE`, `SMSG_PERIODICAURALOG`) to emit precise,
GUID-keyed, unlocalized damage/heal events would make any Lua threat
model far more robust. But (a) that's a **separate feature** — a
`COMBAT_LOG_EVENT`-style feed, useful well beyond threat — that should be
filed on its own merits; (b) it still only *feeds* the Lua model — threat
stays an estimate, computed cooperatively in Lua; and (c) on the actual
target environment SuperWoW already exposes GUID-keyed combat info +
`UNIT_CASTEVENT`, so even this niche is largely pre-filled.
**Bottom line on synthesis:** Tier 1 is a Lua one-liner too degenerate to
wear the API's name; Tier 2 is a full KTM/Omen reimplementation that is
almost entirely Lua data + logic, cooperative-only, and inherently an
estimate. Anyone who wants vanilla threat should run an existing threat
addon. ClassicAPI's only worthwhile contribution in this space is an
unrelated precise-combat-log event feed — filed as its own thing, not as
"threat".
## 99. `C_AddOns.GetAddOnLocalTable(name)` — gate on loaded + opt-in TOC flag — DONE
Shipped gated (branch `feat/lua-syntax-transpile`,
[src/addons/LocalTable.cpp](src/addons/LocalTable.cpp)). Returns the addon's
private namespace table **only** when BOTH hold, else `nil`:
1. the addon `name` is **loaded** (`FUN_ADDON_IS_LOADED`, by-name), and
2. its `.toc` declares `## AllowAddOnTableAccess: <nonzero>` (scanned via
`FUN_FILE_READ` on `Interface\AddOns\<name>\<name>.toc`, read as a TOC
boolean flag; approach (a) from the notes below — no parser hook).
The two paths stay separate, as required:
- **Internal** `__addonns` (the `local name, ns = ...` preamble) stays
**ungated** — an addon always gets its own namespace. Still in
`luasyntax/Transpile.cpp`.
- **Public** `C_AddOns.GetAddOnLocalTable` carries the gate, in
`addons/LocalTable.cpp`.
Both resolve to the SAME table per addon via `LuaSyntax::PushAddonNamespace`
(the one owner of the registry-backed name→table map, exposed by
[src/luasyntax/AddonNamespace.h](src/luasyntax/AddonNamespace.h)) — so an addon
reads back exactly what it (or its files' `...`) stored.
Directive spelling + function name verified present in the 1.15.8 Classic Era
binary (`AllowAddOnTableAccess:` TOC key, `GetAddOnLocalTable`).
Deliberate scope choices (revisit only if an addon needs otherwise):
- **Name (string) input only.** A numeric index returns `nil` — cross-addon
table access is by name, and the map is name-keyed. Every other `C_AddOns.*`
wrapper accepts name-or-index; this one does not.
- **`nil` on denial, not a Lua error.** Matches the project's modern-API
convention (nil over `lua_error`). Retail may raise instead; switch the
denial branches to `Game::Lua::Error` if strict parity is wanted.
- **No per-name cache** on the TOC scan — GetAddOnLocalTable is not a hot path.
Not shipped by default: no addon opts in yet. The embedded `!!!ClassicAPI`
addon could add `## AllowAddOnTableAccess: 1` to its `.toc` to expose its own
namespace as a worked example, but that's a product/security decision left to
the maintainer.
## 100. Self-documenting API + `/classicapi` browser — SHIPPED (first slice)
`docs/API.md` is 18.7k lines and its anchors are signature slugs, so a
signature edit breaks the 281 internal + 88 README links into it. Blizzard
solved the same problem by shipping the API as DATA
(`Blizzard_APIDocumentationGenerated`: one table per system with typed
`Functions` / `Events` / `Tables`) plus a browser addon
(`Blizzard_APIDocumentation`, the `/api` command). warcraft.wiki.gg's
Arguments/Returns blocks are those same tables rendered by a bot — so one set
of descriptors feeds the in-game browser, a page generator, and a drift check.
**Shipped in this round**
- `namespace Game::Doc` in [src/Game.h](src/Game.h) — `Field` +
`Req`/`Opt`/`Vararg`, `FieldList`, `Function`, `Method`, `Structure`,
`Event`. Constant-initialized `const` objects; no heap, no dynamic init.
- A trailing descriptor argument on all six `Game::Lua::Register*`, and on
`Event::Custom::AutoReserve`. Zero changes inside any `Script_*`.
- [src/api/Documentation.cpp](src/api/Documentation.cpp) — records every
registration on the first pass of each Lua state, derives systems, and
exports `C_APIDocumentation.GetSystems()` / `GetSystem(name)` lazily in
Blizzard's exact table shape, plus `_classicapi_UndocumentedAPI()`.
- `AddOns/!!!ClassicAPI/APIDocumentation/` — the 8-file port of
`Blizzard_APIDocumentation`, driven by `/classicapi` (short `/capi`).
Named for what it documents: the browser holds only ClassicAPI's own
surface, so `/api` would have over-promised.
- `Util/LinkUtil.lua` — the `SetItemRef` → `LinkUtil.ProcessLink` dispatch,
wiring up a `RegisterLinkHandler` registry that had been dead code. Any
future link type now registers a handler instead of stacking another
`SetItemRef` override. Also fixed `assertsafe` being undefined there.
- Documented: the whole `C_Spell` / `C_SpellBook` surface, the spell globals
(`SpellGlobals`), the two SpellBook enums, the 13 `UNIT_SPELLCAST_*`
events, `GameTooltipAPI` (frame-method example), and `C_Glue` (glue and
mixed-environment example).
**The remaining sweep.** `_classicapi_UndocumentedAPI()` is the worklist —
~700 registrations across ~46 namespaces. Do it a namespace at a time; the
descriptor goes beside the registration and must be written against the
`Script_*` BODY, not against `docs/API.md` (which is already stale in
places — `IsHarmfulSpell` / `IsHelpfulSpell` describe an `AttributesEx` bit
read that the code does not do; it walks the effects' implicit targets).
`tools/New-ApiDocSkeletons.ps1` emits paste-ready skeletons from the 207
single-line `Usage:` strings + the API.md headings, with `// TODO` on every
guess — a starting point to verify, never to paste blind.
When the sweep finishes, delete the `= nullptr` / `= 0` defaults from the six
registrar parameters: a registration without a descriptor then fails to
compile, which is the whole point of putting the descriptor at the call site.
**Then, not before:** an `ExportAPIDocumentation` console command (glue-
registered like `ExportInterfaceFiles`, writing one Blizzard-format `.lua`
per system plus `Undocumented.txt`), a CI diff of the committed copies to
catch descriptor drift, and a Markdown/wiki generator to replace the
hand-maintained `docs/API.md` — the reason the descriptors exist at all.
## 101. `Frame:SetOnUpdateMode(mode)` + `Enum.OnUpdateMode` — medium
```
Frame:SetOnUpdateMode(onUpdateMode) -- Enum.OnUpdateMode
0 Disabled no OnUpdate, visible or not
1 RunWhenVisible the vanilla behaviour (default)
2 RunWhenVisibleOnce run once while visible; resets to Disabled BEFORE running
3 RunOnce run once regardless of visibility; resets to Disabled BEFORE running
4 RunAlways run regardless of visibility
```
"Resets before running" is load-bearing: the handler re-arms by calling
`SetOnUpdateMode` again from inside itself.
**Engine (verified 2026-09-15).** The per-frame dispatcher is `FUN_0076B2C0`,
`__thiscall(frame, float elapsed)` at vtable `+0x38`, present in every frame
vtable with subclass overrides chaining into it (same shape as the click
vmethod `FUN_00779540`):
```c
if (frame[0x128] != 0) // the OnUpdate slot
FUN_007026F0(frame, frame + 0x128, "%f", elapsed); // fmt @0x00835160
```
The walk is `FUN_00765650`: nine strata buckets of an intrusive list
(`frame+0x310` = next, saved into the bucket before each call so a handler may
unlink itself), calling `vtable+0x38` per node — with **no visibility check in
the loop and none in the dispatcher**. Visibility is therefore *list
membership*, not a test, and that list is the per-strata render list, so a
hidden frame is simply absent. Contention: a literal scan of every DLL in
`dll\` + `dll_local\` finds no reference to `FUN_0076B2C0` or `FUN_00765650`.
**Design.** Modes 0/1/2 need only a co-hook on `FUN_0076B2C0` — mode 0 returns
without calling the original, mode 2 sets Disabled then calls it, mode 1 is the
engine unchanged. Guard the detour on an empty mode map so non-users pay a
compare.
Modes 3/4 cannot come from that hook: the frame is not in the walk's list while
hidden, and forcing membership would put it in the RENDER list (it would try to
draw). Drive them from `Tick::WorldTick` instead — an already-owned hook, so no
second MinHook — calling the engine's own `FUN_0076B2C0(frame, elapsed)` so the
handler sees exactly the fire it normally would, with a per-tick mark set by the
hook so a *visible* `RunAlways` frame is not dispatched twice.
**Open question before writing it:** the `elapsed` for the self-driven modes.
The walk receives it from its caller; cleanest is to capture it in the hook (one
value per pass, shared by every frame) and reuse it, falling back to a
`Time::Clock` delta when nothing visible ran that frame. Needs checking whether
`Tick::WorldTick` (`FUN_0066FD50`, the world subsystem) runs before or after the
UI pass, which decides whether the captured value is this frame's or last
frame's.
**Cost:** one new MinHook (uncontended, guarded to ~zero when unused), one
WorldTick subscriber, a frame-keyed mode map, `Enum.OnUpdateMode`, and
`SetOnUpdateMode` / `GetOnUpdateMode`.
**Value, honestly.** `RunAlways` is the only genuinely new capability — a hidden
frame currently cannot run OnUpdate at all, which is why addons keep a
permanently-shown dummy frame for their tickers. `Disabled` duplicates
`SetScript("OnUpdate", nil)` and `RunOnce` overlaps `C_Timer.After(0, …)`, so
the rest is API parity. Worth it for the one capability plus a clean enum, not
as a performance feature.