From 2a7cbe2e594af162c3462007da650e0154db15fb Mon Sep 17 00:00:00 2001 From: Brues <5278969+brues-code@users.noreply.github.com> Date: Sun, 17 May 2026 21:21:48 -0500 Subject: [PATCH] Remove C_CharacterList; preserve recovery notes in TODO #95 The single addon driving the C_CharacterList.* bindings moved off them; keeping the engine-hook surface live for a feature nobody calls is dead weight. Snapshot record layout, hook target, and the "why memory-only" rationale all land in TODO #95 so another DLL can pick it up without re-deriving any of it. --- README.md | 1 - TODO.md | 83 ++++++++++++++ docs/API.md | 61 ----------- src/Offsets.h | 34 ------ src/charlist/Cache.cpp | 243 ----------------------------------------- 5 files changed, 83 insertions(+), 339 deletions(-) delete mode 100644 src/charlist/Cache.cpp diff --git a/README.md b/README.md index 68f04714..f4b23828 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,6 @@ Full per-function reference: **[docs/API.md](docs/API.md)**. | Namespace | Calls | |-----------|-------| | AddOns | `C_AddOns.DoesAddOnExist`, `C_AddOns.GetAddOnName`, `C_AddOns.GetAddOnNotes`, `C_AddOns.GetAddOnSecurity`, `C_AddOns.GetAddOnTitle`, `C_AddOns.IsAddOnLoadable` | -| CharacterList | `C_CharacterList.GetCharacterInfo`, `C_CharacterList.GetCharacters`, `C_CharacterList.GetNumCharacters` | | Chat | `GetCurrentChatGUID` | | Class | `FillLocalizedClassList` | | Combat | `InCombatLockdown` | diff --git a/TODO.md b/TODO.md index 47acb267..781133d2 100644 --- a/TODO.md +++ b/TODO.md @@ -3062,3 +3062,86 @@ Required three pieces of new infrastructure, all in their own commits: - WoW.cfg was considered for persistence and rejected: extending the cfg parser is more invasive than a self-managed file under WTF, and we already have the `Settings::Account` shape. + +## 95. `C_CharacterList.*` — removed; notes for a future pickup + +We shipped `C_CharacterList.GetNumCharacters` / +`GetCharacterInfo(index)` / `GetCharacters()` for a while — +exposing the realm's character list (name, class, race, level, +area, sex, GUID) from anywhere in the game, not just the glue +char-select screen. The implementation was removed because the +single addon driving the need moved off it; keeping a binding +nobody calls is dead weight, and the engine-hook surface (the +char-list teardown function) is the kind of thing better owned by +whichever DLL actually uses it. The history is preserved in git +(see commits around `src/charlist/Cache.cpp`). + +If another project picks this up, the work is straightforward — +no novel reversing needed: + +### What the binding looked like + +Three Lua entry points, all under `C_CharacterList`: + +- `GetNumCharacters() -> n` +- `GetCharacterInfo(index) -> name, localizedRace, localizedClass, level, areaName, englishRace, sex, guid` +- `GetCharacters() -> { { name=, localizedRace=, englishRace=, localizedClass=, level=, areaName=, sex=, guid= }, ... }` + +`guid` was the 64-bit character GUID formatted with our +`Guid::FormatAsString` helper (16 hex digits, `"0x"` prefix — +matches `UnitGUID`'s convention). `areaName` was nil when the +character's last-known area wasn't in `AreaTable.dbc`. + +### Why it needed a DLL hook + +Vanilla 1.12's `GetCharacterInfo` / `GetNumCharacters` are +registered on the **glue** FrameScript engine and the underlying +data at `VAR_CHARLIST_ARRAY` (`0x00B42144`) / +`VAR_CHARLIST_COUNT` (`0x00B42140`) is freed by the +char-list teardown function during the glue→world transition. By +the time addons run in-world, the array is gone and the globals +are zeroed. + +The DLL hook took a snapshot of the records before the engine +freed them. + +### Implementation summary + +1. **Hook the teardown.** `FUN_CHARLIST_FREE` at `0x00472090` — + `__cdecl void()`, single caller (`FUN_0046AC90`, the + glue-shutdown wrapper that runs on world transition). Very + quiet hook target. Pre-hook (snapshot before the original runs); + the original then zeros the globals. + +2. **Iterate the record array.** Flat array, stride `0x120` + bytes. Field offsets within each record (derived from + `Script_GetCharacterInfo` disassembly at `0x004732A0`): + + | Offset | Field | Type / notes | + |--------|-------|---------------| + | `+0x00` | GUID | u64 (verified via `Script_RenameCharacter` at `0x00473520`) | + | `+0x08` | name | inline `char[]`, max 12 + NUL | + | `+0x3C` | areaID | u32, indexes `AreaTable.dbc` | + | `+0x100` | raceID | u8, indexes `ChrRaces.dbc` | + | `+0x101` | classID | u8, indexes `ChrClasses.dbc` | + | `+0x102` | sex | u8 (0/1) | + | `+0x108` | level | u8 | + +3. **Cache memory-only.** Every game launch hits char-select + before world-enter, so the cache is naturally rebuilt every + session. No filesystem persistence, no staleness across + restarts, no deleted-character bookkeeping (a server-side + delete drops the entry from the next `SMSG_CHAR_ENUM`). + +4. **Edge case.** If the DLL is injected mid-session + post-world-enter, the cache stays empty until the player + returns to char-select. Under normal VanillaFixes load order + that's not a concern (DLL loads before any Lua runs). + +### Why we used a memory-only cache, not the persistent file + +`Settings::Account` (the per-account WTF-file mechanism that backs +`GetSavedCharacterOrder`) is the wrong shape: it persists across +sessions, which would mean stale entries surviving server-side +deletes, and the data is already authoritative on each launch. +Memory-only is simpler and self-correcting. diff --git a/docs/API.md b/docs/API.md index 658abc43..ded3519e 100644 --- a/docs/API.md +++ b/docs/API.md @@ -164,8 +164,6 @@ build instructions. - [`IsSwimming()`](#isswimming) - [`IsAssistingRitual()`](#isassistingritual) - [CharacterList](#characterlist) - - [`C_CharacterList.GetNumCharacters()` / `GetCharacterInfo(index)`](#c_characterlistgetnumcharacters--getcharacterinfoindex) - - [`C_CharacterList.GetCharacters()`](#c_characterlistgetcharacters) - [`GetSavedCharacterOrder(realm)` / `SetSavedCharacterOrder(realm, order)` — GlueXML only](#getsavedcharacterorderrealm--setsavedcharacterorderrealm-order--gluexml-only) - [Chat](#chat) - [`GetCurrentChatGUID()`](#getcurrentchatguid) @@ -4266,65 +4264,6 @@ called before the player object is initialized (login screen). ## CharacterList -### `C_CharacterList.GetNumCharacters()` / `GetCharacterInfo(index)` - -Exposes the realm's character list (name, class, race, level, area, -sex, ghost flag) from anywhere in the game — vanilla's stock -`GetNumCharacters` / `GetCharacterInfo` are **glue-only** (registered -on the character-select FrameScript engine; the underlying data is -freed when the player enters the world). - -`GetCharacterInfo` returns an 8-tuple: `name, localizedRace, -localizedClass, level, areaName, englishRace, sex, guid`. -`areaName` is `nil` if the character's last-known area isn't in -`AreaTable.dbc`. `guid` is the 64-bit character GUID formatted as -a 16-hex-digit string (`"0x" + hi + lo`), same format as -`UnitGUID` returns. - -```lua -for i = 1, C_CharacterList.GetNumCharacters() do - local name, _, class, level, area = C_CharacterList.GetCharacterInfo(i) - print(name, class, "Lv", level, "in", area or "?") -end -``` - -### `C_CharacterList.GetCharacters()` - -Returns a numeric-keyed array of CharacterInfo tables — same data -as `GetCharacterInfo` but as struct-style tables with named fields. -Easier to consume when iterating the whole list. - -Each entry has: -- `name` — character name -- `localizedRace`, `englishRace` -- `localizedClass` -- `level` -- `areaName` (only present if the character's last-known area is - in `AreaTable.dbc`) -- `sex` (`0` or `1`) -- `guid` (16-hex-digit string, same format as `UnitGUID`) - -```lua -for _, c in ipairs(C_CharacterList.GetCharacters()) do - print(c.name, c.localizedClass, "Lv", c.level, c.guid) -end -``` - -> **How it works.** We hook the engine's char-list teardown function -> (`FUN_00472090`) and snapshot the array contents into our own -> cache before the engine frees them. Every time the player visits -> character-select (including the implicit visit at every game -> launch), the cache refreshes. Memory-only — no filesystem -> persistence — so deleted characters disappear from the cache on -> the next char-select visit, and there's no stale data across game -> restarts (every launch hits char-select before world-enter). -> -> **First-launch edge case.** If the DLL is loaded mid-session -> somehow (e.g. injected after world-enter), the cache will be -> empty until the player goes back to character-select. Under -> normal use (DLL loaded at game start via VanillaFixes) the cache -> is populated before any addon Lua runs. - ### `GetSavedCharacterOrder(realm)` / `SetSavedCharacterOrder(realm, order)` — GlueXML only > **GlueXML scope.** These globals are registered on the **glue** diff --git a/src/Offsets.h b/src/Offsets.h index 9aa5a4f2..c3856ff7 100644 --- a/src/Offsets.h +++ b/src/Offsets.h @@ -832,40 +832,6 @@ enum Offsets { VAR_AREATABLE_COUNT = 0x00C0E04C, OFF_AREATABLE_NAMES = 0x2C, - // Character-select character list. Populated by SMSG_CHAR_ENUM - // at glue, freed by `FUN_CHARLIST_FREE` on world-enter. Records - // are 0x120 bytes each in a flat array. - // - // We hook FUN_CHARLIST_FREE to snapshot the records into our own - // cache before the engine frees them, so `C_CharacterList.*` can - // read the data after the player is in-world (the underlying - // engine globals are zeroed at that point). - VAR_CHARLIST_COUNT = 0x00B42140, // int - VAR_CHARLIST_ARRAY = 0x00B42144, // CharRecord * - CHARLIST_RECORD_STRIDE = 0x120, - // Per-record field offsets, derived from Script_GetCharacterInfo - // disassembly (0x004732A0). - OFF_CHARRECORD_GUID = 0x00, // u64 character GUID - // (verified via - // Script_RenameCharacter at - // 0x00473520 reading - // `*puVar4` / `puVar4[1]` - // and passing them to the - // rename-by-GUID helper). - OFF_CHARRECORD_NAME = 0x08, // inline char[] (max 12 + NUL) - OFF_CHARRECORD_AREA_ID = 0x3C, // u32, indexes AreaTable.dbc - OFF_CHARRECORD_RACE = 0x100, // u8, indexes ChrRaces.dbc - OFF_CHARRECORD_CLASS = 0x101, // u8, indexes ChrClasses.dbc - OFF_CHARRECORD_SEX = 0x102, // u8 (0/1) - OFF_CHARRECORD_LEVEL = 0x108, // u8 - - // Char-list teardown — `__cdecl void()`, walks the record array - // calling a per-entry cleanup, `SMemFree`s the array, zeros the - // globals. Only one caller in the entire binary (FUN_0046AC90, - // the glue-shutdown wrapper that runs on world transition). Very - // quiet hook target. - FUN_CHARLIST_FREE = 0x00472090, - // Engine player-info cache — populated by the // SMSG_NAME_QUERY_RESPONSE handler (opcode 0x51) at 0x005551A0, // which reads (GUID, name[48], realm[256], race, sex, class) from diff --git a/src/charlist/Cache.cpp b/src/charlist/Cache.cpp deleted file mode 100644 index 7de05fca..00000000 --- a/src/charlist/Cache.cpp +++ /dev/null @@ -1,243 +0,0 @@ -// 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 . - -// `C_CharacterList.*` — exposes the realm's character list (name, -// class, race, level, etc.) from anywhere in the game, not just the -// character-select glue screen. -// -// Vanilla 1.12's `GetCharacterInfo` / `GetNumCharacters` are -// **glue-only** — registered on the glue FrameScript engine, the -// underlying data structure at `VAR_CHARLIST_ARRAY` is freed by -// `FUN_CHARLIST_FREE` (`0x00472090`) during the world-transition -// path. By the time a player is in-world, the data is gone. -// -// We hook `FUN_CHARLIST_FREE` to snapshot the array contents into -// our own cache before the engine frees them. Subsequent -// world-enters re-fetch SMSG_CHAR_ENUM and re-call the teardown, so -// our cache gets refreshed each time. Deleting a character refreshes -// the cache on the next char-select visit (server sends a new -// SMSG_CHAR_ENUM without the deleted character). -// -// The cache is **memory-only** — every game start re-fetches char- -// select before world-enter, so the cache is naturally rebuilt on -// every launch. No filesystem persistence, no staleness across game -// restarts, no need to deal with deleted-character entries. -// -// Hook target: `FUN_CHARLIST_FREE` has exactly one caller -// (FUN_0046AC90, the glue-shutdown wrapper). Not a target other DLLs -// touch. - -#include "Game.h" -#include "Offsets.h" -#include "dbc/Lookup.h" -#include "guid/Guid.h" - -#include -#include -#include -#include - -namespace Charlist::Cache { - -namespace { - -struct Snapshot { - std::string name; - uint8_t raceID; - uint8_t classID; - uint8_t level; - uint8_t sex; - uint32_t areaID; - uint64_t guid; -}; - -// Replaced wholesale on every teardown — we always reflect the most -// recently-observed char-select state. Read by the Lua bindings. -std::vector g_chars; - -void TakeSnapshot() { - g_chars.clear(); - const int count = *reinterpret_cast( - static_cast(Offsets::VAR_CHARLIST_COUNT)); - if (count <= 0) - return; - auto *base = *reinterpret_cast( - static_cast(Offsets::VAR_CHARLIST_ARRAY)); - if (base == nullptr) - return; - g_chars.reserve(count); - for (int i = 0; i < count; ++i) { - const uint8_t *r = base + i * Offsets::CHARLIST_RECORD_STRIDE; - Snapshot s; - s.name = reinterpret_cast(r + Offsets::OFF_CHARRECORD_NAME); - s.raceID = *(r + Offsets::OFF_CHARRECORD_RACE); - s.classID = *(r + Offsets::OFF_CHARRECORD_CLASS); - s.sex = *(r + Offsets::OFF_CHARRECORD_SEX); - s.level = *(r + Offsets::OFF_CHARRECORD_LEVEL); - s.areaID = *reinterpret_cast( - r + Offsets::OFF_CHARRECORD_AREA_ID); - s.guid = *reinterpret_cast( - r + Offsets::OFF_CHARRECORD_GUID); - g_chars.push_back(std::move(s)); - } -} - -// `C_CharacterList.GetNumCharacters()` — count of cached characters. -// Returns 0 if char-select never ran since DLL load (unlikely; every -// game launch hits char-select before world-enter). -int __fastcall Script_GetNumCharacters(void *L) { - Game::Lua::PushNumber(L, static_cast(g_chars.size())); - return 1; -} - -// `C_CharacterList.GetCharacterInfo(index)` — same 8-return tuple -// as the glue-only `GetCharacterInfo`, available from in-world: -// -// name, localizedRace, localizedClass, level, areaName, -// englishRace, sex, isGhost -// -// `englishRace` is the ChrRaces.dbc filename field (untranslated). -// `isGhost` is nil for live characters, 1 for ghost. -int __fastcall Script_GetCharacterInfo(void *L) { - if (!Game::Lua::IsNumber(L, 1)) { - Game::Lua::Error(L, "Usage: C_CharacterList.GetCharacterInfo(index)"); - return 0; - } - const int idx = static_cast(Game::Lua::ToNumber(L, 1)) - 1; - if (idx < 0 || idx >= static_cast(g_chars.size())) - return 0; - const Snapshot &s = g_chars[idx]; - - Game::Lua::PushString(L, s.name.c_str()); - - const char *localRace = DBC::LocalizedField( - Offsets::VAR_CHRRACES_RECORDS, Offsets::VAR_CHRRACES_COUNT, - s.raceID, Offsets::OFF_CHRRACES_NAMES); - if (localRace != nullptr) Game::Lua::PushString(L, localRace); - else Game::Lua::PushString(L, ""); - - const char *localClass = DBC::LocalizedField( - Offsets::VAR_CHRCLASSES_RECORDS, Offsets::VAR_CHRCLASSES_COUNT, - s.classID, Offsets::OFF_CHRCLASSES_NAMES); - if (localClass != nullptr) Game::Lua::PushString(L, localClass); - else Game::Lua::PushString(L, ""); - - Game::Lua::PushNumber(L, static_cast(s.level)); - - const char *area = DBC::LocalizedField( - Offsets::VAR_AREATABLE_RECORDS, Offsets::VAR_AREATABLE_COUNT, - static_cast(s.areaID), Offsets::OFF_AREATABLE_NAMES); - if (area != nullptr) Game::Lua::PushString(L, area); - else Game::Lua::PushNil(L); - - const char *englishRace = DBC::StringField( - Offsets::VAR_CHRRACES_RECORDS, Offsets::VAR_CHRRACES_COUNT, - s.raceID, Offsets::OFF_CHRRACES_FILENAME); - Game::Lua::PushString(L, englishRace != nullptr ? englishRace : ""); - - Game::Lua::PushNumber(L, static_cast(s.sex)); - - // GUID is a 64-bit value; Lua doubles can't carry full precision - // past 2^53. Format as `0x` + 16-hex-digit string (hi then lo, - // matching `UnitGUID`'s convention) so addons can use it as a - // stable string identifier. - char buf[Guid::STRING_SIZE]; - Game::Lua::PushString(L, Guid::FormatAsString(s.guid, buf, sizeof buf)); - - return 8; -} - -// `C_CharacterList.GetCharacters()` — returns a numeric-keyed table -// of CharacterInfo tables. Each entry is a struct-style table with -// the same fields `GetCharacterInfo` returns as a tuple, but named. -// Easier to consume than the multi-return form when iterating the -// whole list: -// -// for _, c in ipairs(C_CharacterList.GetCharacters()) do -// print(c.name, c.localizedClass, "Lv", c.level, c.guid) -// end -int __fastcall Script_GetCharacters(void *L) { - Game::Lua::SetTop(L, 0); - Game::Lua::NewTable(L); - - for (size_t i = 0; i < g_chars.size(); ++i) { - const Snapshot &s = g_chars[i]; - - // Stack: [outer-table] - Game::Lua::PushNumber(L, static_cast(i + 1)); - Game::Lua::NewTable(L); - // Stack: [outer-table, key, inner-table] - - Game::Lua::SetFieldString(L, "name", s.name.c_str()); - - Game::Lua::SetFieldString(L, "localizedRace", DBC::LocalizedField( - Offsets::VAR_CHRRACES_RECORDS, Offsets::VAR_CHRRACES_COUNT, - s.raceID, Offsets::OFF_CHRRACES_NAMES)); - - Game::Lua::SetFieldString(L, "englishRace", DBC::StringField( - Offsets::VAR_CHRRACES_RECORDS, Offsets::VAR_CHRRACES_COUNT, - s.raceID, Offsets::OFF_CHRRACES_FILENAME)); - - Game::Lua::SetFieldString(L, "localizedClass", DBC::LocalizedField( - Offsets::VAR_CHRCLASSES_RECORDS, Offsets::VAR_CHRCLASSES_COUNT, - s.classID, Offsets::OFF_CHRCLASSES_NAMES)); - - Game::Lua::SetFieldNumber(L, "level", static_cast(s.level)); - - const char *area = DBC::LocalizedField( - Offsets::VAR_AREATABLE_RECORDS, Offsets::VAR_AREATABLE_COUNT, - static_cast(s.areaID), Offsets::OFF_AREATABLE_NAMES); - if (area != nullptr) - Game::Lua::SetFieldString(L, "areaName", area); - - Game::Lua::SetFieldNumber(L, "sex", static_cast(s.sex)); - - char buf[Guid::STRING_SIZE]; - Game::Lua::SetFieldString(L, "guid", - Guid::FormatAsString(s.guid, buf, sizeof buf)); - - // Insert inner-table into outer-table at numeric key. - Game::Lua::SetTable(L, -3); - } - - return 1; -} - -void RegisterLuaFunctions() { - Game::Lua::RegisterTableFunction("C_CharacterList", "GetNumCharacters", - &Script_GetNumCharacters); - Game::Lua::RegisterTableFunction("C_CharacterList", "GetCharacterInfo", - &Script_GetCharacterInfo); - Game::Lua::RegisterTableFunction("C_CharacterList", "GetCharacters", - &Script_GetCharacters); -} - -} // namespace - -// `FUN_CHARLIST_FREE` — `__cdecl void()`. We snapshot the records -// BEFORE running the original, so the cache is populated by the time -// the engine zeros the globals. -using CharlistFree_t = void(__cdecl *)(); -CharlistFree_t CharlistFree_o = nullptr; -void __cdecl CharlistFree_h() { - TakeSnapshot(); - CharlistFree_o(); -} - -static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions}; -static const Game::HookAutoRegister _hookreg{ - Offsets::FUN_CHARLIST_FREE, - reinterpret_cast(&CharlistFree_h), - reinterpret_cast(&CharlistFree_o)}; - -} // namespace Charlist::Cache