fix: load sprites unconditionally, improve desync debugging tools

Constructor correctness (match original WA behavior):
- Load debris.spr and back.spr unconditionally, not gfx_mode-gated
- Initialize PaletteContext for masks.img (word=1, word=0xFE, Init)
- Document PCLandscape param_5 as game_info+0xDAAC

Debug tooling improvements:
- Hardware watchpoints: EBP-based stack trace on every hit
- Watchpoint base selection: OPENWA_WATCH_WRAPPER, OPENWA_WATCH_DISPLAY
- Display watchpoint arming during constructor for field tracing
- Snapshot: walk parent chain to CTaskTurnGame (true entity root)

Add docs/re-notes/desync-investigation.md — writeup of the longbow
desync investigation methodology and findings.

NOTE: Longbow desync (4 checksum mismatches) is NOT yet resolved.
These changes are correctness fixes and tooling for continued work.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -85,6 +85,8 @@ Key env vars:
 - `OPENWA_BREAK_FRAME=N` — auto-pause at frame N
 - `OPENWA_USE_ORIG_CTOR=1` — use original WA DDGame constructor (for A/B testing)
 - `OPENWA_WATCH_FRAME=N` — arm hardware watchpoint on DDGame at frame N
+- `OPENWA_WATCH_WRAPPER=1` — watchpoint base = DDGameWrapper instead of DDGame
+- `OPENWA_WATCH_DISPLAY=1` — watchpoint base = display object (DDGameWrapper+0x4D0), armed during constructor
 
 ## Crate Architecture
 
@@ -124,6 +126,18 @@ Hooks use the `minhook` crate. Two patterns:
 
 For `__usercall` functions, use a naked trampoline to capture register params before calling the Rust impl.
 
+## Desync Debugging
+
+Replay desyncs (checksum mismatches) can be caused by any code difference — constructor side effects, hooked function behaviour, missing state, wrong calling conventions, etc. Key methodology:
+
+1. **WA uses a single shared RNG** (DDGame+0x45EC, `AdvanceGameRNG` at 0x53F320) for both gameplay AND visual effects. There is no separate "visual RNG." Even purely decorative things like particle sprites affect the game RNG and will cause desyncs in headless mode if handled differently.
+2. **DDGame flat memory matching is NOT sufficient.** Constructors and hooks have side effects on sub-objects (display, GfxHandler, PCLandscape). Compare all objects pointed to by DDGame AND DDGameWrapper.
+3. **Use hardware watchpoints** (`debug_watchpoint.rs`) with stack traces to find what writes a specific field. DR0–DR3 + VEH handler gives "who wrote this byte?" answers without an external debugger.
+4. **Per-frame RNG logging** (DDGame+0x45EC) pinpoints the exact frame where simulation diverges. Binary search on frames, not code.
+5. **Always validate diff methodology** against a known-good frame first. The snapshot system's pointer canonicalization produces false positives.
+
+See `docs/re-notes/desync-investigation.md` for a detailed case study.
+
 ## Hardware Watchpoint Debugger
 
 `crates/openwa-wormkit/src/debug_watchpoint.rs` — self-contained x86 debug register instrumentation. Sets DR0–DR3 write watchpoints on DDGame offsets via an INT3→VEH trick (no external debugger needed). Logs the exact Ghidra VA of every write.

crates/openwa-core/src/engine/ddgame.rs

@@ -559,13 +559,17 @@ unsafe fn wa_load_effect_wavs(wrapper: *mut DDGameWrapper) {
 }
 
 /// PCLandscape__Constructor (0x57ACB0): construct landscape object (0xB44 bytes, 11 params).
+///
+/// param_5 is `game_info + 0xDAAC` (landscape data path region within GameInfo).
+/// The SoundEmitter sub-constructor reads paths, water settings, etc. from this
+/// pointer with negative offsets back into GameInfo.
 #[cfg(target_arch = "x86")]
 unsafe fn wa_pc_landscape_ctor(
     this: *mut u8,
     ddgame: *mut DDGame,
     gfx_resource: *mut u8,
     display: *mut DDDisplay,
-    landscape_path: *const u8,
+    landscape_data: *const u8,
     byte_output: *mut u8,
     gfx_mode: u32,
     temp_buf: *mut u32,
@@ -591,7 +595,7 @@ unsafe fn wa_pc_landscape_ctor(
         ddgame,
         gfx_resource,
         display,
-        landscape_path,
+        landscape_data,
         byte_output,
         gfx_mode,
         temp_buf,
@@ -955,13 +959,31 @@ unsafe fn init_graphics_and_resources(
         }
     }
 
-    // ── GfxResource: thiscall(ECX=gfx_dir) + EAX=name + 1 stack(output), RET 0x4 ──
+    // ── GfxResource for masks.img ──
+    // The original constructor uses a stack-local PaletteContext buffer (ESP+0x1A4)
+    // initialized at the start with (word=1, word=0xFE, PaletteContext__Init).
+    // This same buffer is reused as the output param for GfxResource__Create(masks.img).
+    // We replicate this initialization here. Size 0x900 matches the stack allocation.
     let gfx_resource: *mut u8;
     {
         let gfx_dir = (*wrapper).primary_gfx_dir;
-        let out_buf = wa_malloc_zeroed(0x900);
+        // Create PaletteContext the same way the original DDGame constructor does:
+        // word[0]=1, word[1]=0xFE, then PaletteContext__Init (0x5411A0)
+        let palette_ctx = wa_malloc_zeroed(0x900);
+        *(palette_ctx as *mut u16) = 1;
+        *(palette_ctx.add(2) as *mut u16) = 0xFE;
+        call_usercall_eax(palette_ctx as *mut DDGameWrapper, rb(va::PALETTE_CONTEXT_INIT));
         gfx_resource =
-            gfx_resource_create(gfx_dir, rb(va::STR_MASKS_IMG) as *const c_char, out_buf);
+            gfx_resource_create(gfx_dir, rb(va::STR_MASKS_IMG) as *const c_char, palette_ctx);
+    }
+
+    // ── Dump GfxResource for A/B comparison ──
+    if !gfx_resource.is_null() {
+        let use_orig = std::env::var("OPENWA_USE_ORIG_CTOR").is_ok();
+        let tag = if use_orig { "orig" } else { "rust" };
+        // Dump GfxResource object + first sub-object
+        let gr_data = core::slice::from_raw_parts(gfx_resource, 0x100);
+        let _ = std::fs::write(format!("gfx_resource_{}.bin", tag), gr_data);
     }
 
     // ── PCLandscape (alloc 0xB44, stdcall 11 params) ──
@@ -1244,16 +1266,22 @@ unsafe fn init_graphics_and_resources(
         let disp = (*wrapper).display;
         DDDisplay::set_active_layer(disp, 3);
 
-        if (*wrapper).gfx_mode != 0 {
-            DDDisplay::load_sprite_by_layer(
-                disp,
-                3,
-                0x26D,
-                land_layer,
-                c"back.spr".as_ptr().cast(),
-            );
-            DDDisplay::load_sprite(disp, 3, 0x26E, 0, land_layer, c"debris.spr".as_ptr());
-        }
+        // back.spr and debris.spr must be loaded unconditionally — they're used by
+        // GenerateDebrisParticles (0x546F70) for particle effects, which affects
+        // the game RNG (DDGame+0x45EC). The original constructor loads them even
+        // in headless mode. Skipping them causes replay desync.
+        DDDisplay::load_sprite_by_layer(
+            disp,
+            3,
+            0x26D,
+            land_layer,
+            c"back.spr".as_ptr().cast(),
+        );
+        // debris.spr must be loaded unconditionally — it's used by
+        // GenerateDebrisParticles (0x546F70) for particle effects, which
+        // affects the game RNG (DDGame+0x45EC). Skipping it in headless
+        // mode causes desync (longbow replay checksum mismatch at frame 1350).
+        DDDisplay::load_sprite(disp, 3, 0x26E, 0, land_layer, c"debris.spr".as_ptr());
 
         DDDisplay::load_sprite_by_layer(
             disp,

crates/openwa-wormkit/src/debug_watchpoint.rs

@@ -30,10 +30,12 @@ use windows_sys::Win32::System::Diagnostics::Debug::{
     AddVectoredExceptionHandler, RemoveVectoredExceptionHandler, EXCEPTION_POINTERS,
 };
 
-/// DDGame offsets to watch. Hardware limit: 4 watchpoints (DR0–DR3).
+/// Offsets to watch. Hardware limit: 4 watchpoints (DR0–DR3).
 /// Change these to investigate different fields.
-const WATCH_OFFSETS: [(u32, &str); 1] = [
-    (0x0050, "ddgame+0x50"),
+/// NOTE: The base pointer is set by `on_ddgame_alloc()` — can be DDGame or DDGameWrapper.
+const WATCH_OFFSETS: [(u32, &str); 2] = [
+    (0x09C0, "display+0x09C0"),
+    (0x353C, "display+0x353C"),
 ];
 
 /// DDGame base address (set when allocation is reported).
@@ -115,28 +117,58 @@ unsafe extern "system" fn veh_handler(info: *mut EXCEPTION_POINTERS) -> i32 {
         (STATUS_SINGLE_STEP, Phase::Active) => {
             let dr6 = ctx.Dr6;
             let eip = ctx.Eip;
-            // Compute Ghidra VA (only meaningful if EIP is inside WA.exe)
             let delta = rb(va::IMAGE_BASE).wrapping_sub(va::IMAGE_BASE);
             let wa_base = rb(va::IMAGE_BASE);
-            let ghidra_eip = eip.wrapping_sub(delta);
-            // WA.exe is ~2MB; check if EIP is plausibly inside it
-            let in_wa = eip >= wa_base && eip < wa_base + 0x300000;
 
             let base = DDGAME_BASE.load(Ordering::Relaxed);
             for (i, &(offset, name)) in WATCH_OFFSETS.iter().enumerate() {
                 if dr6 & (1 << i) != 0 {
                     let val = *((base + offset) as *const u32);
-                    if in_wa {
-                        let _ = log_line(&format!(
-                            "[Watchpoint] {} (+0x{:04X}) = 0x{:08X}  writer before 0x{:08X} (WA.exe)",
-                            name, offset, val, ghidra_eip,
-                        ));
-                    } else {
-                        let _ = log_line(&format!(
-                            "[Watchpoint] {} (+0x{:04X}) = 0x{:08X}  writer before 0x{:08X} (runtime, outside WA.exe)",
-                            name, offset, val, eip,
-                        ));
+                    let ghidra_eip = eip.wrapping_sub(delta);
+
+                    // Walk EBP chain for stack trace
+                    let mut trace = heapless::String::<512>::new();
+                    let mut ebp = ctx.Ebp;
+                    let esp = ctx.Esp;
+                    for depth in 0..12 {
+                        // Validate EBP: must be in plausible stack range, aligned,
+                        // and above ESP (stack grows down)
+                        if ebp < 0x10000 || ebp > 0x7FFE0000 || (ebp & 3) != 0 {
+                            break;
+                        }
+                        // Safety: check both [ebp] and [ebp+4] are readable
+                        if !openwa_core::mem::can_read(ebp, 8) {
+                            break;
+                        }
+                        let ret_addr = *((ebp + 4) as *const u32);
+                        let next_ebp = *(ebp as *const u32);
+                        let ghidra_ret = ret_addr.wrapping_sub(delta);
+                        let in_wa = ret_addr >= wa_base && ret_addr < wa_base + 0x300000;
+                        if depth > 0 {
+                            let _ = core::fmt::Write::write_str(&mut trace, "<-");
+                        }
+                        if in_wa {
+                            let _ = core::fmt::Write::write_fmt(
+                                &mut trace,
+                                format_args!("{:08X}", ghidra_ret),
+                            );
+                        } else {
+                            let _ = core::fmt::Write::write_fmt(
+                                &mut trace,
+                                format_args!("r:{:08X}", ret_addr),
+                            );
+                        }
+                        // EBP must increase (frames go up the stack)
+                        if next_ebp <= ebp {
+                            break;
+                        }
+                        ebp = next_ebp;
                     }
+
+                    let _ = log_line(&format!(
+                        "[Watchpoint] {} = 0x{:08X}  eip=0x{:08X} stack=[{}]",
+                        name, val, ghidra_eip, trace,
+                    ));
                 }
             }
 

crates/openwa-wormkit/src/replacements/game_session.rs

@@ -102,6 +102,12 @@ pub(crate) unsafe fn construct_ddgame_wrapper(
         display as u32, net_game as u32, timer_obj as u32, game_info as u32,
     ));
 
+    // Arm display watchpoint during construction if requested
+    if std::env::var("OPENWA_WATCH_DISPLAY").is_ok() {
+        crate::debug_watchpoint::prepare();
+        crate::debug_watchpoint::on_ddgame_alloc(display as *mut u8);
+    }
+
     // Use env var to switch between original and Rust constructor
     let use_original = std::env::var("OPENWA_USE_ORIG_CTOR").is_ok();
     if use_original {
@@ -125,6 +131,11 @@ pub(crate) unsafe fn construct_ddgame_wrapper(
 
     }
 
+    // Disarm display watchpoint
+    if std::env::var("OPENWA_WATCH_DISPLAY").is_ok() {
+        crate::debug_watchpoint::teardown();
+    }
+
     // Initialize DDGame's game-state fields.
     let init_state: unsafe extern "stdcall" fn(*mut DDGameWrapper) =
         core::mem::transmute(rb(va::DDGAME_INIT_GAME_STATE) as usize);

crates/openwa-wormkit/src/replacements/input.rs

@@ -195,7 +195,18 @@ unsafe extern "stdcall" fn hook_turn_manager(turngame: u32) {
                 if game_frame >= target {
                     WATCH_ARMED.store(true, Ordering::Relaxed);
                     crate::debug_watchpoint::prepare();
-                    crate::debug_watchpoint::on_ddgame_alloc(ddgame as *mut u8);
+                    // Select watchpoint base: DDGame, DDGameWrapper, or Display
+                    let watch_base = if std::env::var("OPENWA_WATCH_DISPLAY").is_ok() {
+                        let session = *(rb(va::G_GAME_SESSION) as *const u32);
+                        let wrapper = *((session + 0xA0) as *const *const u8);
+                        *(wrapper.add(0x4D0) as *const *mut u8)
+                    } else if std::env::var("OPENWA_WATCH_WRAPPER").is_ok() {
+                        let session = *(rb(va::G_GAME_SESSION) as *const u32);
+                        *((session + 0xA0) as *const *mut u8)
+                    } else {
+                        ddgame as *mut u8
+                    };
+                    crate::debug_watchpoint::on_ddgame_alloc(watch_base);
                 }
             }
         }

crates/openwa-wormkit/src/snapshot.rs

@@ -72,6 +72,9 @@ pub unsafe fn capture() -> String {
     let _ = writeln!(out);
 
     // ── Entity tree ──
+    // CTaskTurnGame is the root of the entity tree. Find it by checking
+    // CTaskLand's parent chain or the shared data table.
+    // CTaskTurnGame vtable = 0x669F70.
     let task_land = (*ddgame).task_land;
     if task_land.is_null() {
         let _ = writeln!(out, "[Entities] task_land=null");
@@ -79,7 +82,20 @@ pub unsafe fn capture() -> String {
     }
 
     let delta = rb(va::IMAGE_BASE).wrapping_sub(va::IMAGE_BASE);
-    let root = task_land as *const CTask;
+
+    // Walk parent chain from CTaskLand to find CTaskTurnGame (root of entity tree).
+    // Safety limit to prevent infinite loops on corrupt parent chains.
+    let mut root = task_land as *const CTask;
+    for _ in 0..10 {
+        let parent = (*root).parent as *const CTask;
+        if parent.is_null() || parent == root {
+            break;
+        }
+        root = parent;
+    }
+    let _ = writeln!(out, "[Entities] root vt=0x{:08X}",
+        (*(root as *const u32)).wrapping_sub(delta));
+
     let iter = CTaskBfsIter::new(root);
 
     // Census + detailed dump

docs/re-notes/desync-investigation.md

@@ -0,0 +1,114 @@
+# The debris.spr Desync: Debugging a Replay Mismatch in a Reimplemented Game Constructor
+
+## Summary
+
+During the incremental Rust reimplementation of Worms Armageddon's DDGame constructor, a deterministic replay of a longbow match produced "Checksum Mismatch" errors starting at frame 1350. Other replays (bots 3v3, shotgun) passed. This documents the investigation that ultimately traced the root cause to a single missing sprite load (`debris.spr`) in headless mode, and the debugging methodology used to find it.
+
+## Background
+
+OpenWA replaces WA functions with Rust reimplementations via DLL injection. The DDGame constructor (~900 lines of Rust replacing a ~19KB x86 function) initialises the entire game engine: display layers, terrain, sprites, sound, HUD, and entity systems. An A/B toggle (`OPENWA_USE_ORIG_CTOR=1`) switches between the Rust and original constructors for comparison.
+
+Replay testing works by running WA.exe with a recorded `.WAgame` file in headless mode (no graphics window), capturing the game log, and comparing against a known-good baseline. WA's built-in checksum system sends periodic state checksums during gameplay; mismatches indicate simulation divergence.
+
+## The Symptom
+
+- Rust constructor: **4 checksum mismatches** at frames 1350, 2186, 2249, 2775
+- Original constructor: all checksums pass
+- DDGame flat memory (39KB): **byte-for-byte identical** between both constructors
+- Terrain collision bitmaps: identical
+- Entity tree: same 68 entities in same BFS order
+
+The game outcome was the same (same winner, same damage), but the checksums diverged.
+
+## Dead Ends
+
+Several hypotheses were investigated and ruled out:
+
+1. **Landscape bitmap differences** — dumped 1.3MB terrain collision bitmaps from both runs: byte-identical at construction AND at the divergence frame.
+
+2. **Entity tree ordering** — full entity snapshot comparison showed ~490 diff lines. Seemed like proof of different entity ordering. But the same comparison at a *known-good* frame also showed ~490 diffs, and the bots replay (which passes) showed ~480 diffs. The snapshot tool's pointer canonicalization heuristic (`is_likely_pointer` using `can_read()`) was producing false positives. **Lesson: always validate your diff tool against a known baseline.**
+
+3. **PaletteContext buffer** — the original constructor creates a PaletteContext on the stack and reuses it; our code creates a fresh one. Tried matching the initialization: no effect. The cached GfxDir path was taken, bypassing the PaletteContext entirely.
+
+4. **PCLandscape constructor parameters** — verified via x86 disassembly that `param_5 = game_info + 0xDAAC` (not raw game_info). Our code was already correct.
+
+## The Breakthrough: Sub-Object Diffing
+
+The key insight: DDGame's flat memory matching doesn't mean *everything* matches. The constructor calls WA functions that modify objects *outside* DDGame — particularly the **display object** (DDGameWrapper+0x4D0).
+
+Dumping the display object (16KB) before and after construction revealed:
+
+| Offset | Before | After (orig) | After (rust) |
+|--------|--------|-------------|-------------|
+| +0x09C0 | 0 | **3** | 0 |
+| +0x353C | 0 | **1** | 0 |
+
+The display started identical and diverged *during* the constructor.
+
+## Hardware Watchpoints With Stack Traces
+
+To find what wrote these display fields, we used x86 debug registers (DR0–DR3) via a Vectored Exception Handler:
+
+1. Register VEH before the constructor
+2. Set DR0/DR1 to watch `display + 0x09C0` and `display + 0x353C`
+3. On `STATUS_SINGLE_STEP` (write trap), log the value, EIP, and walk the EBP chain for a stack trace
+
+The watchpoint reported:
+```
+display+0x353C = 0x00000001  eip=0x005234C0  stack=[...]
+display+0x09C0 = 0x00000003  eip=0x005234B8  stack=[...]
+```
+
+Both writes came from `LoadSprite` (0x523400) — a display vtable method (slot 31) that loads a sprite into the display's layer cache. The sprite being loaded was **index 0x26E** into **layer 3**.
+
+## The Root Cause
+
+Tracing back to our Rust constructor:
+
+```rust
+if (*wrapper).gfx_mode != 0 {
+    DDDisplay::load_sprite_by_layer(disp, 3, 0x26D, land_layer, "back.spr");
+    DDDisplay::load_sprite(disp, 3, 0x26E, 0, land_layer, "debris.spr");
+}
+```
+
+In headless mode (`gfx_mode = 0`), both sprites were skipped. But the original WA constructor loads them unconditionally — even without a graphics window. Sprite 0x26E is `debris.spr`, used by `GenerateDebrisParticles` (0x546F70) for particle effects.
+
+`GenerateDebrisParticles` reads terrain pixels and, when a hit is detected, updates the **game RNG** (DDGame+0x45EC) and creates particle entities. Without `debris.spr` loaded in the display, the sprite lookup returns different data, causing different RNG update patterns:
+
+- Original: 15,470 RNG writes (from frame 808 onward)
+- Rust (broken): 17,106 RNG writes
+- Delta: 1,636 extra RNG ticks → cascading simulation divergence
+
+## The Partial Fix (and a Lesson in Verifying Results)
+
+```rust
+// Load unconditionally — debris.spr affects game RNG via GenerateDebrisParticles
+DDDisplay::load_sprite(disp, 3, 0x26E, 0, land_layer, c"debris.spr".as_ptr());
+```
+
+This change is correct — the original constructor loads `debris.spr` unconditionally, and our code should match. However, it did **not** resolve the desync. An initial test appeared to show 3 of 4 mismatches fixed, but this was a `tail -5` truncation error — only the last mismatch was visible, creating a false impression. All 4 mismatches persist.
+
+The display state differences (sprite layer counters) we found were real and worth fixing for correctness, but they turned out not to be the root cause of the checksum mismatch. The investigation continues.
+
+## Debugging Tools Built
+
+The investigation produced several reusable tools:
+
+- **Hardware watchpoint system** with EBP-based stack trace walking (VEH + DR0–DR3)
+- **Per-frame game state hashing** via forced `SerializeGameState` calls
+- **Binary sub-object dumping** for display, GfxHandler, PCLandscape comparison
+- **`OPENWA_WATCH_DISPLAY=1`** env var to arm watchpoints on the display object during construction
+- Terrain collision bitmap dumping at arbitrary frames
+
+## Key Lessons
+
+1. **Identical struct memory ≠ identical behaviour.** The constructor's side effects on *other* objects matter as much as the struct it fills. Compare sub-objects systematically.
+
+2. **Validate your diff tools.** Our snapshot comparison showed ~490 "differences" at known-good frames — pure noise from pointer canonicalization heuristics. Always baseline.
+
+3. **There is no "visual-only" code in a deterministic game engine.** `debris.spr` seems purely decorative — it controls what debris particles look like when terrain is destroyed. But Worms uses a **single shared RNG** for everything: gameplay physics, AI decisions, particle effects, sound variation. There is no separate "visual RNG." Every RNG consumer must execute identically, or the streams diverge and every subsequent random outcome differs. Skipping a single sprite load changed how `GenerateDebrisParticles` consumed RNG ticks, shifting the entire RNG sequence for all downstream gameplay.
+
+4. **Hardware watchpoints are underrated.** x86 DR0–DR3 with a VEH handler gives "what wrote this byte?" answers in seconds, without an external debugger. Adding stack traces made them even more powerful.
+
+5. **Binary search on frames, not code.** Per-frame RNG logging narrowed 542 candidate frames to the exact frame (818) where divergence began, before any code analysis.