// 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 . // Persistent name cache — see NameCache.h for the motivating use case. // // Two persistence files: // // `WTF\Account\\ClassicAPI.txt` // Account-level setting — `PersistentNameCacheEnabled`. // Shared with other modules via the // [`Settings::Account`](../settings/Account.h) registry; we // register a section at static-init time with reset / serialize / // parse callbacks, and the registry handles load/save so neither // this module nor `Charlist::Order` clobbers the other's lines. // // `WTF\ClassicAPI\\\ClassicAPI_NameCache.txt` // Per-realm cache contents, SHARED across every account on the // same server. Keyed by realmlist address (unambiguous server // identity — can't collide across unrelated private servers) plus // the realm name, rather than by account, so alts on different // accounts pool into one file. Not under `Account\`, so we create // the directory tree ourselves. v4 format. One entry per line: // `name guid classID raceID sex` // (fields tab-separated). Loaded once the realm name is // available post-login (migrating a pre-existing per-account file // in on first load). Saved when (a) a recent write hasn't been // flushed AND (b) at least 30 seconds have elapsed since the prior // save, OR (c) DLL teardown / `Flush()` is called. // // Population sources: // 1. The engine's NameCache writer (`FUN_PLAYER_INFO_CACHE_WRITE`) // — every SMSG_NAME_QUERY_RESPONSE the engine processes flows // through here, and it is the only writer that fills an engine // NameCache row. Covers chat, group/raid sync, guild roster // updates, and every visible player (`CGUnit_C::GetUnitName` // 0x00609210 sends the query on a miss). // 2. `C_PlayerCache.RememberPlayer(guid, name, classToken)` from // Lua — lets addons feed in sources the engine cache doesn't // touch directly (e.g. /who results parsed via GetWhoInfo, // mouseover, target). // 3. A one-time import of the engine NameCache when the cache is // turned on. The hook only sees responses that arrive while the // cache is enabled, so rows the engine resolved earlier in the // session would otherwise stay missing until that player is // queried again. The engine keeps names in memory only, so a // fresh session starts empty and needs no import. // // Lookups are GUID-keyed. Names ARE the dedup signal though: vanilla // server-side names are unique per realm, so a fresh GUID claiming a // name we've already seen means the prior character was deleted and // the name recycled. The old GUID is dead (server won't honor it // again); keeping it just bloats the file. `EvictStaleGuidsForName` // drops the old entry on each write so the cache holds one entry per // name. #include "NameCache.h" #include "Game.h" #include "Offsets.h" #include "dbc/Names.h" #include "guid/Guid.h" #include "settings/Account.h" #include "unit/Identity.h" #include #include #include #include #include #include #include #include #include #include #include namespace Player::NameCache { namespace { // Backstop flush interval — explicit `Flush()` calls from DllMain's // `FrameScript_Initialize` hook (covers /reload and /logout) and // `DLL_PROCESS_DETACH` (clean /quit) are the primary save path. The // in-`Remember` `MaybeFlush` runs only as a defensive measure for // long sessions that never reload AND end via hard process kill // (task manager, OS crash) — in that case we bound data loss to // roughly this interval. 5 minutes was chosen as a compromise: // long enough that routine play has zero in-flight I/O, short // enough that a rare bad-shutdown loses at most ~5 min of new // entries. constexpr DWORD kFlushIntervalMs = 5 * 60 * 1000; // ChrClasses.dbc max ID. Anything above this is a corrupt input. constexpr uint32_t kMaxClassID = 16; // ChrRaces.dbc max ID. Vanilla has 8 (Human..Troll); allow some // headroom for private-server custom races. constexpr uint32_t kMaxRaceID = 16; // Wire sex values are 0/1. Any higher value is corrupt input. constexpr uint32_t kMaxSex = 1; // 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. // // Keys compare ignoring ASCII case, the same rule as the engine's own // name compares (SStrCmpI 0x0064A4C0 is a null-checked CRT _strnicmp), so // `"gedwyr"` finds `"Gedwyr"`. A re-cased name for the same GUID takes the // rename path in Upsert, so the newest spelling wins. struct NameHash { size_t operator()(const std::string &s) const { size_t h = 2166136261u; // FNV-1a over the lowercased bytes for (unsigned char c : s) h = (h ^ static_cast(c >= 'A' && c <= 'Z' ? c + 32 : c)) * 16777619u; return h; } }; struct NameEqual { bool operator()(const std::string &a, const std::string &b) const { return a.size() == b.size() && _strnicmp(a.c_str(), b.c_str(), a.size()) == 0; } }; std::unordered_map 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 g_guidIndex; bool g_enabled = false; bool g_cacheLoaded = false; bool g_dirty = false; DWORD g_lastSaveTick = 0; // ----- engine globals helpers (mirrors EquipmentSet::Storage) ----- const char *ReadAccountName() { return *reinterpret_cast( static_cast(Offsets::VAR_ACCOUNT_NAME_PTR)); } const char *ReadRealmName() { auto *info = *reinterpret_cast( static_cast(Offsets::VAR_REALM_INFO_PTR)); if (info == nullptr) return nullptr; return *reinterpret_cast( info + Offsets::OFF_REALM_INFO_NAME); } // ----- path resolution ----- // realmList CVar value (the realmlist address, e.g. // "logon.turtle-wow.org") — the unambiguous server identity. Unlike the // friendly realm name it can't collide across unrelated private servers, // so it's the outer key for the shared cache path. Mirrors // `Security::CredStore`'s realm scoping. const char *ReadRealmList() { using GetRealmList_t = const char *(__fastcall *)(int forceRefresh); return reinterpret_cast( static_cast(Offsets::FUN_CVAR_REALM_LIST))(0); } // Filesystem-safe path component. We create these directories ourselves // (WoW doesn't), so any character Windows rejects in a path — or that // could surprise, like the space/apostrophe in "N'Zoth" — becomes '_'. // Deterministic, so a realm always maps to the same folder. std::string SanitizeComponent(const char *s) { std::string out; for (const char *p = s; p != nullptr && *p; ++p) { const char c = *p; const bool safe = (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '.' || c == '-' || c == '_'; out.push_back(safe ? c : '_'); } return out; } // Shared, server-specific cache path: // WTF\ClassicAPI\\\ClassicAPI_NameCache.txt // Not under Account\, so alts on different accounts of the same server // share one pool. Empty (defer) until both realmlist + realm are known. std::string CachePath() { const char *realmList = ReadRealmList(); if (realmList == nullptr || realmList[0] == '\0') return {}; const char *realm = ReadRealmName(); if (realm == nullptr || realm[0] == '\0') return {}; std::string out = "WTF\\ClassicAPI\\"; out += SanitizeComponent(realmList); out += '\\'; out += SanitizeComponent(realm); out += "\\ClassicAPI_NameCache.txt"; return out; } // The pre-shared per-account path, used only to migrate an existing // cache into the shared location on first load. Built exactly as it was // written (raw account + realm, unsanitized) so it matches the file // sitting in WoW's own folders. std::string OldCachePath() { const char *account = ReadAccountName(); if (account == nullptr || account[0] == '\0') return {}; const char *realm = ReadRealmName(); if (realm == nullptr || realm[0] == '\0') return {}; std::string out = "WTF\\Account\\"; out += account; out += '\\'; out += realm; out += "\\ClassicAPI_NameCache.txt"; return out; } // Creates every parent directory of `filePath` (mkdir -p). WoW makes // `WTF\` but not `WTF\ClassicAPI\...`, and ofstream won't create // directories, so a save into a fresh realm folder would silently fail // without this. CreateDirectory on an existing dir no-ops. void EnsureParentDirs(const std::string &filePath) { for (size_t pos = 0;;) { const size_t slash = filePath.find('\\', pos); if (slash == std::string::npos) break; // remainder is the filename if (slash > 0) CreateDirectoryA(filePath.substr(0, slash).c_str(), nullptr); pos = slash + 1; } } // ----- account settings (registered with Settings::Account) ----- void SettingsReset() { g_enabled = false; } void SettingsSerialize(std::ostream &out) { out << "PersistentNameCacheEnabled=" << (g_enabled ? 1 : 0) << "\n"; } bool SettingsParse(const std::string &key, const std::string &value) { if (key == "PersistentNameCacheEnabled") { g_enabled = (value == "1" || value == "true"); return true; } return false; } const Settings::Account::AutoRegister _accountSettings{ &SettingsReset, &SettingsSerialize, &SettingsParse}; // ----- cache load/save ----- // Lightweight name sanitizer — vanilla player names are 2..12 ASCII // letters, but for paranoia drop anything that would break a line // (tab, newline) and cap length. Anything else passes through. std::string SanitizeName(const char *name) { if (name == nullptr) return {}; std::string out; for (const char *p = name; *p && out.size() < 16; ++p) { const char c = *p; if (c == '\t' || c == '\r' || c == '\n') continue; out.push_back(c); } return out; } // Inserts or updates an entry keyed by `name`, maintaining the // `g_guidIndex` reverse-map invariant. Handles three eviction cases: // // 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. // // `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; 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; } // Parses v4 cache lines (`name\tguid\tclass\trace\tsex`) from `file` // into the store. 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). Shared by the normal load and the one-time // migration from the old per-account file. void LoadFromStream(std::istream &file) { std::string line; while (std::getline(file, line)) { while (!line.empty() && (line.back() == '\r' || line.back() == '\n')) line.pop_back(); if (line.empty() || line[0] == '#') continue; std::istringstream is(line); 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(std::strtoul(classStr.c_str(), nullptr, 10)); const uint32_t raceID = static_cast(std::strtoul(raceStr.c_str(), nullptr, 10)); const uint32_t sex = static_cast(std::strtoul(sexStr.c_str(), nullptr, 10)); if (guid == 0 || sanitized.empty()) continue; if (classID > kMaxClassID || raceID > kMaxRaceID || sex > kMaxSex) continue; // 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); } } void LoadCacheIfNeeded() { if (g_cacheLoaded) return; const std::string path = CachePath(); if (path.empty()) return; // pre-realm; retry on next call (g_cacheLoaded stays false) g_cacheLoaded = true; std::ifstream file(path); if (file.is_open()) { LoadFromStream(file); return; } // No shared file yet. One-time migration: seed from the old // per-account file if it exists, then mark dirty so the next save // writes the merged data into the shared path. Only when the shared // file is absent — once it exists it's authoritative (a second // account's old-only entries just repopulate via scan / SMSG). const std::string oldPath = OldCachePath(); if (oldPath.empty()) return; std::ifstream oldFile(oldPath); if (oldFile.is_open()) { LoadFromStream(oldFile); g_dirty = true; } } void SaveCache() { const std::string path = CachePath(); if (path.empty()) return; // `WTF\ClassicAPI\\\` isn't created by WoW — make // the tree first, else the ofstream open below silently fails. EnsureParentDirs(path); const std::string tmp = path + ".tmp"; { std::ofstream out(tmp, std::ios::binary | std::ios::trunc); if (!out.is_open()) return; // Single hex GUID column with no leading zeros. Player GUIDs // (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. // 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, shared across accounts)\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), "\t%llX\t%u\t%u\t%u", static_cast(e.guid), e.classID, e.raceID, e.sex); out << name << buf << "\n"; } if (!out) return; } std::remove(path.c_str()); std::rename(tmp.c_str(), path.c_str()); g_dirty = false; g_lastSaveTick = GetTickCount(); } void MaybeFlush() { if (!g_dirty) return; const DWORD now = GetTickCount(); if ((now - g_lastSaveTick) < kFlushIntervalMs) return; SaveCache(); } // ----- engine NameCache mirror ----- // Mirrors one engine player-info record into our store. `record` is // either the SMSG_NAME_QUERY_RESPONSE buffer the writer consumes or the // cache row it produced — same layout (`OFF_PLAYER_INFO_*`). void RememberRecord(uint64_t guid, const uint8_t *record) { if (guid == 0) return; const char *name = reinterpret_cast( record + Offsets::OFF_PLAYER_INFO_NAME); const uint32_t classID = *reinterpret_cast( record + Offsets::OFF_PLAYER_INFO_CLASS); const uint32_t raceID = *reinterpret_cast( record + Offsets::OFF_PLAYER_INFO_RACE); const uint32_t sex = *reinterpret_cast( record + Offsets::OFF_PLAYER_INFO_SEX); if (name[0] == '\0') return; if (classID == 0 || classID > kMaxClassID) return; LoadCacheIfNeeded(); const std::string sanitized = SanitizeName(name); // Out-of-range race/sex mean the record 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(); } } // Copies every row the engine already resolved this session. Run when // the cache turns on, since the hook missed those responses. void ImportEngineCache() { Unit::Identity::ForEachCachedPlayer( [](uint64_t guid, const uint8_t *record, void *) { RememberRecord(guid, record); return true; }, nullptr); } // `__thiscall(this = cache, packet, guidLo, guidHi)`. We forward to // the original first (so the engine settles its entry and dispatches // callbacks), then mirror the packet's fields into our store. using CacheWrite_t = void(__thiscall *)(void *self, const uint8_t *packet, uint32_t guidLo, uint32_t guidHi); CacheWrite_t CacheWrite_o = nullptr; void __fastcall CacheWrite_h(void *self, void *edx, const uint8_t *packet, uint32_t guidLo, uint32_t guidHi) { // __fastcall stub forwards to __thiscall — MSVC's free-function // __fastcall lays out (ECX=self, EDX=unused, stack=packet, lo, hi), // matching the engine's __thiscall(self, packet, lo, hi). CacheWrite_o(self, packet, guidLo, guidHi); (void)edx; if (packet == nullptr || !IsEnabled()) return; RememberRecord((static_cast(guidHi) << 32) | guidLo, packet); } static const Game::HookAutoRegister _hookreg{ Offsets::FUN_PLAYER_INFO_CACHE_WRITE, reinterpret_cast(&CacheWrite_h), reinterpret_cast(&CacheWrite_o)}; // ----- Lua surface ----- // Thin shim around the centralized `Guid::Parse` so this TU's Lua // surface keeps a local symbol with its existing call shape. bool ParseGUID(const char *str, uint64_t *outGUID) { return Guid::Parse(str, outGUID); } // `C_PlayerCache.RememberPlayer(guid, name, classToken [, raceToken // [, sex]])` — stores the entry in the persistent cache. Class and // race tokens are uppercase engine tokens (`"WARRIOR"`, `"NIGHTELF"`, // etc.); sex is `0` (male) or `1` (female), matching the wire-format // convention the engine cache stores. Trailing args are optional — // passing only the first three preserves the old 3-arg signature. // Returns `true` on success, `false` if the cache is disabled or the // required args are malformed. int __fastcall Script_C_PlayerCache_RememberPlayer(void *L) { if (!IsEnabled()) { Game::Lua::PushBool(L, 0); return 1; } if (!Game::Lua::IsString(L, 1) || !Game::Lua::IsString(L, 2) || !Game::Lua::IsString(L, 3)) { Game::Lua::Error(L, "Usage: C_PlayerCache.RememberPlayer(guid, name, classToken [, raceToken [, sex]])"); return 0; } uint64_t guid; if (!ParseGUID(Game::Lua::ToString(L, 1), &guid) || guid == 0) { Game::Lua::PushBoolean(L, 0); return 1; } const char *name = Game::Lua::ToString(L, 2); if (name == nullptr || name[0] == '\0') { Game::Lua::PushBoolean(L, 0); return 1; } const char *classToken = Game::Lua::ToString(L, 3); const uint32_t classID = DBC::ClassIdForToken(classToken); // Optional race + sex. Missing / non-string / unknown values // resolve to 0, which Remember() treats as "leave existing value // alone" — so a 3-arg call preserves any prior race/sex data. uint32_t raceID = 0; if (Game::Lua::IsString(L, 4)) raceID = DBC::RaceIdForToken(Game::Lua::ToString(L, 4)); uint32_t sex = 0; if (Game::Lua::IsNumber(L, 5)) { const double raw = Game::Lua::ToNumber(L, 5); if (raw >= 0 && raw <= static_cast(kMaxSex)) sex = static_cast(raw); } // Remember treats sex==0 as "leave alone" since male and "unknown" // share the same wire value. To flip a wrongly-cached female back // to male, the SMSG hook path (which does direct assignment) is // the route — RememberPlayer is for additive updates from addon // sources that may or may not know sex. Remember(guid, name, classID, raceID, sex); Game::Lua::PushBoolean(L, 1); return 1; } // `C_PlayerCache.SetEnabled(bool)` — opt-in toggle for the persistent // name cache. Persists to the account-level settings file. Enabling // loads any prior cache contents for the current realm and imports // what the engine already resolved this session. int __fastcall Script_C_PlayerCache_SetEnabled(void *L) { Settings::Account::EnsureLoaded(); bool desired = false; if (Game::Lua::IsNumber(L, 1)) desired = Game::Lua::ToNumber(L, 1) != 0; else desired = Game::Lua::ToBoolean(L, 1) != 0; SetEnabled(desired); return 0; } int __fastcall Script_C_PlayerCache_IsEnabled(void *L) { Settings::Account::EnsureLoaded(); Game::Lua::PushBoolean(L, g_enabled); return 1; } void RegisterLuaFunctions() { Game::Lua::RegisterTableFunction("C_PlayerCache", "RememberPlayer", &Script_C_PlayerCache_RememberPlayer); Game::Lua::RegisterTableFunction("C_PlayerCache", "SetEnabled", &Script_C_PlayerCache_SetEnabled); Game::Lua::RegisterTableFunction("C_PlayerCache", "IsEnabled", &Script_C_PlayerCache_IsEnabled); } const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions}; } // namespace const Entry *Lookup(uint64_t guid, const std::string **outName) { if (outName != nullptr) *outName = nullptr; if (!IsEnabled()) return nullptr; LoadCacheIfNeeded(); auto guidIt = g_guidIndex.find(guid); if (guidIt == g_guidIndex.end()) return nullptr; 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 (name == nullptr || name[0] == '\0' || !IsEnabled()) return nullptr; LoadCacheIfNeeded(); auto it = g_entries.find(name); if (it == g_entries.end()) return nullptr; return &it->second; } void Remember(uint64_t guid, const char *name, uint32_t classID, uint32_t raceID, uint32_t sex) { if (guid == 0 || name == nullptr || name[0] == '\0' || !IsEnabled()) return; LoadCacheIfNeeded(); if (classID > kMaxClassID) classID = 0; if (raceID > kMaxRaceID) raceID = 0; if (sex > kMaxSex) sex = 0; const std::string sanitized = SanitizeName(name); if (Upsert(guid, sanitized, classID, raceID, sex)) { g_dirty = true; MaybeFlush(); } } // Every gate reads the toggle through here, never `g_enabled` directly: // nothing else guarantees the account settings are loaded before the // first name response arrives (only optional glue Lua calls into the // registry at character select). bool IsEnabled() { Settings::Account::EnsureLoaded(); return g_enabled; } void SetEnabled(bool enabled) { Settings::Account::EnsureLoaded(); if (g_enabled == enabled) return; g_enabled = enabled; Settings::Account::Save(); if (g_enabled) { LoadCacheIfNeeded(); ImportEngineCache(); } else if (g_dirty) { SaveCache(); } } void Flush() { if (!g_enabled || !g_dirty) return; // SaveCache resolves the path itself — returns silently if realm // name isn't available yet (pre-login). SaveCache(); } } // namespace Player::NameCache