PlayerCache: Key by name

This commit is contained in:
Brues
2026-05-15 16:00:19 -05:00
parent 5330c46e1d
commit a8a970a41d
3 changed files with 162 additions and 179 deletions
+15 -11
View File
@@ -112,11 +112,12 @@ int __fastcall Script_GetPlayerInfoByGUID(void *L) {
// enabled). Name + class + race + sex round-trip from disk;
// realm comes back "" since vanilla is single-realm and we
// never see the realm name as a per-player attribute.
const std::string *cachedName = nullptr;
const NameCache::Entry *cached = NameCache::Lookup(
(static_cast<uint64_t>(hi) << 32) | lo);
if (cached == nullptr || cached->name.empty())
(static_cast<uint64_t>(hi) << 32) | lo, &cachedName);
if (cached == nullptr || cachedName == nullptr || cachedName->empty())
return 0;
name = cached->name.c_str();
name = cachedName->c_str();
classID = cached->classID;
race = cached->raceID;
sex = cached->sex;
@@ -149,12 +150,15 @@ int __fastcall Script_GetPlayerInfoByGUID(void *L) {
return 7;
}
// Shared tuple builder used by both `GetPlayerInfoByGUID`'s
// NameCache-fallback path and `C_PlayerCache.GetPlayerInfoByName`.
// Pushes `(localizedClass, englishClass, localizedRace, englishRace,
// sex, name, realm)` from a NameCache entry. Realm is always "" —
// vanilla is single-realm and never propagates a per-player realm.
int PushFromNameCacheEntry(void *L, const NameCache::Entry &e) {
// Shared tuple builder used by `C_PlayerCache.GetPlayerInfoByName`
// (and useful for any other NameCache-fronted Lua surface). Pushes
// `(localizedClass, englishClass, localizedRace, englishRace, sex,
// name, realm)` — realm is always "" since vanilla is single-realm
// and never propagates a per-player realm. Name is passed separately
// because the cache's primary key (name) lives on the map slot, not
// inside the Entry value.
int PushFromNameCacheEntry(void *L, const char *name,
const NameCache::Entry &e) {
const char *englishClass = DBC::StringField(
Offsets::VAR_CHRCLASSES_RECORDS, Offsets::VAR_CHRCLASSES_COUNT,
e.classID, Offsets::OFF_CHRCLASSES_FILENAME);
@@ -173,7 +177,7 @@ int PushFromNameCacheEntry(void *L, const NameCache::Entry &e) {
Game::Lua::PushString(L, localizedRace ? localizedRace : "");
Game::Lua::PushString(L, englishRace ? englishRace : "");
Game::Lua::PushNumber(L, static_cast<double>(e.sex + 2));
Game::Lua::PushString(L, e.name.c_str());
Game::Lua::PushString(L, name);
Game::Lua::PushString(L, "");
return 7;
}
@@ -197,7 +201,7 @@ int __fastcall Script_C_PlayerCache_GetPlayerInfoByName(void *L) {
const NameCache::Entry *e = NameCache::LookupByName(name);
if (e == nullptr)
return 0;
PushFromNameCacheEntry(L, *e);
PushFromNameCacheEntry(L, name, *e);
char buf[Guid::STRING_SIZE];
Game::Lua::PushString(L, Guid::FormatAsString(e->guid, buf, sizeof buf));
return 8;
+105 -141
View File
@@ -100,13 +100,15 @@ constexpr uint32_t kMaxSex = 1;
// players in a static zone do basically nothing.
constexpr DWORD kScanIntervalMs = 10 * 1000;
std::unordered_map<uint64_t, Entry> g_entries;
// `name → guid` reverse index, maintained in lockstep with `g_entries`
// so `LookupByName` and `EvictStaleGuidsForName` are O(1). Invariant:
// `g_nameIndex[name] == guid` iff `g_entries[guid].name == name`.
// Vanilla 1.12 server-enforced per-realm name uniqueness means each
// name maps to at most one entry — the eviction logic preserves that.
std::unordered_map<std::string, uint64_t> g_nameIndex;
// Name-primary storage. Vanilla's per-realm name uniqueness makes
// name the natural identity key; deletion-recreation produces a new
// GUID for the same name, which inserts-replaces here instead of
// piling up dead entries the way a GUID-keyed map would.
std::unordered_map<std::string, Entry> g_entries;
// `guid → name` reverse index. Maintained in lockstep with
// `g_entries`. Invariant: `g_guidIndex[guid] == name` iff
// `g_entries[name].guid == guid`.
std::unordered_map<uint64_t, std::string> g_guidIndex;
bool g_enabled = false;
bool g_scanEnabled = false;
bool g_settingsLoaded = false;
@@ -227,27 +229,64 @@ std::string SanitizeName(const char *name) {
return out;
}
// Removes the cache entry whose name matches `name` if its GUID
// differs from `keepGuid`. Vanilla 1.12 enforces per-realm name
// uniqueness, so seeing the same name under a new GUID means the old
// character was deleted and the name recycled — that old GUID is
// dead, no addon should ever look it up again, and keeping it just
// bloats the file. Returns true if an entry was removed.
// Inserts or updates an entry keyed by `name`, maintaining the
// `g_guidIndex` reverse-map invariant. Handles three eviction cases:
//
// Bots and serial re-rollers are the motivating case: a single
// player remaking five times in a session leaves five entries under
// the same name with sequential GUIDs without this.
// 1. A prior entry exists under this name with a different GUID
// (name recycled — character deleted and recreated). Drop the
// old entry and its guid-index entry.
// 2. A prior entry exists under this GUID with a different name
// (character renamed — rare in vanilla but defensible). Drop
// the old name entry and its guid-index entry.
// 3. Same name + same GUID — update in place.
//
// O(1) via the `g_nameIndex` reverse map.
bool EvictStaleGuidsForName(const std::string &name, uint64_t keepGuid) {
if (name.empty())
// `classID` / `raceID` / `sex` of 0 mean "caller doesn't know" and
// don't overwrite an existing non-zero field. Returns true if any
// change occurred (caller marks the cache dirty for flushing).
bool Upsert(uint64_t guid, const std::string &name,
uint32_t classID, uint32_t raceID, uint32_t sex) {
if (name.empty() || guid == 0)
return false;
auto it = g_nameIndex.find(name);
if (it == g_nameIndex.end() || it->second == keepGuid)
return false;
g_entries.erase(it->second);
g_nameIndex.erase(it);
return true;
bool changed = false;
// Case 1: same name under a different GUID — recycled name.
auto nameIt = g_entries.find(name);
if (nameIt != g_entries.end() && nameIt->second.guid != guid) {
g_guidIndex.erase(nameIt->second.guid);
g_entries.erase(nameIt);
changed = true;
}
// Case 2: same GUID under a different name — rename.
auto guidIt = g_guidIndex.find(guid);
if (guidIt != g_guidIndex.end() && guidIt->second != name) {
g_entries.erase(guidIt->second);
g_guidIndex.erase(guidIt);
changed = true;
}
// Case 3: insert or update in place.
Entry &e = g_entries[name];
if (e.guid != guid) {
e.guid = guid;
changed = true;
}
if (classID != 0 && e.classID != classID) {
e.classID = classID;
changed = true;
}
if (raceID != 0 && e.raceID != raceID) {
e.raceID = raceID;
changed = true;
}
// sex == 0 is ambiguous (male AND "unknown") — only treat
// non-zero as authoritative.
if (sex != 0 && e.sex != sex) {
e.sex = sex;
changed = true;
}
g_guidIndex[guid] = name;
return changed;
}
void LoadCacheIfNeeded() {
@@ -262,9 +301,9 @@ void LoadCacheIfNeeded() {
if (!file.is_open())
return; // first run for this realm
// v3 format: `guid\tclass\trace\tsex\tname`. Single hex GUID
// column, no leading zeros — 1-8 hex digits for player GUIDs
// (high dword zero), up to 16 digits for non-player GUIDs.
// v4 format: `name\tguid\tclass\trace\tsex`. Name first since
// it's the primary key; GUID is a peripheral field carried for
// GUID-keyed lookups. Variable-width hex GUID (no leading zeros).
std::string line;
while (std::getline(file, line)) {
while (!line.empty() && (line.back() == '\r' || line.back() == '\n'))
@@ -273,44 +312,22 @@ void LoadCacheIfNeeded() {
continue;
std::istringstream is(line);
std::string guidStr, classStr, raceStr, sexStr, name;
if (!(is >> guidStr >> classStr >> raceStr >> sexStr))
continue;
// Consume the single tab/space, then read remaining name
// as-is (no spaces in vanilla names but tolerate them).
while (is.peek() == ' ' || is.peek() == '\t')
is.get();
std::getline(is, name);
if (name.empty())
std::string name, guidStr, classStr, raceStr, sexStr;
if (!(is >> name >> guidStr >> classStr >> raceStr >> sexStr))
continue;
const std::string sanitized = SanitizeName(name.c_str());
const uint64_t guid = std::strtoull(guidStr.c_str(), nullptr, 16);
const uint32_t classID = static_cast<uint32_t>(std::strtoul(classStr.c_str(), nullptr, 10));
const uint32_t raceID = static_cast<uint32_t>(std::strtoul(raceStr.c_str(), nullptr, 10));
const uint32_t sex = static_cast<uint32_t>(std::strtoul(sexStr.c_str(), nullptr, 10));
if (guid == 0)
if (guid == 0 || sanitized.empty())
continue;
if (classID > kMaxClassID || raceID > kMaxRaceID || sex > kMaxSex)
continue;
const std::string sanitized = SanitizeName(name.c_str());
if (sanitized.empty())
continue;
// Defensive dedup on load: if the file somehow has two rows
// for the same name (shouldn't with EvictStaleGuidsForName
// running at every save, but handle gracefully), the later
// row wins.
auto idx = g_nameIndex.find(sanitized);
if (idx != g_nameIndex.end() && idx->second != guid) {
g_entries.erase(idx->second);
g_nameIndex.erase(idx);
}
Entry &slot = g_entries[guid];
slot.guid = guid;
slot.name = sanitized;
slot.classID = classID;
slot.raceID = raceID;
slot.sex = sex;
g_nameIndex[sanitized] = guid;
// Upsert handles the rare same-name / same-guid dedup if the
// file has duplicate rows (shouldn't, but defensive).
Upsert(guid, sanitized, classID, raceID, sex);
}
}
@@ -327,15 +344,21 @@ void SaveCache() {
// (all we cache today) write as 1-8 hex digits since the high
// dword is always 0; non-player GUIDs would naturally extend
// to up to 16 digits if any ever landed here.
out << "# ClassicAPI name cache v3 (per-realm)\n";
out << "# guid\tclassID\traceID\tsex\tname\n";
// Name-primary v4 format. Name first since it's the primary
// identity (server-enforced unique per realm) and the natural
// sort/scan key when hand-editing. GUID is variable-width
// hex — 1-8 digits for player GUIDs, up to 16 if a non-player
// GUID ever lands here.
out << "# ClassicAPI name cache v4 (per-realm)\n";
out << "# name\tguid\tclassID\traceID\tsex\n";
for (const auto &kv : g_entries) {
const std::string &name = kv.first;
const Entry &e = kv.second;
char buf[80];
std::snprintf(buf, sizeof(buf), "%llX\t%u\t%u\t%u\t",
std::snprintf(buf, sizeof(buf), "\t%llX\t%u\t%u\t%u",
static_cast<unsigned long long>(e.guid),
e.classID, e.raceID, e.sex);
out << buf << e.name << "\n";
out << name << buf << "\n";
}
if (!out)
return;
@@ -397,40 +420,12 @@ void __fastcall CacheWrite_h(void *self, void *edx, const uint8_t *packet,
const uint64_t guid = (static_cast<uint64_t>(guidHi) << 32) | guidLo;
const std::string sanitized = SanitizeName(name);
if (EvictStaleGuidsForName(sanitized, guid))
g_dirty = true;
Entry &e = g_entries[guid];
bool changed = false;
if (e.guid != guid) {
e.guid = guid;
changed = true;
}
if (e.name != sanitized) {
// Drop the old name's index entry (if any) before re-pointing
// the index at the new name. Skips for fresh inserts where the
// old name is the empty string.
if (!e.name.empty())
g_nameIndex.erase(e.name);
e.name = sanitized;
g_nameIndex[sanitized] = guid;
changed = true;
}
if (e.classID != classID) {
e.classID = classID;
changed = true;
}
// Race/sex sanity-check against the same maxes Load enforces.
// Out-of-range values mean the packet didn't carry them (some
// entry types skip these fields); preserve any prior real data.
if (raceID != 0 && raceID <= kMaxRaceID && e.raceID != raceID) {
e.raceID = raceID;
changed = true;
}
if (sex <= kMaxSex && e.sex != sex) {
e.sex = sex;
changed = true;
}
if (changed) {
// Out-of-range race/sex mean the packet didn't carry them (some
// entry types skip these fields); pass 0 so `Upsert` preserves
// any prior real data.
const uint32_t safeRace = (raceID != 0 && raceID <= kMaxRaceID) ? raceID : 0;
const uint32_t safeSex = (sex <= kMaxSex) ? sex : 0;
if (Upsert(guid, sanitized, classID, safeRace, safeSex)) {
g_dirty = true;
MaybeFlush();
}
@@ -783,27 +778,31 @@ const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
} // namespace
const Entry *Lookup(uint64_t guid) {
const Entry *Lookup(uint64_t guid, const std::string **outName) {
if (outName != nullptr)
*outName = nullptr;
if (!g_enabled)
return nullptr;
LoadCacheIfNeeded();
auto it = g_entries.find(guid);
if (it == g_entries.end())
auto guidIt = g_guidIndex.find(guid);
if (guidIt == g_guidIndex.end())
return nullptr;
return &it->second;
auto entryIt = g_entries.find(guidIt->second);
if (entryIt == g_entries.end())
return nullptr; // shouldn't happen if invariant holds
if (outName != nullptr)
*outName = &entryIt->first;
return &entryIt->second;
}
const Entry *LookupByName(const char *name) {
if (!g_enabled || name == nullptr || name[0] == '\0')
return nullptr;
LoadCacheIfNeeded();
auto idx = g_nameIndex.find(name);
if (idx == g_nameIndex.end())
auto it = g_entries.find(name);
if (it == g_entries.end())
return nullptr;
auto entry = g_entries.find(idx->second);
if (entry == g_entries.end())
return nullptr; // shouldn't happen if invariant holds
return &entry->second;
return &it->second;
}
void Remember(uint64_t guid, const char *name, uint32_t classID,
@@ -818,42 +817,7 @@ void Remember(uint64_t guid, const char *name, uint32_t classID,
if (sex > kMaxSex)
sex = 0;
const std::string sanitized = SanitizeName(name);
if (EvictStaleGuidsForName(sanitized, guid))
g_dirty = true;
Entry &e = g_entries[guid];
bool changed = false;
if (e.guid != guid) {
e.guid = guid;
changed = true;
}
if (e.name != sanitized) {
// Maintain `g_nameIndex` invariant: drop the entry's prior
// name (if any) before re-pointing the index at the new one.
if (!e.name.empty())
g_nameIndex.erase(e.name);
e.name = sanitized;
g_nameIndex[sanitized] = guid;
changed = true;
}
// 0 means "caller doesn't know"; don't overwrite real data with
// unknown. Only update on real → real change.
if (classID != 0 && e.classID != classID) {
e.classID = classID;
changed = true;
}
if (raceID != 0 && e.raceID != raceID) {
e.raceID = raceID;
changed = true;
}
// sex == 0 is ambiguous (male AND "unknown"); we only treat
// non-zero (1 = female) as authoritative. Means we can't flip
// a wrongly-cached female back to male via Remember — but the
// SMSG hook path uses direct assignment so it self-corrects.
if (sex != 0 && e.sex != sex) {
e.sex = sex;
changed = true;
}
if (changed) {
if (Upsert(guid, sanitized, classID, raceID, sex)) {
g_dirty = true;
MaybeFlush();
}
+42 -27
View File
@@ -16,46 +16,61 @@
#include <cstdint>
#include <string>
// Opt-in persistent name cache, keyed by GUID. When enabled, every
// SMSG_NAME_QUERY_RESPONSE the engine processes — plus anything fed
// in via `C_PlayerCache.RememberPlayer` from Lua — is persisted to
// `WTF\Account\<acct>\<realm>\ClassicAPI_NameCache.txt` and survives
// across sessions on the same realm. Shared across all characters
// on that account+realm, so a 50-character bank alt's cache is
// available to the player's main without duplication.
// Opt-in persistent name cache, keyed by **name**. When enabled,
// every SMSG_NAME_QUERY_RESPONSE the engine processes — plus
// anything fed in via `C_PlayerCache.RememberPlayer` from Lua — is
// persisted to `WTF\Account\<acct>\<realm>\ClassicAPI_NameCache.txt`
// and survives across sessions on the same realm. Shared across all
// characters on that account+realm, so a 50-character bank alt's
// cache is available to the player's main without duplication.
//
// Use case: addons like pfUI's libunitscan currently keep their own
// per-character SVPC name DB to color chat names by class. With this
// enabled, `GetPlayerInfoByGUID` falls back to the persistent cache
// on engine miss, so chat coloring Just Works after a /reload — and
// the data isn't duplicated 50 times.
// per-character SVPC name DB to color chat names by class. With
// this enabled, `GetPlayerInfoByGUID` / `GetPlayerInfoByName` falls
// back to the persistent cache on engine miss, so chat coloring
// Just Works after a /reload — and the data isn't duplicated 50
// times.
//
// Storage model: **name is the primary key**. Vanilla 1.12 enforces
// per-realm name uniqueness server-side, so each name maps to at
// most one live character. GUIDs are unstable — character deletion
// + recreation produces a new GUID for the same name — so keying by
// GUID would mean storing dead identities and needing a name-based
// eviction pass to clean them up. Keying by name makes dedup
// natural (insert-replaces) and eliminates the stale-GUID problem.
// A `guid → name` reverse index gives O(1) lookups in both
// directions. GUIDs are still persisted so addons can recover a
// name from a stored GUID (combat-log replay, etc.).
namespace Player::NameCache {
struct Entry {
uint64_t guid; // full 64-bit GUID (hi << 32 | lo)
std::string name; // ASCII, <= 12 chars (vanilla cap)
uint32_t classID; // ChrClasses.dbc record ID (1..9), 0 if unknown
uint32_t raceID; // ChrRaces.dbc record ID (1..8), 0 if unknown
uint32_t sex; // 0 = male, 1 = female (wire convention), 0 if unknown
};
// Returns a pointer to the cached entry, or nullptr if not cached.
// The pointer is stable until the next `Remember` for the same GUID
// (which may relocate via map rehash). Treat as transient.
const Entry *Lookup(uint64_t guid);
// Same shape but indexed by name (case-sensitive, exact match). The
// underlying map is GUID-keyed, so this walks the entries — O(N) per
// call where N is total cached players. Cheap enough in practice
// (low thousands of entries; called only from addon chat-coloring
// paths that fire per chat-line render). Returns nullptr if no
// entry has that exact name.
// O(1) lookup by GUID via the reverse index. On hit, returns a
// pointer to the entry and writes the player's name to `*outName`.
// On miss, returns nullptr and sets `*outName` to nullptr. The
// returned pointer and `*outName` are stable until the next
// `Remember` / eviction; treat as transient.
//
// Used by `C_PlayerCache.GetPlayerInfoByName` for the case where an
// addon has a player's name (e.g., from a |Hplayer:Name|h chat link)
// but no GUID — `GetCurrentChatGUID()` returns nil for several chat
// event paths the engine doesn't tag with the sender's GUID.
// The name out-param is the entry's key in the primary map —
// passing it by pointer keeps it cheap (no string copy) and lets
// the caller read both halves from one lookup.
const Entry *Lookup(uint64_t guid, const std::string **outName);
// O(1) lookup by name (case-sensitive, exact match). Vanilla
// 1.12's server-stored names are case-stable, so `"Gedwyr"` won't
// match `"gedwyr"`. Returns nullptr if no entry has that name.
//
// Used by `C_PlayerCache.GetPlayerInfoByName` for the case where
// an addon has a player's name (e.g., from a `|Hplayer:Name|h`
// chat link or `CHAT_MSG_SYSTEM` string) but no GUID —
// `GetCurrentChatGUID()` returns nil for several chat event paths
// the engine doesn't tag with the sender's GUID.
const Entry *LookupByName(const char *name);
// Adds or updates an entry. Zero values for classID/raceID/sex are