From b893b8eff1ee8eee12ecc65ed78dfec5f299ddcb Mon Sep 17 00:00:00 2001 From: Brues <5278969+brues-code@users.noreply.github.com> Date: Fri, 8 May 2026 23:05:43 -0500 Subject: [PATCH] GetFactionParentID and GetTalentIDByIndex --- README.md | 6 +-- TODO.md | 111 ++++++++++++++++++------------------------- docs/API.md | 51 ++++++++++++++++++++ src/Offsets.h | 1 + src/faction/Info.cpp | 24 ++++++++++ src/talent/Info.cpp | 58 ++++++++++++++++++++++ src/unit/Tooltip.cpp | 77 ++++++++++++++++++++++++++++++ 7 files changed, 261 insertions(+), 67 deletions(-) create mode 100644 src/unit/Tooltip.cpp diff --git a/README.md b/README.md index adf917ee..b75d1aa1 100644 --- a/README.md +++ b/README.md @@ -18,13 +18,13 @@ Quick index: | Namespace | Calls | |-----------|-------| | Spell | `GetSpellInfo` (with `(slot, bookType)` overload), `C_Spell.GetSpellInfo`, `C_Spell.GetSpellName`, `C_Spell.GetSpellTexture`, `GetSpellLink` (with `(slot, bookType)` overload), `C_Spell.GetSpellLink`, `FindSpellBookSlotByID`, `C_Spell.GetSpellDescription`, `IsPassiveSpell` (with `(slot, bookType)` overload), `C_Spell.IsSpellPassive`, `IsPlayerSpell`, `IsSpellKnown` | -| GameTooltip | `GameTooltip:SetSpellByID` | +| GameTooltip | `GameTooltip:SetSpellByID`, `GameTooltip:SetItemByID`, `GameTooltip:SetUnitAura` | | Quest | `GetQuestIDFromLogIndex`, `C_QuestLog.RequestLoadQuestByID` (+ `QUEST_DATA_LOAD_RESULT` event), `C_QuestLog.GetTitleForQuestID` | -| Faction | `GetFactionIDByIndex`, `GetFactionInfoByID` | +| Faction | `GetFactionIDByIndex`, `GetFactionInfoByID`, `GetFactionParentID` | | Item | `C_Item.IsBound`, `C_Item.GetItemID`, `GetInventoryItemID`, `C_Container.GetContainerItemID`, `C_Item.GetItemInfoInstant`, `GetItemIcon` / `C_Item.GetItemIcon` / `C_Item.GetItemIconByID`, `C_Item.IsItemDataCached(ByID)`, `C_Item.RequestLoadItemData(ByID)` (+ `ITEM_DATA_LOAD_RESULT` event) | | Unit | `UnitGUID` | | Combat | `InCombatLockdown` | -| Talent | `GetTalentSpellID` | +| Talent | `GetTalentSpellID`, `GetTalentIDByIndex` | | Time | `GetServerTime` | | Events | `C_EventUtils.IsEventValid` | | Global | `CLASSIC_API_VERSION` | diff --git a/TODO.md b/TODO.md index 0b2bb369..a506d664 100644 --- a/TODO.md +++ b/TODO.md @@ -730,22 +730,17 @@ library that wants to render an indicator radius. Modern WoW exposes this via `GetSpellRadius` (deprecated) or returns from `C_Spell.GetSpellInfo`. -## 39. `GetFactionParentID(factionID)` — trivial +## ~~39. `GetFactionParentID(factionID)`~~ — DONE -Returns the parent factionID for a faction in a hierarchy (e.g. -`Stormwind`'s parent is `Alliance`; `The Defilers`'s parent is -`Horde Forces`). Modern WoW returns this as the 13th value of -`GetFactionInfoByID`. We'd just add it as its own getter. +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. -`Faction.dbc` `ParentFactionID` is at `+0x48` of the record (already -documented in [`src/Offsets.h`](src/Offsets.h)'s Faction section as -"`ParentFactionID +0x48`"; the existing `Faction::Info::FactionRecord` -helper returns the record pointer ready to read). This is a 5-line -addition. - -Used by reputation addons that group factions hierarchically -(`Stormwind` rolls up under `Alliance`, etc.), and by character- -sheet-style displays. +See [src/faction/Info.cpp](src/faction/Info.cpp) and +`OFF_FACTION_PARENT_ID` in [src/Offsets.h](src/Offsets.h). ## 40. `UnitRaceBase(unit)` — easy @@ -783,32 +778,20 @@ 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)` — easy +## ~~42. `GetTalentIDByIndex(tabIndex, talentIndex)`~~ — DONE -Exposes the `Talent.dbc` primary key — the talentID at `+0x00` of -the record. 1.12's `GetTalentInfo(tab, idx)` returns -`(name, icon, tier, column, currentRank, maxRank)` but NOT the -talentID. Modern WoW exposes it as the 9th return of `GetTalentInfo`, -and `GetTalentInfoByID(talentID)` / `GameTooltip:SetTalentByID` -both consume it as the natural key. +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. -Why useful even though `(tab, idx)` works for most things: +Unblocks #43 `GameTooltip:SetTalentByID` whenever someone wants the +modern by-ID tooltip dispatcher. -- **Stable across talent-tree restructuring** — vanilla itself - doesn't restructure trees mid-expansion, but addons backporting - from later expansions key on talentID and we'd let them work - unmodified. -- **SavedVariables-friendly** — single int per talent vs. - `(class, tab, tier, column)` tuple. -- **Enables #43 `SetTalentByID`** which has no other input shape. - -`Talent.dbc` instance at `0x00C0D6E0` (records ptr at `+0x08`, count -at `+0x0C`, per `docs/DBCs.md`). Resolution path: the engine's -`Script_GetTalentInfo` already walks Talent.dbc filtered by -`TabID`, sorted by `(tier, column)`, to produce the visible order -the Lua API uses. Mirror that walk and return `record[+0x00]` -instead of the existing tuple. Should share the (tab, idx) -resolution helper with #36 `GetTalentSpellID`. +See [src/talent/Info.cpp](src/talent/Info.cpp). ## 43. `GameTooltip:SetTalentByID(talentID)` — medium @@ -832,40 +815,40 @@ display time. Same helper #42 uses, just inverted. If we ship #42 first, this becomes a thin wrapper — the talentID → `(tab, idx)` mapping is symmetric to #42's `(tab, idx)` → talentID. -## 44. `GameTooltip:SetItemByID(itemID)` — trivial +## ~~44. `GameTooltip:SetItemByID(itemID)`~~ — DONE -Modern method that renders an item tooltip from just an itemID. The -1.12 workaround is to construct an item hyperlink and call -`SetHyperlink` — `tooltip:SetHyperlink("item:" .. id .. ":0:0:0:0:0:0:0")` -— which works but is ugly and forces every caller to know the -hyperlink format. - -Implementation: format the hyperlink string in C (`snprintf`) and -dispatch to the existing `Script_GameTooltip_SetHyperlink` at -`0x00531FD0` (registry slot 12). Same registration pattern as -[src/spell/Tooltip.cpp](src/spell/Tooltip.cpp) used for +snprintf the hyperlink string and dispatch to the existing +`Script_GameTooltip_SetHyperlink`. Same registration pattern as `SetSpellByID`. -Used by basically every addon that wants to show item tooltips -without first faking a hyperlink — bag manager UIs, loot trackers, -auction tools. +### Caching gotcha caught in testing -## 45. `GameTooltip:SetUnitAura(unit, index, filter)` — trivial +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. -Modern unified-aura method that 1.12 splits into `SetUnitBuff` (slot -32, `0x00534AC0`) and `SetUnitDebuff` (slot 33, `0x00534E30`). -Single method takes a filter string `"HELPFUL"` or `"HARMFUL"` and -dispatches to the right underlying call. +Documented the caveat in [docs/API.md](docs/API.md) with the +recommended `IsItemDataCachedByID` / `RequestLoadItemDataByID` / +`ITEM_DATA_LOAD_RESULT` pattern callers should follow. -Implementation: pure dispatch wrapper. Register on the GameTooltip -method registry (existing `Game::Lua::RegisterFrameMethods` flow) -and in the body, branch on the filter string and tail-call the -existing `SetUnitBuff` / `SetUnitDebuff` script function. +See [src/item/Tooltip.cpp](src/item/Tooltip.cpp). -Used by aura libraries that already use the modern call shape (which -is most of them, since modern is what addons backport from). Lets -them use the same code path on the 1.12 client without conditionally -splitting on filter. +## ~~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])` — medium-large, deferred diff --git a/docs/API.md b/docs/API.md index 6731e414..1fc298e2 100644 --- a/docs/API.md +++ b/docs/API.md @@ -28,6 +28,7 @@ build instructions. - [Faction](#faction) - [`GetFactionIDByIndex(factionIndex)`](#getfactionidbyindexfactionindex) - [`GetFactionInfoByID(factionID)`](#getfactioninfobyidfactionid) + - [`GetFactionParentID(factionID)`](#getfactionparentidfactionid) - [Item](#item) - [`C_Item.IsBound(itemLocation)`](#c_itemisbounditemlocation) - [`C_Item.GetItemID(itemLocation)`](#c_itemgetitemiditemlocation) @@ -43,6 +44,7 @@ build instructions. - [`InCombatLockdown()`](#incombatlockdown) - [Talent](#talent) - [`GetTalentSpellID(tabIndex, talentIndex, [rank])`](#gettalentspellidtabindex-talentindex-rank) + - [`GetTalentIDByIndex(tabIndex, talentIndex)`](#gettalentidbyindextabindex-talentindex) - [Time](#time) - [`GetServerTime()`](#getservertime) - [Events](#events) @@ -557,6 +559,30 @@ local name = GetFactionInfoByID(574) -- Caer Darrow (faction that can't be enco Equivalent to the function of the same name introduced in 3.0. +### `GetFactionParentID(factionID)` + +Returns the parent factionID for a faction in a hierarchy (e.g. +Stormwind's parent is Alliance Forces; The Defilers's parent is +Horde Forces). Returns `0` for top-level factions with no parent, +or `nil` for invalid factionIDs. + +```lua +GetFactionParentID(72) -- 469 (Stormwind → Alliance) +GetFactionParentID(469) -- 0 (Alliance is top-level) +GetFactionParentID(99999) -- nil +``` + +Modern WoW returns this as the 13th value of `GetFactionInfoByID`; +we expose it as its own getter since 1.12's `GetFactionInfo` doesn't +have the slot. + +Reads `Faction.dbc` `ParentFactionID` at record `+0x48` directly — +no displayed-list dependency, works for any faction in the DBC +regardless of whether the player has rep with it. + +Equivalent to the function of the same name introduced in 3.0 (as +the 13th return of `GetFactionInfoByID`). + ## Item ### `C_Item.IsBound(itemLocation)` @@ -874,6 +900,31 @@ Equivalent to one of `GetTalentInfo`'s extended returns in modern WoW (varies by version; the talent's spellID has been part of the tuple since 5.0+). +### `GetTalentIDByIndex(tabIndex, talentIndex)` + +Returns the engine's hidden talentID — the primary key of the +`Talent.dbc` row — for the talent at the given (tab, idx). Returns +`nil` for out-of-range indices. + +```lua +GetTalentIDByIndex(1, 9) -- 174 (Inner Focus, Discipline tier 3) +GetTalentIDByIndex(1, 1) -- 166 (first Discipline talent) +``` + +1.12's `GetTalentInfo(tab, idx)` returns +`(name, icon, tier, column, currentRank, maxRank, ...)` but NOT the +talentID. Modern WoW exposes it (and uses talentIDs as the natural +key for `GetTalentInfoByID`, talent build sharing strings, etc.); we +add this getter so addons that key on talentIDs from later expansions +work unmodified. + +Reads `TalentEntry+0x00` from the per-tab talent arrays at +`[0x00BDCD28]`. Same struct walk as `GetTalentSpellID`, just reads +a different field. + +Equivalent to the talentID return slot of `GetTalentInfo` in modern +WoW (5.0+; not exposed at all in 1.12). + ## Time ### `GetServerTime()` diff --git a/src/Offsets.h b/src/Offsets.h index 69c6e8a2..4ea5cb39 100644 --- a/src/Offsets.h +++ b/src/Offsets.h @@ -224,6 +224,7 @@ enum Offsets { // `[VAR_LOCALE_INDEX]` (0..8). VAR_FACTION_DBC_RECORDS = 0x00C0DD50, VAR_FACTION_DBC_COUNT = 0x00C0DD54, + OFF_FACTION_PARENT_ID = 0x48, OFF_FACTION_NAMES = 0x4C, OFF_FACTION_DESCRIPTIONS = 0x70, diff --git a/src/faction/Info.cpp b/src/faction/Info.cpp index 532c389b..a6f00a8f 100644 --- a/src/faction/Info.cpp +++ b/src/faction/Info.cpp @@ -171,9 +171,33 @@ static int __fastcall Script_GetFactionInfoByID(void *L) { return 11; } +// `GetFactionParentID(factionID)` — returns the parent factionID for a +// faction in a hierarchy (e.g. Stormwind's parent is Alliance Forces; +// The Defilers's parent is Horde Forces). Returns `0` if the faction +// is top-level (no parent), or `nil` if the factionID is invalid. +// +// Reads `Faction.dbc` `ParentFactionID` at `+0x48`. Modern WoW returns +// this as the 13th value of `GetFactionInfoByID`; we expose it as its +// own getter since 1.12's `GetFactionInfo` doesn't have the slot. +static int __fastcall Script_GetFactionParentID(void *L) { + if (!Game::Lua::IsNumber(L, 1)) { + Game::Lua::Error(L, "Usage: GetFactionParentID(factionID)"); + return 0; + } + const int factionID = static_cast(Game::Lua::ToNumber(L, 1)); + const uint8_t *record = FactionRecord(factionID); + if (record == nullptr) + return 0; + const int parent = *reinterpret_cast( + record + Offsets::OFF_FACTION_PARENT_ID); + Game::Lua::PushNumber(L, static_cast(parent)); + return 1; +} + static void RegisterLuaFunctions() { Game::Lua::RegisterGlobalFunction("GetFactionIDByIndex", &Script_GetFactionIDByIndex); Game::Lua::RegisterGlobalFunction("GetFactionInfoByID", &Script_GetFactionInfoByID); + Game::Lua::RegisterGlobalFunction("GetFactionParentID", &Script_GetFactionParentID); } static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions}; diff --git a/src/talent/Info.cpp b/src/talent/Info.cpp index 2fca878f..f0c1fb41 100644 --- a/src/talent/Info.cpp +++ b/src/talent/Info.cpp @@ -109,8 +109,66 @@ static int __fastcall Script_GetTalentSpellID(void *L) { return 1; } +// `GetTalentIDByIndex(tabIndex, talentIndex)` — returns the Talent.dbc +// primary key (the row's ID at `TalentEntry+0x00`) for the talent at +// the given (tab, idx). 1.12's `GetTalentInfo` returns +// `(name, icon, tier, column, currentRank, maxRank, ...)` but NOT the +// talentID, so addons that want a stable identifier (for SavedVariables +// keys, talent-build sharing, modern-API parity) currently have to +// encode `(class, tab, tier, column)` and hope the talent tree doesn't +// shift. +// +// Reads from the same per-tab talent arrays at `[VAR_TALENT_TAB_INFO_ARRAY]` +// that #36 `GetTalentSpellID` walks. talentID at `+0x00` of the +// `TalentEntry` was verified empirically during the GetTalentSpellID +// debug pass: `entryFirstDword=174` matched Inner Focus's Talent.dbc +// row ID (and `166` for the first Discipline talent). +static int __fastcall Script_GetTalentIDByIndex(void *L) { + if (!Game::Lua::IsNumber(L, 1) || !Game::Lua::IsNumber(L, 2)) { + Game::Lua::Error(L, "Usage: GetTalentIDByIndex(tabIndex, talentIndex)"); + return 0; + } + const int tabIndex = static_cast(Game::Lua::ToNumber(L, 1)); + const int talentIndex = static_cast(Game::Lua::ToNumber(L, 2)); + if (tabIndex < 1 || talentIndex < 1) + return 0; + + const int tabCount = *reinterpret_cast( + static_cast(Offsets::VAR_TALENT_TAB_COUNT)); + if (tabIndex > tabCount) + return 0; + + auto *tabs = *reinterpret_cast( + static_cast(Offsets::VAR_TALENT_TAB_INFO_ARRAY)); + if (tabs == nullptr) + return 0; + const uint8_t *tabInfo = tabs[tabIndex - 1]; + if (tabInfo == nullptr) + return 0; + + const int numTalents = *reinterpret_cast( + tabInfo + Offsets::OFF_TABINFO_NUM_TALENTS); + if (talentIndex > numTalents) + return 0; + + auto *talents = *reinterpret_cast( + tabInfo + Offsets::OFF_TABINFO_TALENT_ARRAY); + if (talents == nullptr) + return 0; + + const uint8_t *entry = talents + + (talentIndex - 1) * Offsets::TALENT_ENTRY_STRIDE; + const uint32_t talentID = *reinterpret_cast(entry); + if (talentID == 0) + return 0; + + Game::Lua::PushNumber(L, static_cast(talentID)); + return 1; +} + static void RegisterLuaFunctions() { Game::Lua::RegisterGlobalFunction("GetTalentSpellID", &Script_GetTalentSpellID); + Game::Lua::RegisterGlobalFunction("GetTalentIDByIndex", &Script_GetTalentIDByIndex); } static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions}; diff --git a/src/unit/Tooltip.cpp b/src/unit/Tooltip.cpp new file mode 100644 index 00000000..1754f0eb --- /dev/null +++ b/src/unit/Tooltip.cpp @@ -0,0 +1,77 @@ +// This file is part of ClassicAPI. +// +// ClassicAPI is free software: you can redistribute it and/or modify it under the terms +// of the GNU Lesser 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 Lesser General Public License for more details. +// +// You should have received a copy of the GNU Lesser General Public License along with +// ClassicAPI. If not, see . + +#include "Game.h" +#include "Offsets.h" + +#include +#include + +namespace Unit::Tooltip { + +// `GameTooltip:SetUnitAura(unit, index, [filter])` — modern unified-aura +// method. 1.12 splits this into `SetUnitBuff` (slot 32) and +// `SetUnitDebuff` (slot 33); we dispatch to the right one based on the +// `filter` string ("HELPFUL" → SetUnitBuff, "HARMFUL" → SetUnitDebuff). +// +// `filter` defaults to "HELPFUL" when omitted, matching modern +// behavior. Anything other than a HARMFUL match goes to SetUnitBuff. +static int __fastcall Script_GameTooltipSetUnitAura(void *L) { + // Args: self (table), unit (string), index (number), filter (optional string) + if (Game::Lua::Type(L, 1) != Game::Lua::TYPE_TABLE) { + Game::Lua::Error(L, "Usage: GameTooltip:SetUnitAura(unit, index, [filter])"); + return 0; + } + if (!Game::Lua::IsString(L, 2) || !Game::Lua::IsNumber(L, 3)) { + Game::Lua::Error(L, "Usage: GameTooltip:SetUnitAura(unit, index, [filter])"); + return 0; + } + + bool isHarmful = false; + if (Game::Lua::Type(L, 4) == Game::Lua::TYPE_STRING) { + const char *filter = Game::Lua::ToString(L, 4); + // Case-insensitive prefix check for "HARM" — covers "HARMFUL" + // (the canonical filter) and any reasonable variant. Anything + // else, including missing/empty, falls through to the buff path. + if (filter != nullptr) { + const char a = filter[0], b = filter[1], c = filter[2], d = filter[3]; + isHarmful = (a == 'H' || a == 'h') && (b == 'A' || b == 'a') && + (c == 'R' || c == 'r') && (d == 'M' || d == 'm'); + } + } + + // Drop the filter arg before calling — the existing + // SetUnitBuff/SetUnitDebuff take (self, unit, index) only. + Game::Lua::SetTop(L, 3); + + using Script_t = int(__fastcall *)(void *L); + auto fn = reinterpret_cast( + isHarmful ? Offsets::FUN_SCRIPT_GAMETOOLTIP_SET_UNIT_DEBUFF + : Offsets::FUN_SCRIPT_GAMETOOLTIP_SET_UNIT_BUFF); + return fn(L); +} + +static const Game::Lua::FrameMethodEntry g_methods[] = { + {"SetUnitAura", &Script_GameTooltipSetUnitAura}, +}; + +static void RegisterLuaFunctions() { + Game::Lua::RegisterFrameMethods( + reinterpret_cast(Offsets::VAR_GAMETOOLTIP_METHOD_REGISTRY), + g_methods, + static_cast(sizeof(g_methods) / sizeof(g_methods[0]))); +} + +static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions}; + +} // namespace Unit::Tooltip