From c202c1000fcaa8b1769eec294e7ea9d726e18395 Mon Sep 17 00:00:00 2001
From: Brues <5278969+brues-code@users.noreply.github.com>
Date: Mon, 20 Jul 2026 23:00:03 -0500
Subject: [PATCH] chatbubbles: add C_ChatBubbles.GetAllChatBubbles
Returns the active chat-bubble Frame objects, matching modern WoW's
7.2.5 signature. Vanilla's CGChatBubbleFrames are full CSimpleFrames
the engine creates in C++ without CreateFrame (same as default
nameplates), kept on an intrusive Storm TSList at 0x00B6F038 (next
link +0x318, low-bit sentinel). Mirror the engine's own walk
(FUN_004b1060) and push each as its canonical engine wrapper, so the
returned frames are real and method-capable and their text FontString
(+0x31c) surfaces via :GetRegions().
includeForbidden is accepted and ignored (vanilla has no forbidden
frames).
Factor the ScriptRegister->rawgeti wrapper push out of nameplate/Info
into a shared UI::FrameObject::Push; PushNamePlateFrame now forwards to
it (no behavior change).
---
README.md | 1 +
docs/API.md | 39 +++++++++++++++++++
src/chatbubble/Info.cpp | 82 +++++++++++++++++++++++++++++++++++++++
src/nameplate/Info.cpp | 73 ++++------------------------------
src/ui/FrameObject.cpp | 86 +++++++++++++++++++++++++++++++++++++++++
src/ui/FrameObject.h | 34 ++++++++++++++++
6 files changed, 249 insertions(+), 66 deletions(-)
create mode 100644 src/chatbubble/Info.cpp
create mode 100644 src/ui/FrameObject.cpp
create mode 100644 src/ui/FrameObject.h
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