diff --git a/TODO.md b/TODO.md index e92d3077..385f401e 100644 --- a/TODO.md +++ b/TODO.md @@ -148,7 +148,29 @@ The investigation needed three engine pieces nobody had documented: Full notes in [CLAUDE.md](CLAUDE.md) under "Firing a custom event end-to-end". -## ~~14. `GetFactionInfoByID` / `GetFactionIDByIndex`~~ — DONE (not in original list) +## ~~14. `C_QuestLog.RequestLoadQuestByID` + `QUEST_DATA_LOAD_RESULT`~~ — DONE (not in original list) + +Fires `QUEST_DATA_LOAD_RESULT(questID, success)` when quest static info +(description, objectives, reward text) finishes loading. Synchronously +fired when the questID was already in the client cache; asynchronously +fired after `SMSG_QUEST_QUERY_RESPONSE` when the engine has to round-trip. + +Implemented as a near-direct mirror of `Item::Data`: the quest cache +`_GetRecord` at `0x00562A40` has the same five-arg shape and the same +`callback != NULL` gate as the item cache `_GetRecord`. The interesting +investigation was confirming that `[0x00BB7480]` (passed as the cache +key in `Script_GetQuestLogQuestText`) is a *questID*, not a struct +pointer — verified by tracing the load site at `0x004DEF5D` back through +`mov eax, [esi + 0x00BB71C0]`, which reads field +0 of a quest log +entry (= questID per the quest log struct). The cache is then keyed by +questID just like the item cache is keyed by itemID. + +See [src/quest/Data.cpp](src/quest/Data.cpp) and "Quest static-info +cache" in [CLAUDE.md](CLAUDE.md). The custom-event plumbing +([src/event/Custom.cpp](src/event/Custom.cpp)) is shared with +`ITEM_DATA_LOAD_RESULT` — no new infrastructure needed. + +## ~~15. `GetFactionInfoByID` / `GetFactionIDByIndex`~~ — DONE (not in original list) `GetFactionInfoByID(factionID)` returns the same 11 values as `GetFactionInfo(factionIndex)` keyed by factionID — implemented as a thin diff --git a/src/Offsets.h b/src/Offsets.h index e9ea1ca2..db208965 100644 --- a/src/Offsets.h +++ b/src/Offsets.h @@ -165,6 +165,32 @@ enum Offsets { VAR_FACTION_DISPLAY_COUNT = 0x00B73764, VAR_FACTION_VISIBLE_MAX_INDEX = 0x00B73760, + // Quest static-info cache (the client-side cache of QUEST_QUERY_RESPONSE + // payloads — descriptions, objectives, reward text). Same five-arg + // `_GetRecord` shape as the item cache, keyed by questID. Verified by + // tracing `Script_GetQuestLogQuestText` (`0x004DFF20`): + // 1. `[VAR_QUEST_LOG_SELECTED_QUEST_ID]` is the *questID* of the + // selected entry (not a pointer) — populated from + // `mov eax, [esi + 0x00BB71C0]` which reads field +0 of a + // `VAR_QUEST_LOG_ENTRIES` row, i.e. the questID itself. + // 2. That value is passed as the `key` arg to `_GetRecord`, then + // hashed via `key & cache.mask` and matched with `cmp [bucket], key`. + // + // Cache-hit-already-loaded shortcut: if `[entry+0x18F8]` is set, the + // function returns `entry+0x18` immediately and does NOT invoke the + // queued callback. Modules that want a notification regardless of + // cache state must fire it themselves (see `Item::Data` for the same + // pattern). + // + // Callback shape verified at the dispatch sites near 0x00562EEB et al.: + // `mov ecx, [entry+0x18]; push 1; push ecx; call [entry+8]` + // → `__stdcall(void *userData, int success)` where `userData` is + // `arg4` we passed to `_GetRecord` (engine stores it at + // `entry+0x18` and replays it without dereferencing). + VAR_QUEST_CACHE = 0x00C0E1B0, + FUN_DBCACHE_QUEST_GET_RECORD = 0x00562A40, + VAR_QUEST_LOG_SELECTED_QUEST_ID = 0x00BB7480, + // Quest log: 16-byte-stride entry array and active count. // Field +0 of each entry is the questID for real quests (a category index // for headers); field +8 is the header indicator: non-NULL = header, diff --git a/src/quest/Data.cpp b/src/quest/Data.cpp new file mode 100644 index 00000000..4d5e3463 --- /dev/null +++ b/src/quest/Data.cpp @@ -0,0 +1,110 @@ +// 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 . + +#include "Game.h" +#include "Offsets.h" +#include "event/Custom.h" + +#include + +namespace Quest::Data { + +// Engine cache `_GetRecord` for quest static info, mirroring the +// `Item::Data` shape but with one extra "context" arg that the engine +// uses for its own bookkeeping (we pass an 8-byte zero block; see +// `Script_GetQuestLogQuestText` at `0x004DFF20` for the same usage). +// +// __thiscall(this=cache, questID, &outBuf, callback, userData, unused) +// +// `outBuf` provides 8 bytes that get copied into the pending entry at +// +0x10/+0x14 — engine bookkeeping, not exposed to the callback. The +// callback receives `userData` (arg4) as its first argument. +using GetQuestRecord_t = const uint8_t *(__thiscall *)(void *cache, uint32_t questID, + void *outBuf, void *callback, + void *userData, int unused); + +static constexpr const char *kQuestDataLoadResult = "QUEST_DATA_LOAD_RESULT"; + +// Same `__stdcall(userData, success)` shape as `Item::Data::ItemLoadCallback`. +// The engine's invocation pattern at 0x00562EEB et al. is: +// mov ecx, [entry+0x18] ; userData (= arg4 we passed to _GetRecord) +// push 1 ; success (1/0) +// push ecx ; userData +// call [entry+0x08] ; this callback +// `ret 8` cleans both args. We encode the questID into `userData` at +// request time so the callback knows which quest completed. +static void __stdcall QuestLoadCallback(void *userData, int success) { + const int slot = Event::Custom::Register(kQuestDataLoadResult); + if (slot < 0) + return; + const auto questID = + static_cast(reinterpret_cast(userData)); + Event::Custom::Fire_DD(slot, questID, success ? 1 : 0); +} + +// Calls the quest cache `_GetRecord`. With `fireRequest=false`, performs +// only the hash-table lookup; returns the cached record (`entry+0x18`) if +// the data is fully loaded (engine checks `[entry+0x18F8]`), or nullptr +// otherwise. With `fireRequest=true`, queues a CMSG_QUEST_QUERY when the +// data isn't already loaded — engine fills the cache asynchronously and +// invokes our callback when the SMSG_QUEST_QUERY_RESPONSE lands. +// +// **Cache-hit-already-loaded path does NOT invoke the callback** — the +// engine returns `entry+0x18` directly. Callers that want notification +// regardless of cache state must fire `QUEST_DATA_LOAD_RESULT` themselves +// for that branch (see `RequestAndMaybeNotify`). +static const uint8_t *CacheFetch(uint32_t questID, bool fireRequest) { + auto fn = reinterpret_cast(Offsets::FUN_DBCACHE_QUEST_GET_RECORD); + auto *cache = reinterpret_cast(Offsets::VAR_QUEST_CACHE); + uint64_t outBuf = 0; // 8-byte zero block (matches engine's own pattern) + void *callback = fireRequest ? reinterpret_cast(&QuestLoadCallback) : nullptr; + void *userData = + fireRequest ? reinterpret_cast(static_cast(questID)) : nullptr; + return fn(cache, questID, &outBuf, callback, userData, 0); +} + +static void RequestAndMaybeNotify(uint32_t questID) { + const bool wasCached = (CacheFetch(questID, false) != nullptr); + CacheFetch(questID, true); + if (wasCached) { + const int slot = Event::Custom::Register(kQuestDataLoadResult); + if (slot >= 0) + Event::Custom::Fire_DD(slot, static_cast(questID), 1); + } +} + +static int __fastcall Script_RequestLoadQuestByID(void *L) { + if (!Game::Lua::IsNumber(L, 1)) { + Game::Lua::Error(L, "Usage: C_QuestLog.RequestLoadQuestByID(questID)"); + return 0; + } + const int questID = static_cast(Game::Lua::ToNumber(L, 1)); + if (questID <= 0) + return 0; + RequestAndMaybeNotify(static_cast(questID)); + return 0; +} + +static void RegisterLuaFunctions() { + Game::Lua::RegisterTableFunction("C_QuestLog", "RequestLoadQuestByID", + &Script_RequestLoadQuestByID); + + // Seed the event-name cache so `Event::Custom::RetryAll` (driven by + // our hook on `Frame::RegisterEvent`) can claim a slot once the + // engine's event table is populated. Same pattern as Item::Data. + Event::Custom::Register(kQuestDataLoadResult); +} + +static const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions}; + +} // namespace Quest::Data