From e793f80f6b45ed49a94dc8abdc9fcac4fe6b03dd Mon Sep 17 00:00:00 2001
From: Brues <5278969+brues-code@users.noreply.github.com>
Date: Mon, 24 Aug 2026 23:16:34 -0500
Subject: [PATCH] feat(spell): add minimap tracking enumeration
Vanilla 1.12 only stores the single active tracking spell
(VAR_ACTIVE_TRACKING_SPELL, 0xBC6378) and never enumerates the tracking
abilities the player knows. Add GetNumTrackingTypes/GetTrackingInfo/
SetTracking, which rebuild that list by scanning the player spellbook for
spells whose EffectApplyAuraName is Track Creatures/Resources/Stealthed
(44/45/151) -- the same discriminator the engine's own active-tracker
updater (FUN_004E4170) uses. This reproduces pfUI's hardcoded tracking
table with no table to maintain and auto-covers server-custom trackers
(e.g. Turtle's Find Trees, 52917).
- GetTrackingInfo returns name, texture, active, category ("spell"),
spellID; active is read from VAR_ACTIVE_TRACKING_SPELL.
- SetTracking selects a tracker by tail-calling the engine's
Script_CastSpell(slot, "spell").
- Add offsets VAR_ACTIVE_TRACKING_SPELL and FUN_SCRIPT_CAST_SPELL
(0x4B42F0), both with RE-provenance comments.
- Document under docs/API.md (Tracking section).
Verified in-game on a Hunter (8 trackers) and a Dwarf racial (1):
active flips on SetTracking, texture matches native GetTrackingTexture,
out-of-range returns nil.
---
docs/API.md | 61 ++++++++++++++
src/Offsets.h | 18 ++++
src/spell/Tracking.cpp | 187 +++++++++++++++++++++++++++++++++++++++++
3 files changed, 266 insertions(+)
create mode 100644 src/spell/Tracking.cpp
diff --git a/docs/API.md b/docs/API.md
index 08258288..63d3aba1 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -584,6 +584,11 @@ build instructions.
- [`GetTotemDuration(slot)`](#gettotemdurationslot)
- [`TargetTotem(slot)`](#targettotemslot)
+- [Tracking](#tracking)
+ - [`GetNumTrackingTypes()`](#getnumtrackingtypes)
+ - [`GetTrackingInfo(index)`](#gettrackinginfoindex)
+ - [`SetTracking(index)`](#settrackingindex)
+
- [TradeSkillUI](#tradeskillui)
- [`C_TradeSkillUI.GetTradeSkillListLink()`](#c_tradeskilluigettradeskilllistlink)
- [`C_TradeSkillUI.GetCraftListLink()`](#c_tradeskilluigetcraftlistlink)
@@ -14141,6 +14146,62 @@ Looks up the totem creature's live GUID (object-manager scan for the
player-owned creature of the slot's tracked entry) and sets the target
through the same engine path `TargetUnit` uses (`CMSG_SET_SELECTION`).
+## Tracking
+
+Vanilla 1.12 stores only the tracking spell that is active now. It does
+not keep a list of the tracking spells you know. These globals add that
+list. A minimap addon can then build a tracking menu without a hardcoded
+spell table.
+
+A tracking spell is a spell in your spellbook that finds creatures,
+resources, or hidden units. This is the same test the engine uses to find
+the active tracker. The list covers Find Herbs, Find Minerals, Find
+Treasure, the Hunter Track spells, Sense Undead, Sense Demons, and Track
+Humanoids. It also covers server-added trackers, such as Turtle's Find
+Trees. You do not have to maintain a spell list.
+
+### `GetNumTrackingTypes()`
+
+Returns the number of tracking spells in your spellbook.
+
+```lua
+GetNumTrackingTypes() -- for example, 8 for a Hunter
+```
+
+### `GetTrackingInfo(index)`
+
+`index` starts at 1 and follows spellbook order. The function returns
+these five values, or `nil` if `index` is out of range:
+
+| # | Value | Type | Notes |
+|---|-------|------|-------|
+| 1 | `name` | string | Localized spell name. |
+| 2 | `texture` | string | Icon path. Give it to `texture:SetTexture(...)`. `nil` if the icon is missing. |
+| 3 | `active` | boolean | `true` when this tracker is the one now in effect. |
+| 4 | `category` | string | Always `"spell"`. Vanilla has no non-spell trackers. |
+| 5 | `spellID` | number | The tracking spell's ID. This is a ClassicAPI extra. The retail 5th value is `nested`, which has no meaning here. |
+
+```lua
+local name, texture, active, category, spellID = GetTrackingInfo(1)
+```
+
+### `SetTracking(index)`
+
+Turns on the tracking spell at `index`. In vanilla, you select a tracker
+when you cast its spell. This function casts it. For an out-of-range
+index, it does nothing. To turn tracking off, use the built-in
+`CancelTrackingBuff()`.
+
+```lua
+for i = 1, GetNumTrackingTypes() do
+ local name = GetTrackingInfo(i)
+ if name == "Find Herbs" then
+ SetTracking(i)
+ break
+ end
+end
+```
+
## TradeSkillUI
Backports the 2.x+ **trade-skill list link** — the shareable
diff --git a/src/Offsets.h b/src/Offsets.h
index e34fa2f6..44c7b010 100644
--- a/src/Offsets.h
+++ b/src/Offsets.h
@@ -4109,6 +4109,15 @@ enum Offsets {
VAR_PET_SPELLBOOK = 0x00B6F098,
SPELLBOOK_MAX_SLOTS = 0x400,
+ // Active minimap-tracking spell ID (0 = none). Vanilla tracks exactly
+ // one active tracker as a plain int here, derived from the player's
+ // active Track Creatures/Resources/Stealthed aura by `FUN_004E4170`
+ // (an aura-descriptor observer registered by `FUN_004E4100`). Read by
+ // `Script_GetTrackingTexture` (`0x004E4A20`), `Script_CancelTrackingBuff`
+ // (`0x004E4A80`), and `GameTooltip:SetTrackingSpell` (`0x00532C50`);
+ // `Spell::Tracking::GetTrackingInfo` reads it to report `active`.
+ VAR_ACTIVE_TRACKING_SPELL = 0x00BC6378,
+
// Player-spell-knowledge bitmap — `[VAR_PLAYER_SPELL_BITMAP]` is a
// pointer to a dword bitmap covering all spellIDs the player has
// learned, including talent passives, racials, profession recipes,
@@ -4379,6 +4388,15 @@ enum Offsets {
// results). Callable directly from C++ — push args on stack, call.
FUN_SCRIPT_CAST_SPELL_BY_NAME = 0x004B4AB0,
+ // `Script_CastSpell` — engine's Lua wrapper for the slot-based
+ // `CastSpell(spellbookSlot, bookType)` global. `int __fastcall(void *L)`.
+ // Parses (slot, bookType) from stack[1]/[2] via `FUN_004B3EC0`, then
+ // dispatches through `FUN_SPELL_CAST_DISPATCH` with the current target
+ // (or self). Raises "Invalid spell slot in CastSpell" for a bad slot.
+ // Callable from C++ by preparing the stack and tail-calling it (the
+ // `Spell::Tracking::SetTracking` "select = cast" path does this).
+ FUN_SCRIPT_CAST_SPELL = 0x004B42F0,
+
// Inner spell-cast dispatcher — `__fastcall(slot, bookType, targetGuidLo,
// targetGuidHi)`. `Script_CastSpellByName` calls this after resolving
// the spell name to a spellbook slot. For ground-target spells, the
diff --git a/src/spell/Tracking.cpp b/src/spell/Tracking.cpp
new file mode 100644
index 00000000..2f530d4b
--- /dev/null
+++ b/src/spell/Tracking.cpp
@@ -0,0 +1,187 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see .
+
+#include "Game.h"
+#include "Offsets.h"
+#include "dbc/Lookup.h"
+#include "spell/Lookup.h"
+
+#include
+
+// `GetNumTrackingTypes()` / `GetTrackingInfo(index)` / `SetTracking(index)` —
+// backport of the minimap-tracking enumeration the modern client exposes.
+//
+// Vanilla 1.12 never enumerates the tracking abilities the player KNOWS — it
+// only stores the single currently-active tracker as a plain spellID in
+// `VAR_ACTIVE_TRACKING_SPELL`, surfaced through `GetTrackingTexture()` /
+// `CancelTrackingBuff()` / `GameTooltip:SetTrackingSpell()`. 3.3.5's
+// `GetTrackingInfo` iterates a spellbook-derived list of tracking spells and
+// reports name/texture/active/category per entry; we rebuild that list here.
+//
+// A tracking spell is identified exactly the way the engine's own active-
+// tracker updater `FUN_004E4170` identifies one: a Spell.dbc record with an
+// `EffectApplyAuraName` of Track Creatures (44), Track Resources (45), or
+// Track Stealthed (151). That effect-based test reproduces pfUI's hardcoded
+// spellID/icon table (Find Herbs/Minerals/Treasure/Trees, every Hunter
+// Track*, Sense Undead/Demons, Track Humanoids) with no table to maintain,
+// and auto-covers server-custom trackers such as Turtle's Find Trees (52917).
+namespace Spell::Tracking {
+
+// Tracking aura effect types — SPELL_AURA_TRACK_* ApplyAura names, the same
+// values `FUN_004E4170` scans a spell's three effects for.
+static constexpr int32_t AURA_TRACK_CREATURES = 44;
+static constexpr int32_t AURA_TRACK_RESOURCES = 45;
+static constexpr int32_t AURA_TRACK_STEALTHED = 151;
+
+// True iff `spellID`'s record has any of the three Track* effects.
+static bool IsTrackingSpell(int spellID) {
+ const uint8_t *record = Spell::Lookup::RecordForID(spellID);
+ if (record == nullptr)
+ return false;
+ auto *aura = Game::Ptr(
+ record, Offsets::OFF_SPELL_RECORD_EFFECT_APPLY_AURA_NAME);
+ for (int i = 0; i < Offsets::SPELL_RECORD_EFFECT_COUNT; ++i) {
+ if (aura[i] == AURA_TRACK_CREATURES || aura[i] == AURA_TRACK_RESOURCES ||
+ aura[i] == AURA_TRACK_STEALTHED)
+ return true;
+ }
+ return false;
+}
+
+// Walks the player spellbook in slot order counting tracking spells. If
+// `wantNth >= 1` and an Nth tracking spell exists, writes its spellID and
+// 1-based spellbook slot to `*outSpellID` / `*outSlot`. Returns the total
+// number of tracking spells found (so callers detect out-of-range by
+// comparing the return against `wantNth`).
+//
+// The spellbook array is zero-padded past the populated count (see
+// `Spell::Lookup::FindSpellbookSlot`), so a 0 entry is just an empty slot —
+// skip it and keep scanning the full range rather than break, matching the
+// existing spellbook walkers.
+static int EnumerateTracking(int wantNth, int *outSpellID, int *outSlot) {
+ auto *book = reinterpret_cast(
+ static_cast(Offsets::VAR_PLAYER_SPELLBOOK));
+ int found = 0;
+ for (int i = 0; i < Offsets::SPELLBOOK_MAX_SLOTS; ++i) {
+ const int spellID = book[i];
+ if (spellID <= 0 || !IsTrackingSpell(spellID))
+ continue;
+ ++found;
+ if (found == wantNth) {
+ if (outSpellID != nullptr)
+ *outSpellID = spellID;
+ if (outSlot != nullptr)
+ *outSlot = i + 1;
+ }
+ }
+ return found;
+}
+
+// `GetNumTrackingTypes()` -> number of tracking spells in the player's book.
+static int __fastcall Script_GetNumTrackingTypes(void *L) {
+ Game::Lua::PushNumber(L,
+ static_cast(EnumerateTracking(0, nullptr, nullptr)));
+ return 1;
+}
+
+// `GetTrackingInfo(index)` -> name, texture, active, category, spellID.
+// - index is 1-based into the tracking list (spellbook order).
+// - texture is the SpellIcon.dbc path (nil if the icon is missing).
+// - active is a boolean: the tracker currently in effect.
+// - category is always "spell" — vanilla has no non-spell ("other")
+// trackers, unlike 3.3.5's class-masked table.
+// - spellID is a ClassicAPI extension (the modern 5th return is `nested`,
+// which has no meaning here); handy since selecting/among trackers is
+// spellID-driven.
+// Returns nil for an out-of-range index.
+static int __fastcall Script_GetTrackingInfo(void *L) {
+ if (!Game::Lua::IsNumber(L, 1)) {
+ Game::Lua::Error(L, "Usage: GetTrackingInfo(index)");
+ return 0;
+ }
+ const int index = static_cast(Game::Lua::ToNumber(L, 1));
+ if (index < 1)
+ return 0;
+
+ int spellID = 0;
+ int slot = 0;
+ if (EnumerateTracking(index, &spellID, &slot) < index)
+ return 0; // index past the number of tracking types -> nil
+
+ const uint8_t *record = Spell::Lookup::RecordForID(spellID);
+ const int locale = Game::Read(static_cast(Offsets::VAR_LOCALE_INDEX));
+ const char *name =
+ Game::Read(record, Offsets::OFF_SPELL_NAMES + locale * 4);
+
+ const char *texture = nullptr;
+ const int iconID = Game::Read(record, Offsets::OFF_SPELL_RECORD_ICON_ID);
+ if (auto *iconRec = DBC::Record(Offsets::VAR_SPELL_ICON_RECORDS,
+ Offsets::VAR_SPELL_ICON_COUNT,
+ static_cast(iconID))) {
+ texture = Game::Read(iconRec, Offsets::OFF_SPELLICON_PATH);
+ }
+
+ const bool active =
+ Game::Read(static_cast(Offsets::VAR_ACTIVE_TRACKING_SPELL)) ==
+ spellID;
+
+ Game::Lua::PushString(L, name); // 1. name (PushString handles NULL -> nil)
+ Game::Lua::PushString(L, texture); // 2. texture (icon path) or nil
+ Game::Lua::PushBool(L, active); // 3. active
+ Game::Lua::PushString(L, "spell"); // 4. category
+ Game::Lua::PushNumber(L, static_cast(spellID)); // 5. spellID (extension)
+ return 5;
+}
+
+// `SetTracking(index)` — selects (activates) the tracking spell at `index`.
+// Vanilla has no "set tracking" primitive: choosing a tracker IS casting its
+// spell (the tracking dropdown does exactly this). So we resolve the entry's
+// spellbook slot and tail-call the engine's own `Script_CastSpell(slot,
+// "spell")` — reusing its slot bounds-check, target resolution, and error
+// handling rather than reconstructing the cast path. Returns nil for an
+// out-of-range index.
+static int __fastcall Script_SetTracking(void *L) {
+ if (!Game::Lua::IsNumber(L, 1)) {
+ Game::Lua::Error(L, "Usage: SetTracking(index)");
+ return 0;
+ }
+ const int index = static_cast(Game::Lua::ToNumber(L, 1));
+ if (index < 1)
+ return 0;
+
+ int spellID = 0;
+ int slot = 0;
+ if (EnumerateTracking(index, &spellID, &slot) < index)
+ return 0;
+
+ // Rebuild the stack as CastSpell(slot, "spell") and hand off to the
+ // engine handler. `slot` is 1-based, matching what a Lua `CastSpell`
+ // caller passes.
+ Game::Lua::SetTop(L, 0);
+ Game::Lua::PushNumber(L, static_cast(slot));
+ Game::Lua::PushString(L, "spell");
+ using CastSpell_t = int(__fastcall *)(void *);
+ auto castSpell = reinterpret_cast(Offsets::FUN_SCRIPT_CAST_SPELL);
+ return castSpell(L);
+}
+
+static void RegisterLuaFunctions() {
+ Game::Lua::RegisterGlobalFunction("GetNumTrackingTypes",
+ &Script_GetNumTrackingTypes);
+ Game::Lua::RegisterGlobalFunction("GetTrackingInfo", &Script_GetTrackingInfo);
+ Game::Lua::RegisterGlobalFunction("SetTracking", &Script_SetTracking);
+}
+
+static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+
+} // namespace Spell::Tracking