diff --git a/README.md b/README.md index 580e0ae8..b596a300 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ Full per-function reference: **[docs/API.md](docs/API.md)**. | [AddOns](docs/API.md#addons) | `C_AddOns.DoesAddOnExist`, `C_AddOns.GetAddOnName`, `C_AddOns.GetAddOnNotes`, `C_AddOns.GetAddOnOptionalDependencies`, `C_AddOns.GetAddOnSecurity`, `C_AddOns.GetAddOnTitle`, `C_AddOns.IsAddOnLoadable`, `C_AddOns.IsAddOnLoaded` | | [AuctionHouse](docs/API.md#auctionhouse) | `C_AuctionHouse.PostItem` | | [Chat](docs/API.md#chat) | `GetCurrentChatGUID` | +| [ChatBubbles](docs/API.md#chatbubbles) | `C_ChatBubbles.GetAllChatBubbles` | | [Class](docs/API.md#class) | `FillLocalizedClassList` | | [Combat](docs/API.md#combat) | `InCombatLockdown` | | [CVar](docs/API.md#cvar) | `C_CVar.GetCVarBool` | diff --git a/docs/API.md b/docs/API.md index f18cc286..89bef349 100644 --- a/docs/API.md +++ b/docs/API.md @@ -334,6 +334,9 @@ build instructions. - [`C_MerchantFrame.IsMerchantItemRefundable(slot)`](#c_merchantframeismerchantitemrefundableslot) - [`C_MerchantFrame.IsSellAllJunkEnabled()`](#c_merchantframeissellalljunkenabled) +- [ChatBubbles](#chatbubbles) + - [`C_ChatBubbles.GetAllChatBubbles([includeForbidden])`](#c_chatbubblesgetallchatbubblesincludeforbidden) + - [NamePlate](#nameplate) - [`C_NamePlate.GetNamePlates()`](#c_nameplategetnameplates) - [`C_NamePlate.GetNamePlateGUIDs()`](#c_nameplategetnameplateguids) @@ -8012,6 +8015,42 @@ No retail equivalent (retail ships only the explored getter; its inverse, `C_Map.GetMapOverlays`, returns *everything*). Same table shape and `areaID` semantics as the explored getter. +## ChatBubbles + +### `C_ChatBubbles.GetAllChatBubbles([includeForbidden])` + +Returns a 1-based table of the currently-active chat-bubble `Frame` +objects (the speech bubbles above characters who `/say` or `/yell`). +Modern WoW added this in 7.2.5 to replace the old "iterate over +`WorldFrame` children and guess which are bubbles" idiom — we hand you +the exact set instead. + +```lua +for _, bubble in ipairs(C_ChatBubbles.GetAllChatBubbles()) do + -- The spoken text lives in the bubble's FontString region. + for _, region in ipairs({bubble:GetRegions()}) do + if region.GetText and region:GetText() then + print(region:GetText()) + end + end +end +``` + +Vanilla 1.12 chat bubbles are `CGChatBubbleFrame`s — full frames the +engine creates in C++ without ever calling `CreateFrame` (same as +default nameplates). The returned frames are the engine's **canonical +wrappers**: real, method-capable (`:GetRegions()`, `:IsShown()`, +`:GetPoint()`, …), and identical to the object any other addon that +touches the bubble sees, so decorations survive. The spoken-text +FontString is parented to the bubble, so it shows up in +`:GetRegions()`. + +`includeForbidden` is accepted for signature parity and ignored — +vanilla has no forbidden frames, so every active bubble is returned +regardless. Returns an empty table when no bubbles are showing. A +bubble whose owner just despawned can linger for one frame before the +engine prunes it; filter on `bubble:IsShown()` if that matters. + ## NamePlate Modern `C_NamePlate.*` returns nameplate `Frame` objects keyed off diff --git a/src/chatbubble/Info.cpp b/src/chatbubble/Info.cpp new file mode 100644 index 00000000..65f90a44 --- /dev/null +++ b/src/chatbubble/Info.cpp @@ -0,0 +1,82 @@ +// 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 . + +// `C_ChatBubbles.GetAllChatBubbles([includeForbidden])` — returns an +// array of the currently-active chat-bubble Frame objects, matching +// modern WoW's 7.2.5 signature. Addons use it to recolor / translate / +// reposition speech bubbles by reading the bubble's FontString region. +// +// Vanilla 1.12 chat bubbles are `CGChatBubbleFrame`s — full +// `CSimpleFrame`s created purely in C++ (never via `CreateFrame`), so +// they have no name and no Lua wrapper until something pushes them. This +// is exactly the default-nameplate case: we push each via the shared +// `UI::FrameObject::Push`, which delegates to the engine's own +// `FrameScript_Object::ScriptRegister` to lazily build the canonical +// wrapper. The returned frames respond to real frame methods — the +// FontString holding the spoken text (bubble + 0x31c, created with the +// bubble as its parent) shows up in `bubble:GetRegions()`, so the modern +// "iterate GetRegions, find the FontString, read GetText()" idiom works +// unchanged. This is the pre-7.2.5 "walk WorldFrame children" pattern the +// wiki describes, but handed the exact set instead of the whole world. +// +// The engine keeps active bubbles on an intrusive Storm `TSList` whose +// head is `VAR_CHAT_BUBBLE_LIST_HEAD` (`0x00B6F038`); each node's forward +// link sits at `+0x318` and the list terminator carries the low-bit +// sentinel. We mirror the engine's own walk in the per-frame update +// `FUN_004b1060` / teardown `FUN_004b0f80` verbatim. Bubbles whose owner +// unit has despawned are pruned on the engine's next update tick, so a +// just-orphaned bubble can linger one frame — harmless, and addons that +// care filter on `bubble:IsShown()` (a real method here) anyway. +// +// `includeForbidden` is accepted and ignored: vanilla has no forbidden +// frames, so every bubble is returned regardless. + +#include "Game.h" +#include "ui/FrameObject.h" + +#include + +namespace ChatBubble::Info { + +namespace { + +// Storm TSList of live CGChatBubbleFrames. Head pointer, per-node +// forward link, and the end-of-list low-bit sentinel — see the engine +// walks at 0x004b1060 / 0x004b0f80. +constexpr uintptr_t kListHead = 0x00B6F038; +constexpr int kOffNextLink = 0x318; + +} // namespace + +static int __fastcall Script_GetAllChatBubbles(void *L) { + Game::Lua::NewTable(L); + + uintptr_t node = *reinterpret_cast(kListHead); + int nextIndex = 1; + while (node != 0 && (node & 1) == 0) { + Game::Lua::PushNumber(L, static_cast(nextIndex++)); + UI::FrameObject::Push(L, reinterpret_cast(node)); + Game::Lua::SetTable(L, -3); + node = *reinterpret_cast(node + kOffNextLink); + } + return 1; +} + +static void RegisterLuaFunctions() { + Game::Lua::RegisterTableFunction("C_ChatBubbles", "GetAllChatBubbles", + &Script_GetAllChatBubbles); +} + +static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions}; + +} // namespace ChatBubble::Info diff --git a/src/nameplate/Info.cpp b/src/nameplate/Info.cpp index d54bab60..a362538f 100644 --- a/src/nameplate/Info.cpp +++ b/src/nameplate/Info.cpp @@ -56,6 +56,7 @@ #include "Offsets.h" #include "guid/Guid.h" #include "nameplate/Walk.h" +#include "ui/FrameObject.h" #include @@ -66,9 +67,6 @@ namespace { using NamePlate::Walk::ForEachNamePlatedUnit; using NamePlate::Walk::kOffUnitNamePlate; -using LuaRawGetI_t = void(__fastcall *)(void *L, int idx, int n); -using ScriptRegister_t = void(__fastcall *)(void *this_, void *edx_unused, - const char *name); using TokenToGUID_t = uint64_t(__fastcall *)(const char *token); using ResolveByGUID_t = void *(__fastcall *)(int type, const char *debugName, uint32_t guidLo, uint32_t guidHi, @@ -115,70 +113,13 @@ static int __fastcall Script_GetNamePlateGUIDs(void *L) { // frame-push path. Internal callers (Script_GetNamePlates etc.) call // it through the unqualified name (they live in the same namespace). // -// Delegate wrapper construction to the engine's own -// `FrameScript_Object::ScriptRegister`. First call for a never-seen -// nameplate builds a `{[0] = lightuserdata}` table with the -// framescript metatable, `luaL_ref`s it into the registry, and -// writes the refkey to `nameplate + 0x08` (`OFF_COBJECT_LUA_REGISTRY_REF`). -// Subsequent calls find a populated refkey and just rawgeti. -// -// Why delegate instead of building our own wrapper: -// -// - **Single source of truth.** Every code path that pushes this -// frame — ours via this function, addons' `CreateFrame("Type", -// "name", plate)` extracting the parent, the engine's own internal -// pushers — funnels through `rawgeti(REGISTRY, plate+0x08)` and -// gets the same Lua table. Earlier "build our own wrapper + -// `luaL_ref` it" approach kept a side cache, but pfUI's -// `CreateFrame("Button", "name", parent)` inside `NAME_PLATE_CREATED` -// ends up causing the engine to register the parent itself — -// the engine's wrapper diverges from ours, and later -// `GetNamePlateForUnit` calls return the engine's bare wrapper -// instead of our decorated one. Addon fields on the wrapper -// (`plate.nameplate = styledButton`) disappear from the API's -// perspective even though they still exist on the orphaned -// table. -// -// - **Refcount-pinning is benign here.** `ScriptRegister` -// unconditionally increments `nameplate + 0x04`, which normally -// keeps the engine from GC-ing the CObject. Nameplates are -// pool-managed and never destroyed during a session, so pinning -// doesn't actually leak anything. We call `ScriptRegister` at -// most once per nameplate pointer (gated by `refKey <= 0`), so -// the refcount tops out at one increment per pool slot. -// -// Defensive fallback: if the registry slot exists but isn't a table -// any more (some other code freed it), we re-register. This shouldn't -// happen in practice — engines only unref on frame destruction — -// but a stale type check keeps callers from ever seeing a non-table. +// Thin wrapper over the shared `UI::FrameObject::Push` — nameplates and +// chat bubbles are both engine-created-in-C++ `CSimpleFrame`s that need +// the same lazy `ScriptRegister` → `rawgeti` push so addons get the +// engine's canonical wrapper (see that helper for the pfUI-divergence +// rationale that motivated delegating to the engine). void PushNamePlateFrame(void *L, void *nameplate) { - auto rawgeti = reinterpret_cast( - Offsets::FUN_FRAMESCRIPT_PUSH_OBJECT); - auto scriptRegister = reinterpret_cast( - static_cast(Offsets::FUN_FRAMESCRIPT_OBJECT_SCRIPT_REGISTER)); - - int refKey = *reinterpret_cast( - static_cast(nameplate) + Offsets::OFF_COBJECT_LUA_REGISTRY_REF); - if (refKey <= 0) { - scriptRegister(nameplate, nullptr, nullptr); - refKey = *reinterpret_cast( - static_cast(nameplate) + Offsets::OFF_COBJECT_LUA_REGISTRY_REF); - } - - rawgeti(L, Game::Lua::REGISTRY_INDEX, refKey); - if (Game::Lua::Type(L, -1) == Game::Lua::TYPE_TABLE) - return; - Game::Lua::SetTop(L, -2); - - // Slot got freed somewhere — re-register to rebuild a fresh - // wrapper and slot. Zero the refcount so `ScriptRegister` - // re-enters its build branch. - *reinterpret_cast( - static_cast(nameplate) + Offsets::OFF_COBJECT_LUA_REFCOUNT) = 0; - scriptRegister(nameplate, nullptr, nullptr); - refKey = *reinterpret_cast( - static_cast(nameplate) + Offsets::OFF_COBJECT_LUA_REGISTRY_REF); - rawgeti(L, Game::Lua::REGISTRY_INDEX, refKey); + UI::FrameObject::Push(L, nameplate); } // GUID → nameplate Frame pushed on stack. Pushes nil if the GUID diff --git a/src/ui/FrameObject.cpp b/src/ui/FrameObject.cpp new file mode 100644 index 00000000..ed821f30 --- /dev/null +++ b/src/ui/FrameObject.cpp @@ -0,0 +1,86 @@ +// 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 "ui/FrameObject.h" + +#include "Game.h" +#include "Offsets.h" + +#include + +namespace UI::FrameObject { + +namespace { + +using LuaRawGetI_t = void(__fastcall *)(void *L, int idx, int n); +using ScriptRegister_t = void(__fastcall *)(void *this_, void *edx_unused, + const char *name); + +} // namespace + +// Delegate wrapper construction to the engine's own +// `FrameScript_Object::ScriptRegister`. First call for a never-seen frame +// builds a `{[0] = lightuserdata}` table with the framescript metatable, +// `luaL_ref`s it into the registry, and writes the refkey to `frame + +// 0x08` (`OFF_COBJECT_LUA_REGISTRY_REF`). Subsequent calls find a +// populated refkey and just rawgeti. +// +// Why delegate instead of building our own wrapper: single source of +// truth. Every code path that pushes this frame — ours, addons' +// `CreateFrame(..., parent)` extracting the frame, the engine's own +// pushers — funnels through `rawgeti(REGISTRY, frame + 0x08)` and gets the +// same Lua table, so addon fields set on the wrapper don't get orphaned +// onto a divergent copy. See the long note in `nameplate/Info.cpp`'s +// original implementation for the pfUI-divergence story that motivated +// this. +// +// `ScriptRegister` unconditionally bumps the CObject refcount at `+0x04`, +// which pins the frame against GC. That's benign for the pooled/permanent +// frames we push here (nameplates, chat bubbles) — we call it at most +// once per frame pointer (gated by `refKey <= 0`), so the refcount tops +// out at one increment per pool slot. +// +// Defensive fallback: if the registry slot exists but isn't a table any +// more (freed elsewhere), re-register to rebuild a fresh wrapper. This +// shouldn't happen in practice — engines only unref on frame destruction. +void Push(void *L, void *frame) { + auto rawgeti = reinterpret_cast( + Offsets::FUN_FRAMESCRIPT_PUSH_OBJECT); + auto scriptRegister = reinterpret_cast( + static_cast(Offsets::FUN_FRAMESCRIPT_OBJECT_SCRIPT_REGISTER)); + + auto *cobj = static_cast(frame); + int refKey = *reinterpret_cast( + cobj + Offsets::OFF_COBJECT_LUA_REGISTRY_REF); + if (refKey <= 0) { + scriptRegister(frame, nullptr, nullptr); + refKey = *reinterpret_cast( + cobj + Offsets::OFF_COBJECT_LUA_REGISTRY_REF); + } + + rawgeti(L, Game::Lua::REGISTRY_INDEX, refKey); + if (Game::Lua::Type(L, -1) == Game::Lua::TYPE_TABLE) + return; + Game::Lua::SetTop(L, -2); + + // Slot got freed somewhere — re-register to rebuild a fresh wrapper + // and slot. Zero the refcount so `ScriptRegister` re-enters its build + // branch. + *reinterpret_cast(cobj + Offsets::OFF_COBJECT_LUA_REFCOUNT) = 0; + scriptRegister(frame, nullptr, nullptr); + refKey = *reinterpret_cast( + cobj + Offsets::OFF_COBJECT_LUA_REGISTRY_REF); + rawgeti(L, Game::Lua::REGISTRY_INDEX, refKey); +} + +} // namespace UI::FrameObject diff --git a/src/ui/FrameObject.h b/src/ui/FrameObject.h new file mode 100644 index 00000000..67f8e718 --- /dev/null +++ b/src/ui/FrameObject.h @@ -0,0 +1,34 @@ +// 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 . + +#pragma once + +namespace UI::FrameObject { + +// Pushes a C++ `CFrameScriptObject`-derived frame onto the Lua stack as +// its canonical wrapper table — the same object every other engine path +// resolves via `rawgeti(REGISTRY, frame + 0x08)`, so addon-set fields on +// the wrapper survive roundtrips through our API and method dispatch +// (`:GetRegions()`, `:GetName()`, …) works normally. +// +// For frames the engine created purely in C++ without ever going through +// `CreateFrame` (default nameplates, chat bubbles), the registry ref at +// `+0x08` starts at 0; the first push delegates to the engine's own +// `FrameScript_Object::ScriptRegister` to lazily build the wrapper + +// registry slot. Subsequent pushes just `rawgeti` the cached slot. +// +// Leaves exactly one value (the wrapper table, or the re-registered +// fallback) on the stack. `frame` must be non-null. +void Push(void *L, void *frame); + +} // namespace UI::FrameObject