From c04d74f47c6f44b00a77213eef310e9f800ccc12 Mon Sep 17 00:00:00 2001
From: Sam Sung <51686767+samwhosung@users.noreply.github.com>
Date: Fri, 25 Sep 2026 16:06:53 +0700
Subject: [PATCH] Comments in benilla-assets and benilla-ui: three reference
 facts corrected, one deviation labelled (#290)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Comment corrections in crates whose comment pass has already landed. Comment text only: every file strips to identical code.

- Fixes #61. The `<Script file=>` note in `benilla-ui`'s loader now names the install directory as the reference's scan root (`0x646ea0`, from Storm's base path `0xc52418`), not the process's working directory. The deviation it records is unchanged.
- Fixes #96. `liquid.wgsl` no longer labels the ADT water alpha a deviation. The swatch's own alpha is what the reference uses: the `0xc7fbc0` table's texture binds only behind `[0xc800ec]`, which never holds one.
- Fixes #117. `wmo.rs` now gives prop creation as the streaming-window commit (`0x698720` → `0x695aa0`, once per group) and per-frame visibility as the portal walk's admission (`0x685d70` → `0x6838f0`).
- `model.rs`: the billboard-card normal flip carries the Deviation label, with the reason `benilla-formats` already gives where the test lives: the reference shades such a card inverted and camera-dependent.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 crates/benilla-assets/src/model.rs            |  6 +++---
 crates/benilla-assets/src/shaders/liquid.wgsl |  4 ++--
 crates/benilla-assets/src/wmo.rs              | 11 ++++++-----
 crates/benilla-ui/src/loader/mod.rs           |  6 +++---
 4 files changed, 14 insertions(+), 13 deletions(-)

diff --git a/crates/benilla-assets/src/model.rs b/crates/benilla-assets/src/model.rs
index 02dd5130..6424cd28 100644
--- a/crates/benilla-assets/src/model.rs
+++ b/crates/benilla-assets/src/model.rs
@@ -114,9 +114,9 @@ fn build_submesh_mesh(sub: &RenderSubmesh, usages: RenderAssetUsages) -> Mesh {
         mesh.insert_attribute(Mesh::ATTRIBUTE_COLOR, sub.vertex_colors.clone());
     }
     if sub.normals.len() == sub.positions.len() {
-        // A card authored facing away from the viewer is lit on the face it presents, so flip its
-        // normals, never its winding: the reference culls the single-sided ones from every angle,
-        // and re-winding would show them.
+        // Deviation: a card authored facing away from the viewer is lit on the face it presents,
+        // because the reference shades it inverted and camera-dependent. Flip its normals, never
+        // its winding, which would show the single-sided ones the reference culls at every angle.
         let flip = sub.billboard_card_faces_away();
         let normals: Vec<[f32; 3]> = sub
             .normals
diff --git a/crates/benilla-assets/src/shaders/liquid.wgsl b/crates/benilla-assets/src/shaders/liquid.wgsl
index bb7e5fcb..e06c1932 100644
--- a/crates/benilla-assets/src/shaders/liquid.wgsl
+++ b/crates/benilla-assets/src/shaders/liquid.wgsl
@@ -13,8 +13,8 @@
 // `ocean_h` frame, near-black RGB and the ripple in alpha, which its authored mips fade with
 // distance, so the sampler's mips and anisotropy matter; primary is the lit default white vertex
 // (`glColorMaterial`); secondary is the sun sheen.
-// Deviation: the reference's ADT water alpha is the `0xc7fbc0` LUT curve `1.6·(i/63)^8`; this keeps
-// the linear swatch alpha, because switching changes the look of every ADT water surface.
+// The ADT water alpha is the swatch's own: the `0xc7fbc0` LUT texture binds only behind
+// `[0xc800ec]` (`0x685244`-`0x685257`), which never holds one (its one store, `0x68c7f8`, is 0).
 // Deviation: this is the `specular`/`pixelShaders` = 1 leg the reference install runs; both CVars
 // (`0x6886a0`/`0x688712`) default to 0, where water has no program, no specular, a plain ADD
 // combine and no blend. An active ARB program bypasses the texture environment.
diff --git a/crates/benilla-assets/src/wmo.rs b/crates/benilla-assets/src/wmo.rs
index 31b11fc5..cc7ba08b 100644
--- a/crates/benilla-assets/src/wmo.rs
+++ b/crates/benilla-assets/src/wmo.rs
@@ -88,8 +88,8 @@ pub struct WmoModel {
     /// Per-MODD first referencing group, whose MOLR set the interior lane folds; the
     /// interior/exterior class reads [`Self::doodad_groups`].
     pub doodad_owner: Vec<Option<u16>>,
-    /// Per-MODD every group whose MODR names it: the portal-cull key, as the reference draws
-    /// doodads per visible group (`0x695aa0`, MODR at `+0xe8`, count `+0x144`, walk `0x698720`).
+    /// Per-MODD every group whose MODR names it: the portal-cull key, as the reference admits a
+    /// group's props each frame its portal walk visits it (`0x685d70` → `0x6838f0`).
     pub doodad_groups: Vec<Arc<[u16]>>,
     /// Per-group footprint faces (render faces, MOCV, MOPY flags); `None` for exterior groups and
     /// groups without MOCV. A GameObject M2 down-rays them for its MOCV lighting (`0x69e4c0`).
@@ -276,7 +276,8 @@ pub fn floor168(c: [u8; 3]) -> [f32; 3] {
 }
 
 /// MODD index to its first referencing group, whose MOLR set the interior lane uses. The reference
-/// creates a doodad on the first visible-group walk that names it, and never one no group names.
+/// creates a group's props once, when the group enters the streaming window (`0x698720` →
+/// `0x695aa0`, MODR at `+0xe8`, count `+0x144`), and never one no group names.
 fn modr_owners(doodad_count: usize, group_doodad_refs: &[Vec<u16>]) -> Vec<Option<u16>> {
     let mut owner: Vec<Option<u16>> = vec![None; doodad_count];
     for (gi, refs) in group_doodad_refs.iter().enumerate() {
@@ -289,8 +290,8 @@ fn modr_owners(doodad_count: usize, group_doodad_refs: &[Vec<u16>]) -> Vec<Optio
     owner
 }
 
-/// MODD index to every group whose MODR names it: the reference draws per visible group
-/// (`0x695aa0` from the walk at `0x698720`), so a prop shows while any of them is visible.
+/// MODD index to every group whose MODR names it: the reference admits a group's props in each
+/// frame its portal walk visits it (`0x685d70` → `0x6838f0`), so a prop shows while any is visible.
 fn modr_refs(doodad_count: usize, group_doodad_refs: &[Vec<u16>]) -> Vec<Arc<[u16]>> {
     let mut refs: Vec<Vec<u16>> = vec![Vec::new(); doodad_count];
     for (gi, group) in group_doodad_refs.iter().enumerate() {
diff --git a/crates/benilla-ui/src/loader/mod.rs b/crates/benilla-ui/src/loader/mod.rs
index 435bbff9..890e68e2 100644
--- a/crates/benilla-ui/src/loader/mod.rs
+++ b/crates/benilla-ui/src/loader/mod.rs
@@ -316,9 +316,9 @@ impl Loader<'_> {
                 TopLevel::Include(path) => self.do_include(path),
                 // Deviation: a `<Script file=>` value with a separator joins the including
                 // document's directory, like a bare name. The reference uses it verbatim
-                // (`0x6ee070`-`0x6ee079`) against the process CWD (`0x647e60`, `0x646ebc`; the
-                // basename retry at `0x647ed3` is off), where it never opens, so joining breaks
-                // nothing that loads on 1.12.
+                // (`0x6ee070`-`0x6ee079`) against the install directory, the root `0x646ea0`
+                // scans from Storm's base path `0xc52418` (the basename retry at `0x647ed3` is
+                // off), where a stock install has no such file, so joining breaks nothing.
                 TopLevel::Script(ScriptRef::File(path)) => {
                     let joined = join_ref(self.base(), path);
                     match (self.files)(&joined) {