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.
This commit is contained in:
Brues
2026-05-17 21:23:09 -05:00
parent 1c5879e74b
commit 2a7cbe2e59
5 changed files with 83 additions and 339 deletions
-1
View File
@@ -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` |
+83
View File
@@ -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.
-61
View File
@@ -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**
-34
View File
@@ -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
-243
View File
@@ -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 <https://www.gnu.org/licenses/>.
// `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 <cstdint>
#include <cstring>
#include <string>
#include <vector>
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<Snapshot> g_chars;
void TakeSnapshot() {
g_chars.clear();
const int count = *reinterpret_cast<const int *>(
static_cast<uintptr_t>(Offsets::VAR_CHARLIST_COUNT));
if (count <= 0)
return;
auto *base = *reinterpret_cast<const uint8_t *const *>(
static_cast<uintptr_t>(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<const char *>(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<const uint32_t *>(
r + Offsets::OFF_CHARRECORD_AREA_ID);
s.guid = *reinterpret_cast<const uint64_t *>(
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<double>(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<int>(Game::Lua::ToNumber(L, 1)) - 1;
if (idx < 0 || idx >= static_cast<int>(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<double>(s.level));
const char *area = DBC::LocalizedField(
Offsets::VAR_AREATABLE_RECORDS, Offsets::VAR_AREATABLE_COUNT,
static_cast<int>(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<double>(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<double>(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<double>(s.level));
const char *area = DBC::LocalizedField(
Offsets::VAR_AREATABLE_RECORDS, Offsets::VAR_AREATABLE_COUNT,
static_cast<int>(s.areaID), Offsets::OFF_AREATABLE_NAMES);
if (area != nullptr)
Game::Lua::SetFieldString(L, "areaName", area);
Game::Lua::SetFieldNumber(L, "sex", static_cast<double>(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<void *>(&CharlistFree_h),
reinterpret_cast<void **>(&CharlistFree_o)};
} // namespace Charlist::Cache