* FocusUnit
* UnitTokenFromGUID: place focus after target, not after mouseover
Retail's documented scan order is
player -> vehicle -> pet -> party -> partypet -> raid -> raidpet
-> nameplate -> arena -> arenapet -> boss -> target -> focus
-> npc -> mouseover -> softenemy -> softfriend -> softinteract
Earlier commit placed focus at the very end. Moves it into the
target-adjacent slot so a focused unit reverse-resolves to "focus"
the moment it isn't also "target", matching retail.
---------
Co-authored-by: Brues <5278969+brues-code@users.noreply.github.com>
Extend EncodeBagSlot with two new branches matching vanilla's bagID
conventions:
- bagID = -1 -> main bank (24 slots at linear 39..62, container =
player GUID; same shape as backpack with a +38 offset instead of
+22).
- bagID = 5..10 -> equipped bank bags (containers at equipment slots
64..69; same shape as equipped bags with the index range shifted).
Both paths require the bank window to be open in the current
session — the engine doesn't sync bank-side CGContainers or bank
inventory entries before then, so ResolveEquipmentSlot returns null
and EncodeBagSlot bails cleanly. Same constraint
GetContainerItemInfo has on bank IDs.
Now that the engine recognizes `nameplateN` tokens (via the resolver
hook in nameplate/TokenResolver.cpp), they belong in the reverse-
lookup walk too. Iterates the dense ordered list directly via
NamePlate::Events::GetGUIDByIndex — bails on the first zero return,
skipping the token-resolver + SStrCmpI cost per index.
* C_NamePlate.GetNamePlateGUIDs
* fixed NameCache header
* C_NamePlate.GetNamePlates
* GetNamePlates will show blizzard nameplates as well
* C_NamePlate.GetNamePlateForUnit
* nameplate events
* C_NamePlate.GetNamePlateForGUID
* NAME_PLATE_CREATED now sends frame as argument
* document verification provenance for nameplate-adjacent offsets
- Offsets.h: annotate LUA_REF_REF / LUA_REF_UNREF with their Ghidra
decompile shapes (FREELIST_REF chain + LUA_REFNIL/NOREF sentinels)
so the next maintainer doesn't have to re-derive whether these are
really luaL_ref/unref.
- Walk.h: warn that the 0x00B41414 player global overlays multiple
sub-objects; reading +0x1C/+0x24 here is safe, feeding it to the
inventory path crashes.
* harden nameplate frame push against stale registry refs
PushNamePlateFrame now type-checks the rawgeti'd value; on a stale
slot (post-/reload windows, freed slot, etc.) it pops and falls back
to a fresh wrapper instead of returning whatever the registry happens
to hold at that index in the new Lua state. Script_GetNamePlates now
routes through the same helper so it inherits the guard.
Also document the bound on g_seenPlates: pool reuse via DAT_00c4d920
caps it at the session's peak simultaneous-plate count.
* support nameplateN unit tokens
Hook FUN_TOKEN_TO_GUID so every Script_Unit* (UnitName, UnitGUID,
UnitHealth, UnitClass, UnitExists, ...) accepts `nameplateN` tokens
and their `target`-suffix chains (`nameplate1target`,
`nameplate1targettarget`) — modern WoW semantics on the vanilla
engine. Hook is gated by an SStrCmpI prefix check; non-nameplate
tokens fall straight through to the original resolver.
- Ordered GUID list is maintained alongside the existing
NAME_PLATE_UNIT_ADDED / _REMOVED diff. Append on ADDED, erase on
REMOVED — creation-order, stable for a plate's lifetime, modern
semantics.
- Suffix walker mirrors the engine's own LAB_005159d3 walker
instruction-for-instruction: SStrCmpI "target" + ObjectByGUID +
read UNIT_FIELD_TARGET (m_objectFields + 0x28).
- SStrCmpI typedef is __stdcall, not __cdecl. The function ends with
ret 0xc; declaring it cdecl makes MSVC emit a redundant add esp, 12
on top of the callee cleanup, drifting ESP +12 per call and
crashing somewhere deep in Lua once L gets read from a poisoned
stack slot.
- m_objectFields is a *pointer* at obj+0x110, not an inline byte
offset. Two dereferences (mov eax, [obj+0x110]; mov edi, [eax+0x28]),
not one — earlier version mistook the inline-vs-pointer shape and
read instruction bytes as GUIDs.
* document nameplateN unit-token support
- API.md NamePlate section: replace the "scope vs. modern (deferred)"
callout with a pointer to the new Unit tokens subsection; update
the events table and "modern divergence" callout to explain why
the GUID payload remains (engine dispatcher can't carry Lua values
through %s/%d/%u/%f format codes) even though the token form now
works.
- New "Unit tokens (`nameplateN`)" subsection covering the resolved
~30 UnitX functions, creation-order semantics, suffix chains
(`nameplate1target`, `targettarget`), and the SStrCmpI prefix-gate
implementation detail.
- UnitTokenFromGUID's "post-1.12 omitted" list: nameplateN is no
longer engine-unsupported (we hook the resolver) but it's still
not used as a reverse-lookup key — indices can be reassigned
during a session, so it'd be unstable.
- README: new Unit tokens table row pointing to the API.md anchor.
* return stable nameplate wrapper across calls
PushNamePlateFrame was building a fresh Lua table on every call for
unregistered (default vanilla) nameplates — so fields addons set on
the wrapper they received in NAME_PLATE_CREATED were lost on the
next GetNamePlateForUnit lookup. pfUI specifically writes
`plate.nameplate = styledButton` on the CREATED-delivered table to
hand its overlay back through our API, and that field was
disappearing.
Fix: pin the first wrapper for each nameplate pointer in the Lua
registry via luaL_ref, cache the refkey in g_wrapperRefkeys, and
rawgeti on every subsequent push. Same table identity for the life
of the engine plate. Bound by the CGNamePlateFrame pool size (~80).
Cleared on /reload via a new NamePlate::Info::PrepareForReload()
wired into FrameScript_Initialize_h next to the existing
Event::Custom and NameCache reload hooks — stale refkeys would
otherwise point into the freed registry.
* NAME_PLATE_UNIT events now fire token
* nameplate events: ship "nameplateN" tokens, delegate wrappers to engine
Two intertwined changes that together make nameplate-mod addons
(pfUI) survive pool recycle.
1. NAME_PLATE_UNIT_ADDED / _REMOVED arg1 is now the "nameplateN"
unit token, matching modern WoW exactly. For REMOVED we compute
the token before erasing from g_orderedGUIDs so the handler can
still resolve the leaving unit. Addons that want a stable hash
key call UnitGUID(arg1) to convert.
2. PushNamePlateFrame now delegates to the engine's own
FrameScript_Object::ScriptRegister (0x00701BD0) instead of
maintaining our own luaL_ref'd wrapper cache. Per-pointer the
engine builds a wrapper table once, refs it into the registry,
and stores the refkey at nameplate+0x08 - every code path
(ours, addons' CreateFrame(parent) extraction, the engine's own
internal pushers) then funnels through
rawgeti(REGISTRY, nameplate+0x08) and gets the same Lua table.
The prior approach kept our own wrapper alongside the engine's
once pfUI's CreateFrame inside NAME_PLATE_CREATED caused the
engine to register the underlying frame itself - fields set on
our wrapper (plate.nameplate = decoratedButton) disappeared from
the API surface even though they still existed on the orphaned
table. Single-source-of-truth fixes it. The refcount-pinning
caveat CLAUDE.md warned about is benign for pool-managed
nameplates (never destroyed during a session).
Also clear seenPlates / lastTickPlates / orderedGUIDs on
FrameScript_Initialize so currently-visible plates refire CREATED
+ UNIT_ADDED after /reload - re-presents them to the freshly
reloaded UI, matching modern WoW.
---------
Co-authored-by: Brues <5278969+brues-code@users.noreply.github.com>
Drop the hardcoded {75, 5019} ID list in favor of testing
Spell.dbc.Attributes bit 1. Auto Shot (Attr=0x00050012) and Shoot
wand (Attr=0x00000012) share that bit; on-next-swing Heroic Strike
and other ranged spells don't. Future-proofs against private
servers adding new auto-repeating spells.
Modern accessor for "all items in inventory that can equip in
slot N". Walks equipment 1..19 + bags 0..4; for each item whose
m_inventoryType passes the slot-compatibility check, inserts
returnTable[packedLocation] = itemLink. Uses the same packed
ItemLocation encoding as C_EquipmentSet.GetItemLocations.
Compatibility check is a single bitwise AND against a static
invType → slotMask table — same shape and values as 3.3.5's at
DAT_00A2D288 (decoded from its Script_GetInventoryItemsForSlot
chain via FUN_007082B0). Two adjustments for vanilla:
INVTYPE_2HWEAPON → mainhand only (no titanic grip)
INVTYPE_WEAPONMAINHAND → mainhand only
INVTYPE_WEAPONOFFHAND → offhand only
3.3.5's table allowed either-hand for those three because of
later-expansion mechanics.
Implementation gotcha: Item::Location::ResolveBag does
SetTop(L, 0) internally (it needs to set up the engine's
PackBagSlot expected stack shape), which clobbers our returnTable
at slot 2. Fix: anchor the table in the Lua registry under a
private key, collect items into a std::vector during the walk,
then rebuild the stack and populate. Registry slot is cleaned up
before return.
Bank items aren't included — vanilla's GetItemBySlot gates bank
slots on a banker GUID that's only set while the bank window is
open; modern WoW behaves the same way.
The transmogrify arg is accepted and ignored. Stock 1.12 has no
transmog system to query, and the modern flag's effect (broader
cross-eligibility for visual swaps) reduces to the regular equip
check. Private servers (Turtle WoW etc.) layer their own transmog
systems on top of vanilla; if any of those exposes its rules
through addon-readable engine state we'd plumb the flag through,
but we don't know of any such hook today.
Three new accessors for the equipment-set system that vanilla
exposes only partially:
GetItemSetIDByID(itemID) — modern's 16th GetItemInfo return.
GetItemSetID(itemLocation) — same, by ItemLocation table.
GetItemSetInfo(setID) — full ItemSet.dbc row as a table.
The "what set is this item in" path reads ItemStats_C::m_itemSet
at +0x1C0 (field position derived from VanillaHelpers's struct +
verified-offset arithmetic against the already-confirmed
m_bagFamily at +0x1D0). Cache-miss-warm pattern matches the other
*ByID readers (RequestLoadItemDataByID + listen for
GET_ITEM_INFO_RECEIVED).
GetItemSetInfo reads ItemSet.dbc directly — record layout decoded
from the per-record loader at FUN_0057BBA0:
+0x00 ID +0x6C SetSpellID[8]
+0x04 Name[8] (8 locales!) +0x8C SetThreshold[8]
+0x24 unknown +0xAC RequiredSkill
+0x28 ItemID[17] +0xB0 RequiredSkillRank
180-byte stride, 45 columns. ItemSet has only 8 locale slots (vs
Spell.dbc / ChrRaces.dbc's 9), so the name read clamps the global
VAR_LOCALE_INDEX to [0..7] to avoid reading past the locale array
into the unrelated +0x24 field.
Return table: { setID, name, items[], bonuses[{spellID, threshold}],
requiredSkill, requiredSkillRank }. Verified against Magister's
Regalia (setID 181): 8 items, 4 bonuses at thresholds 2/4/6/8.
Returns the spell's reagent list as an array of {itemID, count}
tables, one entry per non-empty reagent slot. Reads directly from
Spell.dbc; stops at the first empty slot, matching the engine's
own tooltip reagent loop.
Discovered while implementing that the reagent offsets we had in
Offsets.h were wrong:
Old: OFF_SPELL_REAGENT_ID = 0x110, OFF_SPELL_REAGENT_COUNT = 0x130
New: OFF_SPELL_REAGENT_ID = 0xA8, OFF_SPELL_REAGENT_COUNT = 0xC8
The old values came from a CMaNGOS-style SpellEntry schema that
doesn't match 1.12.1's actual record layout for reagent fields.
Verified empirically by decompiling BuildSpellTooltip (0x0052E610) —
its reagent loop iterates `localRec + 0x2A` (dword arithmetic =
byte +0xA8) as itemIDs and indexes [+8] (= byte +0xC8) for counts.
We already had a separate OFF_SPELL_RECORD_REAGENTS = 0xA8 entry
used by the tradeskill/craft scrapers (correct value), so it was
silently inconsistent — they were reading the same field by two
different names, one of which was wrong.
Fixed latent IsUsableSpell bug as a side effect: the reagent gate
was reading zeros from +0x110 / +0x130 and concluding "no reagents
required" for every spell. Now correctly returns (false, false) for
spells whose reagent the player doesn't have in their bags.
Verified: GetSpellReagents(23028) = {{itemID=17020, count=1}};
IsUsableSpell(23028)=1 with Arcane Powder in inventory.
Consolidated: removed the now-duplicate OFF_SPELL_RECORD_REAGENTS
alias; tradeskill scraper points at the canonical OFF_SPELL_REAGENT_ID.
Returns (inRange, checkedRange) — 40-yard healing-range check
matching modern's shape. Reuses the CGObject::GetPosition vtable
virtual at slot 5 (offset 0x14) that Script_CheckInteractDistance
uses, just with a fixed 1600.0 squared-distance threshold.
Two notable behaviors:
UnitInRange("player") → (false, false). Documented Blizzard quirk
carried over from modern — the function is meant for "is *another*
unit in range" checks, querying yourself is meaningless. Short-
circuited before the position read so checkedRange=false is
unambiguous.
checkedRange=false when the unit's position can't be obtained:
unresolvable tokens, empty party/raid slots, raid members in a
different zone, target with nothing targeted, etc. The position
virtual returns null in those cases.
Vtable shape verified via the bytes at 0x0048BACF / 0x0048BADC
(both unit and player calls pass an out-buffer to vtable[+0x14] —
Ghidra's decomp dropped the player-call buffer push from the
output).
Direct-by-ID item cooldown query. Returns (startTime, duration,
enable) — the same multi-return shape 1.12's
GetContainerItemCooldown(bag, slot) uses — without requiring a
physical slot reference.
Routes through FUN_ITEM_QUERY_COOLDOWN at 0x006E2ED0, which looks up
the item's ItemStats_C record, finds the slot with trigger=ON_USE
(OFF_ITEMSTATS_SPELL_TRIGGER[i] == 0), and queries that spell's
cooldown via the shared FUN_006E13E0 against the player-spell
cooldown manager. The "ON_USE spell's cooldown" interpretation is
how the engine itself surfaces item cooldowns to addons.
Calling-convention gotcha worth flagging: Ghidra labels the first
arg as uint*, but the ItemStats cache lookup uses the integer both
as a hash key and as the cached-entry field-0 match target (which
is a uint*-typed slot), so the decomp inherits the pointer typing.
The actual fastcall value is the itemID itself — passing &itemID
makes ItemStats interpret the stack address as the lookup key and
the call silently fails. Verified via the Hearthstone (6948) test:
&itemID returned (0, 0, 0); passing itemID directly returns
(732120.014, 3600, 1) after use.
GetItemCooldown(itemInfo) accepts itemID / link / numeric string /
name via the shared Item::Arg helper. C_Container.GetItemCooldown
also accepts links because the shared helper extracts them for
free, even though modern's spec says links aren't accepted.
True if the spell is currently being cast, queued mid-GCD, or
channeled by the player. Reads three engine slots and returns true
on any match:
VAR_CURRENT_CAST_SPELL (0x00CECA88) — cast bar; written by the
cast-start helper at FUN_006E4AD0, read by FUN_006E3D30's
is-currently-casting check (which Script_SpellStopCasting
consults before sending CMSG_CANCEL_CAST).
VAR_QUEUED_CAST_SPELL (0x00CECAA8) — the spell pushed aside when
a new cast superseded it mid-GCD; restored to current when the
new cast ends. Covers the "queued to cast next" half of
modern's documented semantics.
UNIT_FIELD_CHANNEL_SPELL (player descriptor +0x228) — channels
(Fishing, Drain Soul, Ritual of Summoning, etc.).
Accepts the full spellIdentifier shape via Spell::Arg::ResolveSpellID
(number / |Hspell:N|h link / known-spellbook name). Closes TODO #32.
Adds a section-level callout at the top of Spell documenting that
every C_Spell.* function now takes the full spellIdentifier shape
(number / |Hspell:N|h link / known-spellbook name) and returns nil
permissively on garbage input. Function entries still write
(spellID) in the signature for brevity.
Trimmed the now-duplicated identifier-resolution block in
C_Spell.GetSpellCooldown's docs and reworded the "takes a spellID
only" notes on IsSpellPassive / IsSpellHarmful / IsSpellHelpful to
the truer "doesn't accept the (slot, bookType) shape" — since the
broader identifier shape IS accepted.
Modern table-shape cooldown query. Accepts spellID (number),
spell name (with optional (Rank N) suffix), or |Hspell:N|h
hyperlink. Returns a SpellCooldownInfo table:
{ startTime, duration, isEnabled, modRate }
or nil for spellIDs without a Spell.dbc row. modRate is hard-coded
to 1.0 (vanilla has no haste-on-cooldown mechanic); the
post-vanilla fields (activeCategory, timeUntilEndOfStartRecovery,
isOnGCD) are left unset.
Reads the engine's per-spell cooldown manager via
FUN_SPELL_QUERY_COOLDOWN (0x006E2EA0). Fixed the
(*outDuration, *outStart) argument order while doing this — the
typedef in Spell::Usable had it as (*outStart, *outDuration), which
worked accidentally because both fields are 0 when no cooldown is
active, but produced swapped values when a cooldown was running.
Round-tripped against Blink (1953) to verify the corrected order.
Sibling to UnitClassBase. Reads byte 0 of UNIT_FIELD_BYTES_0
(descriptor +0x78) and looks up ChrRaces.dbc::Filename for the
locale-independent token. Returns (raceFile, raceID): "Human"/1,
"Orc"/2, "Dwarf"/3, "NightElf"/4, "Scourge"/5, "Tauren"/6,
"Gnome"/7, "Troll"/8.
Removed two paragraphs that just stated the project premise out loud
("Vanilla 1.12 ships no equivalent...", "Vanilla 1.12 doesn't ship X
(added in later expansions)..."). API.md is the reference for what
ClassicAPI adds — that backport context applies to every entry by
definition.
Kept the substantive nearby context (existing-vanilla-function
contrasts, server constraints, behavioral quirks) — those are
genuinely informative.
Modern arg-order shape (unit first, questID second; questID-keyed).
Walks the unit's +0xE68 sub-struct quest list at +0x28 — same data
source as the engine's IsUnitOnQuest(logIndex, unit). Single Lua call
covers both "is the player on it" and "is a party/raid member on it"
without making the caller find a matching log index first.
Crash hazard fix: the +0xE68 sub-struct is uninitialized for NPCs
(CGCreature_C). First attempt gated on `[unit + 0xE4] & 1` (the
engine's own pre-check before +0xE68 derefs in SetUnitBuff etc.) but
that wasn't sufficient — passing an NPC token still AV'd in the
quest-list walk. The engine's Script_IsUnitOnQuest gets away with the
weaker gate because its GUID-type-filtered ObjMgr lookup
(FUN_00468460(0x10, ...)) rejects non-player GUIDs upstream;
FUN_RESOLVE_UNIT_TOKEN doesn't have that filter. Switched to
UNIT_FLAG_PLAYER_CONTROLLED, which is the gate Item::InventoryID and
Unit::Flags already use for the same hazard.
While doing that, extracted IsPlayerControlled to Unit::Flags::
(new Flags.h) as the canonical predicate. Removed the file-static
copy in Item::InventoryID and collapsed two inline copies in
Unit::Flags (TestPlayerFlag, ReadGuildKey) to call the shared helper.
Walks VAR_QUEST_LOG_ENTRIES (the same array GetQuestIDForLogIndex
reads) matching each real entry's questID against the input. Skips
header rows via the +8 header-pointer gate. Returns false for invalid
input (non-positive / non-number / not in log) — modern semantics, no
lua_error.
Lighter than the engine's IsUnitOnQuest(logIndex, unit) which forces
the caller to walk the log themselves to find the matching index and
resolves a unit token even when the question is just about the player.
Walks the player's buff range for an aura whose Spell.dbc effects
include SPELL_AURA_MOUNTED (78) and sends CMSG_CANCEL_AURA for that
spellID via the existing direct sender. Early-outs on
UNIT_FIELD_MOUNTDISPLAYID == 0 to skip the aura walk when the player
isn't mounted.
Vanilla 1.12 has no Dismount global; addons had to find the mount
buff via GetPlayerBuff and call CancelPlayerBuff with its 0-based
index. Matches Classic Era's no-arg shape.
Vanilla treats warriors as always-in-a-stance — the engine has no "no
stance" state, right-clicking the active stance bar slot does nothing,
and the server rejects CMSG_CANCEL_AURA for stance spells regardless
of how the request is formed. Tried both a looser aura-walk (no
visibility gate) and a form-bar fallback before confirming stances
genuinely aren't cancelable from the client.
All other shapeshift forms (druid, shaman ghost wolf, priest
shadowform / spirit of redemption, rogue stealth) are real visible
buffs and cancel cleanly via the original aura-walk path.
No-arg drop-current-form, polyfilling the modern singular. Walks the
player's buff slots, scans each spell's Spell.dbc EffectApplyAuraName[3]
at +0x16C and EffectMiscValue[3] at +0x1A8 for the
SPELL_AURA_MOD_SHAPESHIFT (0x24) effect whose misc-value matches the
current form byte, and sends CMSG_CANCEL_AURA via FUN_006E7040 for the
owning spellID.
Offsets validated against both 1.12's Script_CastShapeshiftForm
(0x004B4810) — which does the same scan when re-toggling an active form
— and 3.3.5's Script_CancelShapeshiftForm inner FUN_00726CE0. Vanilla's
public Lua surface only exposes the index-based toggle via
CastShapeshiftForm, forcing addons to know which bar slot the current
form occupies before they can cancel it; the no-arg shape is a lot
easier.
Modern aura-cancel primitives — `CancelUnitBuff` decomposes to these
internally. Both go direct to the engine's CMSG_CANCEL_AURA sender
(`FUN_006E7040` at 0x006E7040, `__fastcall(spellID)`) and skip
Script_CancelPlayerBuff's client-side gates (the per-entry cancelable
flag at +0x0A bit 0x01 and the fallback AttributesEx & 0x04 check on
the spell record). Server is the authority on what's cancelable —
non-cancelable auras are rejected server-side as no-ops either way.
CancelSpellByName walks the player's unit-aura descriptor slots 0..31
(buff range) and matches Spell.dbc localized name case-insensitively.
Buff-only by design — matches modern semantics where dispels go
through separate UX.
Player-only (vanilla server only accepts CMSG_CANCEL_AURA for the
local player's own auras), so neither function takes a `unit` arg.
Pre-validates spellID via Spell::Lookup::RecordForID — the engine's
sender unconditionally derefs [record + 0x1C] after a NULL-on-OOR
record lookup, so skipping the check would AV on bad input.