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