From 359eff416a411bdf3a6a39cea6d2b06d63b82c55 Mon Sep 17 00:00:00 2001 From: Sam Sung <51686767+samwhosung@users.noreply.github.com> Date: Sat, 24 Oct 2026 20:34:38 +0700 Subject: [PATCH] Template caches persist between sessions, as 1.12.1's do (#2352) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Item, object, quest and text records are kept between sessions, as 1.12.1 keeps its template caches. - **Which stores persist:** each store's constructor sets a persist byte at `+0x39`. The creature, game object, item name, item, NPC text, quest, page text and item text stores are saved. The name, guild, pet-name and petition stores are session-only and cleared at world entry (`0x555740`). - **The file:** one per store per realm under `benilla-config/cache/`, in the reference's layout, header-checked (build, locale, record size), with a hit sending no query (`0x5586ca`). The records are the server's answer bytes, decoded on load by the live decoder. - **The item-name store** answers `CMSG_ITEM_NAME_QUERY` (`0x559fe0`), and item-set member names read it. - **Cleanup:** the old creature-only file is removed on load, and three comments that called the name caches persistent are corrected. Tests cover every store across a session, header mismatches, eviction and the live packet path. Fixes #85 πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 5.5 --- crates/benilla-app/src/game_plugins.rs | 9 +- crates/benilla-app/src/go_templates.rs | 9 + crates/benilla-app/src/item_names.rs | 73 ++ crates/benilla-app/src/items.rs | 18 + crates/benilla-app/src/lanes/guard_tests.rs | 4 +- crates/benilla-app/src/lib.rs | 3 +- crates/benilla-app/src/local_state.rs | 21 +- crates/benilla-app/src/name_persist.rs | 249 ------- crates/benilla-app/src/names.rs | 343 ++------- crates/benilla-app/src/net.rs | 5 + crates/benilla-app/src/net/io.rs | 17 +- crates/benilla-app/src/query_cache.rs | 2 + crates/benilla-app/src/ui_gossip/mod.rs | 18 +- crates/benilla-app/src/ui_guild/mod.rs | 14 +- crates/benilla-app/src/ui_item_text.rs | 11 +- crates/benilla-app/src/ui_items/feed.rs | 56 +- crates/benilla-app/src/ui_mail/mod.rs | 12 +- crates/benilla-app/src/ui_petition/mod.rs | 19 + crates/benilla-app/src/ui_quest_log.rs | 19 +- crates/benilla-app/src/ui_stable/net.rs | 2 +- crates/benilla-app/src/wdb.rs | 560 ++++++++++++++ crates/benilla-app/src/wdb/tests.rs | 693 ++++++++++++++++++ crates/benilla-protocol/src/events.rs | 6 + crates/benilla-protocol/src/events/decode.rs | 3 + crates/benilla-protocol/src/messages/items.rs | 21 + crates/benilla-protocol/src/messages/mod.rs | 4 +- .../benilla-protocol/src/messages/opcode.rs | 5 + .../benilla-protocol/src/messages/packet.rs | 8 +- crates/benilla-protocol/src/messages/parse.rs | 8 +- .../src/world/writer/items.rs | 8 + crates/benilla-protocol/tests/items.rs | 30 + docs/DEVIATIONS.md | 29 +- docs/MAP.md | 4 +- 33 files changed, 1675 insertions(+), 608 deletions(-) create mode 100644 crates/benilla-app/src/item_names.rs delete mode 100644 crates/benilla-app/src/name_persist.rs create mode 100644 crates/benilla-app/src/wdb.rs create mode 100644 crates/benilla-app/src/wdb/tests.rs diff --git a/crates/benilla-app/src/game_plugins.rs b/crates/benilla-app/src/game_plugins.rs index 02f97cb5c..692894657 100644 --- a/crates/benilla-app/src/game_plugins.rs +++ b/crates/benilla-app/src/game_plugins.rs @@ -24,7 +24,6 @@ use crate::entities::EntitiesPlugin; use crate::fishing_line::FishingLinePlugin; use crate::footprints::FootprintsPlugin; use crate::loading_screen::LoadingScreenPlugin; -use crate::name_persist::NamePersistPlugin; use crate::net::NetPlugin; use crate::player::PlayerPlugin; use crate::portrait::PortraitPlugin; @@ -232,7 +231,8 @@ impl PluginGroup for GamePlugins { .add(UiTradePlugin) .add(UiItemTextPlugin) .add(UiSavedPlugin) - .add(NamePersistPlugin) + .add(crate::item_names::ItemNamesPlugin) + .add(crate::wdb::WdbPlugin) .add(UiStablePlugin) .add(TabardUiPlugin) .add(UiTrainerPlugin) @@ -976,9 +976,8 @@ pub(crate) mod schedule_tests { /// against the 80 world systems no declared order places against it, which bevy lists with /// no component. What they meet of the drain's (its lanes' firings, the VM with the call host, /// and the unit edits it applies in place: every component a change writes, the cast events, - /// the precast tail's loot release) is the name cache alone, a pure cache, which the - /// persisted-name load writes; `lanes::guard_tests` checks that it stays so, and that no - /// exclusive system is among them. Commands a firing defers, which the drain applies after + /// the precast tail's loot release) is the name cache alone, a pure cache; + /// `lanes::guard_tests` checks that it stays so, and that no exclusive system is among them. Commands a firing defers, which the drain applies after /// it, are outside that model; /// - the minimap's draw (`minimap::emit_minimap`), which reads `QuestGiver`'s dialog statuses, /// against `ui_panes::feed_character_panes`, which lends the call host, whose quest verbs diff --git a/crates/benilla-app/src/go_templates.rs b/crates/benilla-app/src/go_templates.rs index e8b78e45b..3468f6953 100644 --- a/crates/benilla-app/src/go_templates.rs +++ b/crates/benilla-app/src/go_templates.rs @@ -183,6 +183,15 @@ impl GameObjectTemplates { .send(ClientCommand::GameObjectQuery { entry, guid }); } + /// The template store, the one [`crate::wdb`] saves. + pub(crate) fn template_store(&self) -> &QueryCache { + &self.templates + } + + pub(crate) fn template_store_mut(&mut self) -> &mut QueryCache { + &mut self.templates + } + /// A refused entry (`SMSG_GAMEOBJECT_QUERY_RESPONSE` with the top bit set, `0x5588e0`): no /// template, and the next lookup asks again ([`QueryCache::refuse`]). pub(crate) fn refuse(&mut self, entry: u32) { diff --git a/crates/benilla-app/src/item_names.rs b/crates/benilla-app/src/item_names.rs new file mode 100644 index 000000000..0369b05e3 --- /dev/null +++ b/crates/benilla-app/src/item_names.rs @@ -0,0 +1,73 @@ +//! The item-name store (`0xc0e2dc`), apart from the item templates: `CMSG_ITEM_NAME_QUERY` asks +//! one item's name and `SMSG_ITEM_NAME_QUERY_RESPONSE` answers it (lookup `0x559fe0`, reader +//! `0x7c8dc0`). The reference reads an item set's member names through it (`0x52df5a`), never +//! through the template store, and saves it to `itemnamecache.wdb` ([`crate::wdb`]). + +use benilla_protocol::{SessionEvent, SessionEventKind}; +use bevy::prelude::*; + +use crate::net::{ClientCommand, NetCommands, NetHandlerApp}; +use crate::query_cache::{Ask, QueryCache}; + +/// Item names by entry, asked once while in flight. +#[derive(Resource, Default)] +pub(crate) struct ItemNames { + names: QueryCache, +} + +impl crate::query_cache::AskOnce for ItemNames { + fn clear_pending(&mut self) { + self.names.clear_pending(); + } +} + +impl ItemNames { + /// The name of `entry`, read as `ask` says. The set tooltip's lookup passes a zero owner + /// (`0x52df41`-`0x52df44`), so the query's guid is 0. + pub(crate) fn name(&self, entry: u32, ask: Ask<'_>) -> Option<&str> { + self.names + .read(entry, ask, |commands: &NetCommands| { + debug!("item names: asking item {entry}"); + let _ = commands + .0 + .send(ClientCommand::ItemNameQuery { entry, guid: 0 }); + }) + .map(String::as_str) + } + + /// Files an answer; `None` is the store's refusal (`0x556e67`). + pub(crate) fn file(&mut self, entry: u32, name: Option) { + match name { + Some(name) => self.names.insert(entry, name), + None => { + self.names.refuse(entry); + } + } + } + + /// The name store, the one [`crate::wdb`] saves. + pub(crate) fn store(&self) -> &QueryCache { + &self.names + } + + pub(crate) fn store_mut(&mut self) -> &mut QueryCache { + &mut self.names + } +} + +pub(crate) struct ItemNamesPlugin; + +impl Plugin for ItemNamesPlugin { + fn build(&self, app: &mut App) { + crate::query_cache::register::(app); + app.init_resource::() + .net_handler(SessionEventKind::ItemName, on_item_name); + } +} + +/// `SMSG_ITEM_NAME_QUERY_RESPONSE`: the record lands, or the refusal frees the key. +fn on_item_name(In(ev): In, mut names: ResMut) { + if let SessionEvent::ItemName { entry, name } = ev { + names.file(entry, name); + } +} diff --git a/crates/benilla-app/src/items.rs b/crates/benilla-app/src/items.rs index 06e495106..0bc67ddf5 100644 --- a/crates/benilla-app/src/items.rs +++ b/crates/benilla-app/src/items.rs @@ -665,6 +665,24 @@ impl Items { } } + /// The template store, the one [`crate::wdb`] saves. + pub(crate) fn template_store(&self) -> &QueryCache { + &self.templates + } + + pub(crate) fn template_store_mut(&mut self) -> &mut QueryCache { + &mut self.templates + } + + /// Drops every template, which the interface's copy drops too: another realm's file replaces + /// them. + pub(crate) fn forget_templates(&mut self) { + self.dropped + .extend(self.templates.iter().map(|(&entry, _)| entry)); + self.fresh.clear(); + self.templates.clear(); + } + /// Bumped by every landed answer, for consumers besides the drain; the stand-in for the /// reference's `DBCACHECALLBACK` redisplay (`0x6e29b0`). pub(crate) fn template_epoch(&self) -> u64 { diff --git a/crates/benilla-app/src/lanes/guard_tests.rs b/crates/benilla-app/src/lanes/guard_tests.rs index d5308f204..159b7119b 100644 --- a/crates/benilla-app/src/lanes/guard_tests.rs +++ b/crates/benilla-app/src/lanes/guard_tests.rs @@ -576,8 +576,8 @@ const READS_FRAME_FINAL: &[(&str, &[&str])] = &[ "ui_petition::PetitionRecords"]), ("::ui_items::feed::feed_item_stats", &["items::Items", "net::HomeBind", "net::ObjectStore", "spell::mods::SpellModifiers"]), - ("::ui_items::feed::feed_item_sets", &["items::Items", "net::ObjectStore", - "spell::mods::SpellModifiers"]), + ("::ui_items::feed::feed_item_sets", &["item_names::ItemNames", "items::Items", + "net::ObjectStore", "spell::mods::SpellModifiers"]), ("::ui_items::feed::ask_item_build_lookups", &["items::Countdowns", "names::NameCache", "net::GuidIndex", "net::ObjectStore", "ui_petition::PetitionRecords"]), ("::ui_items::feed::feed_player_req", &["net::ObjectStore", "net::Proficiencies", diff --git a/crates/benilla-app/src/lib.rs b/crates/benilla-app/src/lib.rs index 63351b25d..a2c34c2d0 100644 --- a/crates/benilla-app/src/lib.rs +++ b/crates/benilla-app/src/lib.rs @@ -64,6 +64,7 @@ mod go_templates; #[cfg(feature = "dev")] mod hover_log; mod item_lane; +mod item_names; mod item_watch; mod items; mod lanes; @@ -98,7 +99,6 @@ mod script_calls; mod shaders; mod game_tip; -mod name_persist; mod opaque2d; /// Where "the client is going down" is observed, in `Last`; every system that persists state on the /// way out registers through it. @@ -188,6 +188,7 @@ mod ui_world_map; mod video; mod vm_pass; mod vplates; +mod wdb; mod weapon_trail; mod world_backdrop; mod world_console; diff --git a/crates/benilla-app/src/local_state.rs b/crates/benilla-app/src/local_state.rs index edadc9311..da0f348fa 100644 --- a/crates/benilla-app/src/local_state.rs +++ b/crates/benilla-app/src/local_state.rs @@ -354,12 +354,21 @@ pub(crate) fn move_character_state(realm: &str, old: &str, new: &str) { } } -/// `benilla-config/cache/.tsv`: the player, creature and pet names the server has answered, -/// one file for the reference's `WDB/namecache.wdb`, `creaturecache.wdb` and `petnamecache.wdb`. -/// -/// Realm-scoped, where the reference's is not: guids, creature entries and pet numbers are -/// realm-local, so one shared file would serve a realm another realm's names. -pub(crate) fn name_cache_path(realm: &str) -> Option { +/// `benilla-config/cache//.bin`: one saved template store ([`crate::wdb`]), the +/// reference's `WDB/.wdb`. Realm-scoped, where the reference's is not: a template key is +/// the server's, so another realm may hold another template under it. +pub(crate) fn template_cache_path(realm: &str, store: &str) -> Option { + Some( + home()? + .join("cache") + .join(file_token(realm)) + .join(format!("{store}.bin")), + ) +} + +/// `benilla-config/cache/.tsv`: the creature names an earlier build kept, which the +/// realm's saved stores replace; [`crate::wdb`] removes it. +pub(crate) fn retired_name_cache_path(realm: &str) -> Option { Some( home()? .join("cache") diff --git a/crates/benilla-app/src/name_persist.rs b/crates/benilla-app/src/name_persist.rs deleted file mode 100644 index d200a6c4b..000000000 --- a/crates/benilla-app/src/name_persist.rs +++ /dev/null @@ -1,249 +0,0 @@ -//! The creature-template half of [`crate::names::NameCache`], kept across sessions: benilla's -//! `creaturecache.wdb`. -//! -//! The reference persists only `'WNPC'`; `'WNAM'` and `'WPNM'` (player and pet names) are built -//! with persistence off (`0x554cd0`) and cleared at world-session start -//! ([`NameCache::clear_world_session`]). A template entry keeps its meaning, while a player guid -//! or pet number can come to name another character or spawn. -//! -//! From `DBCache.cpp` (`0x554b00`-`0x5738c0`): the 20-byte header -//! `[FourCC | build 0x16f3 | locale | recordSize | version 1]` is compared by equality, with no -//! checksum or TTL, and a mismatch discards the file ([`NameCache::to_tsv`] writes ours). -//! Eviction is explicit only: a high-bit key in a response, or `SMSG_INVALIDATE_PLAYER` (`0x31C`). -//! -//! Deviation: the file is `benilla-config/cache/.tsv` through [`crate::local_state`], not -//! `WDB/` in the install, because the install is read-only; and it is per realm, because another -//! server may hold a different template under the same entry. - -use std::path::PathBuf; - -use bevy::prelude::*; - -use crate::glue_session::roster::Roster; -use crate::names::NameCache; - -/// Seconds between writes: answers arrive in bursts on zone-in, and a crash costs only re-asking. -const SAVE_DEBOUNCE: f32 = 10.0; - -pub(crate) struct NamePersistPlugin; - -impl Plugin for NamePersistPlugin { - fn build(&self, app: &mut App) { - app.init_resource::() - .add_systems(Update, (load_name_cache, save_name_cache).chain()); - // The exit write catches the last burst, which the debounce would not. - crate::shutdown::on_app_exit(app, save_on_exit.into_configs()); - } -} - -/// Where this realm's cache lives and what we last wrote there. -#[derive(Resource, Default)] -pub(crate) struct NameCacheFile { - /// The realm the loaded file belongs to; a change triggers a load. - realm: Option, - path: Option, - /// [`NameCache::generation`] at the last write: the dirty bit, which ticks on an answer. - saved_generation: u64, - since_save: f32, -} - -/// Loads the realm's cache the first frame its identity is known, and on a realm change. -fn load_name_cache( - roster: Res, - mut file: ResMut, - mut names: ResMut, -) { - let Some((realm, _)) = crate::ui_macro::identity(&roster) else { - return; - }; - if file.realm.as_deref() == Some(realm.as_str()) { - return; - } - let path = crate::local_state::name_cache_path(&realm); - file.realm = Some(realm.clone()); - file.path = path.clone(); - file.saved_generation = names.generation(); - let Some(path) = path else { - return; // a hermetic capture, or no state folder: session-only - }; - let Ok(text) = std::fs::read_to_string(&path) else { - return; // no cache yet - }; - match NameCache::from_tsv(&text, &realm) { - Some(loaded) => { - let n = loaded.len(); - // Install only the file's records: this runs as the pick is in flight, beside the - // login's clear and seed of our own name, and must not replace them. - names.install_persisted(loaded); - file.saved_generation = names.generation(); - debug!( - "names: loaded {n} cached records for {realm} from {}", - path.display() - ); - } - // A header mismatch discards the file, as the reference does; the first save overwrites it. - None => debug!( - "names: discarding {} β€” header is not this build/locale/format", - path.display() - ), - } -} - -/// Writes the cache when answers have landed and the debounce has elapsed. -fn save_name_cache(time: Res