docs: remove outdated plans, add re-notes disclaimer

docs/plans/2026-03-05-offline-harness-design.md

@@ -1,101 +0,0 @@
-# Offline Test Harness Design
-
-**Goal:** Load WA.exe into a 32-bit test process via `cargo test`, enabling offline validation of addresses, vtable contents, and eventually calling WA.exe functions — without running the game.
-
-**Architecture:** A new `openwa-harness` crate that uses `LoadLibraryExA` with `DONT_RESOLVE_DLL_REFERENCES` to map WA.exe into process memory. This gives us a relocated PE image with readable `.text`, `.rdata`, and `.data` sections. Tests run via `cargo test --target i686-pc-windows-msvc -p openwa-harness`.
-
-## How PE Loading Works
-
-```
-LoadLibraryExA("WA.exe", NULL, DONT_RESOLVE_DLL_REFERENCES)
-  → Windows maps PE sections into memory
-  → Applies base relocations (WA.exe has .reloc section)
-  → Does NOT resolve imports (IAT entries are unpatched)
-  → Does NOT call entry point
-  → Returns HMODULE = base address of mapped image
-```
-
-Delta computation: `loaded_base - IMAGE_BASE (0x400000)`.
-Any Ghidra address `addr` maps to `loaded_base + (addr - 0x400000)`.
-
-If `LoadLibraryEx` refuses to load an EXE, fallback: manual PE loader (read file, parse headers, VirtualAlloc, copy sections, apply relocations).
-
-## Test Layers
-
-### Layer 1: Read-only validation (initial scope)
-
-Load WA.exe, read memory at known offsets:
-- Vtable entries in `.rdata` match our address constants
-- Function prologues at known `.text` offsets match expected bytes
-- String data at known locations matches expected values
-- Cross-reference consistency (vtable method pointers land in `.text`)
-
-This replaces/supplements the runtime validator's static checks but runs via `cargo test` with no game needed.
-
-### Layer 2: Function calls (stretch goal)
-
-Call simple WA.exe functions from the test process:
-- Requires resolving at minimum CRT imports (malloc, free, memset, memcpy)
-- IAT patching: find import entries, overwrite with pointers to our own implementations
-- Start with `WA_MallocMemset` (0x53E910) — uses EDI register for size, calls malloc+memset
-- Validate return values and memory contents
-
-### Layer 3: Complex function execution (future)
-
-- Broader IAT patching for Windows API stubs
-- Mock subsystems (DirectDraw, DirectSound) to prevent crashes
-- Test constructors, initialization sequences
-
-## Crate Structure
-
-```
-crates/openwa-harness/
-  Cargo.toml          # 32-bit test crate, depends on openwa-types, windows-sys
-  src/
-    lib.rs            # WaImage loader struct, rebase helpers
-    tests/            # (or use #[cfg(test)] modules)
-      pe_loading.rs   # Layer 1: read-only checks
-```
-
-## Key Type: WaImage
-
-```rust
-pub struct WaImage {
-    base: *const u8,     // HMODULE from LoadLibraryEx
-    delta: i32,          // base - 0x400000
-}
-
-impl WaImage {
-    /// Load WA.exe from given path
-    pub fn load(exe_path: &str) -> Result<Self, ...>;
-
-    /// Convert Ghidra address to pointer in loaded image
-    pub fn ptr(&self, ghidra_addr: u32) -> *const u8;
-
-    /// Read u32 at a Ghidra address
-    pub fn read_u32(&self, ghidra_addr: u32) -> u32;
-}
-
-impl Drop for WaImage {
-    fn drop(&mut self) { FreeLibrary(self.base); }
-}
-```
-
-## WA.exe Path
-
-The harness needs to find WA.exe. Options in priority order:
-1. `WAEXE_PATH` environment variable
-2. Known Steam path: `I:\games\SteamLibrary\steamapps\common\Worms Armageddon\WA.exe`
-3. Skip tests with clear message if not found
-
-## Dependencies
-
-- `windows-sys` crate for `LoadLibraryExA`, `FreeLibrary` (links to kernel32)
-- `openwa-types` for address constants and struct definitions
-- No other external dependencies needed for Layer 1
-
-## Risks
-
-- `LoadLibraryEx` might refuse to load an EXE (unlikely but possible) → fallback to manual PE mapping
-- WA.exe might not have a `.reloc` section → would need to load at exact base address 0x400000 (but we confirmed it has one: 188KB .reloc section)
-- Function calls (Layer 2+) may crash if they touch unresolved imports → start read-only, add IAT patching incrementally

docs/plans/2026-03-05-openwa-foundation-design.md

@@ -1,37 +0,0 @@
-# OpenWA Foundation Design
-
-## Goal
-
-Build the type foundation for an incremental Rust reimplementation of Worms Armageddon 3.8.1 (Steam). Start with Ghidra-assisted reverse engineering and Rust type definitions, later expand to a WormKit module that replaces subsystems.
-
-## Strategy: Hybrid Bootstrap
-
-- **Constants/enums**: Translate immediately from wkJellyWorm's well-documented Constants.h (weapons, messages, sprites, sounds, class types)
-- **Struct layouts**: Explore in Ghidra first, write Rust types only for verified fields, pad unknowns
-
-## Architecture
-
-```
-OpenWA/                     (Cargo workspace)
-  crates/
-    openwa-types/           (no_std-compatible type definitions)
-      - Enums: ClassType, TaskMessage, Weapon, SoundId, SpriteId
-      - Structs: CTask, CGameTask (partial, Ghidra-verified)
-      - Primitives: FixedPoint (16.16 fixed-point math)
-      - Addresses: Known function/global addresses
-    openwa-dll/          (future: WormKit DLL module)
-    openwa-render/           (future: modern rendering backend)
-```
-
-## Key Decisions
-
-- `#[repr(C)]` and `#[repr(u32)]` for FFI compatibility from day one
-- Unknown struct fields as `_unknown_XX: [u8; N]` padding — honest about what we don't know
-- Fixed-point newtype rather than raw i32 — prevents unit confusion
-- No external dependencies in openwa-types (pure Rust, no_std compatible)
-
-## Sources
-
-- wkJellyWorm: Task hierarchy, enums, vtable layouts, offset documentation
-- WormKit: Game state pointers, network protocol, fixed-point conventions
-- Ghidra: WA.exe analysis (6,859 functions, image base 0x400000)

docs/plans/2026-03-05-runtime-validator-design.md

@@ -1,98 +0,0 @@
-# Runtime Validator DLL Design
-
-## Goal
-
-Validate that our reverse-engineered struct layouts, field offsets, and address
-constants in `openwa-types` are correct by checking them against the live
-Worms Armageddon 3.8.1 process at runtime.
-
-## Architecture
-
-A 32-bit Rust cdylib (`wkOpenWAValidator.dll`) loaded by WormKit's HookLib into
-the WA.exe process. On load it:
-
-1. Validates address constants (vtables contain plausible function pointers,
-   function addresses start with valid x86 prologues)
-2. Hooks key constructors to capture object pointers
-3. When constructors fire, validates struct field offsets against live memory
-4. Writes results to `OpenWA_validation.log`
-
-## Crate structure
-
-```
-crates/openwa-validator/
-├── Cargo.toml      # cdylib, i686-pc-windows-msvc
-└── src/
-    └── lib.rs      # DLL entry, hooks, validation
-```
-
-## Dependencies
-
-- `retour` (with `static-detour` feature) — inline function hooking
-- `openwa-types` (path dependency) — the types being validated
-- `windows` or raw FFI — for DllMain, file I/O
-
-## Build
-
-```sh
-cargo build --target i686-pc-windows-msvc -p openwa-validator --release
-```
-
-Output: `target/i686-pc-windows-msvc/release/openwa_validator.dll`
-Copy to game dir as `wkOpenWAValidator.dll`.
-
-## Validation checks
-
-### Address validation (immediate, on DLL load)
-
-For each vtable address in `va::*_VTABLE`:
-- Read the first entry (should be a function pointer in .text range)
-- PASS if value is in 0x401000..0x619FFF
-
-For each function address in `va::*`:
-- Read first 1-3 bytes at that address
-- PASS if starts with common x86 prologue (55 8B EC = push ebp; mov ebp, esp)
-  or other valid patterns (83 EC, 56, 53, etc.)
-
-### Struct validation (on constructor hook)
-
-**CTask constructor (0x5625A0):**
-- After constructor returns, read object
-- Check vtable == 0x669F8C
-- Check _unknown_08 == 0x10 (set by constructor)
-
-**CGameTask constructor (0x4FED50):**
-- Check vtable2 at offset 0xE8 == 0x669CF8
-- Check total struct offsets are consistent
-
-**DDGameWrapper constructor (0x56DEF0):**
-- Check vtable at +0x00 == 0x66A30C
-- Check ddgame pointer at +0x488 is non-null (after init)
-
-**DDGame constructor (0x56E220):**
-- Check landscape at +0x20 matches wrapper's landscape at +0x4CC
-- Check known init values (field_7EFC == 1, etc.)
-
-## Output format
-
-```
-=== OpenWA Validator ===
-[PASS] va::CTASK_VTABLE (0x669F8C) -> first entry 0x562710 (in .text)
-[PASS] va::CONSTRUCT_DD_GAME (0x56E220) -> prologue 55 8B EC
-[FAIL] DDGame+0x020 (landscape): expected non-null, got 0x00000000
-[INFO] 45/47 checks passed, 2 failed
-```
-
-## Deployment
-
-1. Build the DLL
-2. Copy to WA game directory as `wkOpenWAValidator.dll`
-3. Launch WA via WormKit (or directly — HookLib loads wk*.dll)
-4. Play through to trigger constructors (start a game)
-5. Check `OpenWA_validation.log` in game directory
-
-## Non-goals
-
-- No signature scanning (hardcoded addresses for 3.8.1 only)
-- No game modification (read-only checks)
-- No complex hook chains

docs/plans/2026-03-05-runtime-validator-plan.md

@@ -1,675 +0,0 @@
-# Runtime Validator DLL Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Build a 32-bit Rust WormKit DLL that validates our `openwa-types` struct layouts and address constants against live WA.exe 3.8.1 memory.
-
-**Architecture:** A `cdylib` crate (`openwa-validator`) compiled for `i686-pc-windows-msvc`. Loaded by WormKit's HookLib as `wkOpenWAValidator.dll`. On attach: validates addresses immediately, hooks constructors with `retour`, logs PASS/FAIL to a file.
-
-**Tech Stack:** Rust (stable), `retour` (inline hooking), `openwa-types` (path dep), raw Win32 FFI for DllMain.
-
----
-
-### Task 1: Install the i686 target
-
-**Step 1: Add the Rust target**
-
-Run: `rustup target add i686-pc-windows-msvc`
-Expected: "installed" or "already installed"
-
----
-
-### Task 2: Create the openwa-validator crate
-
-**Files:**
-- Create: `crates/openwa-validator/Cargo.toml`
-- Create: `crates/openwa-validator/src/lib.rs`
-
-**Step 1: Create Cargo.toml**
-
-```toml
-[package]
-name = "openwa-validator"
-version = "0.1.0"
-edition = "2021"
-description = "WormKit DLL that validates openwa-types against live WA.exe memory"
-
-[lib]
-crate-type = ["cdylib"]
-
-[dependencies]
-openwa-types = { path = "../openwa-types" }
-retour = { version = "0.4", features = ["static-detour", "thiscall-abi"] }
-```
-
-**Step 2: Create minimal lib.rs with DllMain**
-
-This is the DLL entry point. On `DLL_PROCESS_ATTACH`, it spawns a thread
-(to avoid loader lock) that runs all validation.
-
-```rust
-#![allow(non_snake_case)]
-
-use std::ffi::c_void;
-
-const DLL_PROCESS_ATTACH: u32 = 1;
-
-#[no_mangle]
-unsafe extern "system" fn DllMain(
-    _module: *mut c_void,
-    reason: u32,
-    _reserved: *mut c_void,
-) -> i32 {
-    if reason == DLL_PROCESS_ATTACH {
-        std::thread::spawn(|| {
-            if let Err(e) = run_validation() {
-                let _ = log_line(&format!("[FATAL] Validation failed to run: {}", e));
-            }
-        });
-    }
-    1 // TRUE
-}
-
-fn run_validation() -> Result<(), Box<dyn std::error::Error>> {
-    let _ = log_line("=== OpenWA Validator ===");
-    let _ = log_line("DLL loaded successfully. Validation will follow.");
-    Ok(())
-}
-
-fn log_line(msg: &str) -> std::io::Result<()> {
-    use std::io::Write;
-    let mut f = std::fs::OpenOptions::new()
-        .create(true)
-        .append(true)
-        .open("OpenWA_validation.log")?;
-    writeln!(f, "{}", msg)?;
-    Ok(())
-}
-```
-
-**Step 3: Verify it compiles**
-
-Run: `cargo build --target i686-pc-windows-msvc -p openwa-validator`
-Expected: Compiles successfully, produces `target/i686-pc-windows-msvc/debug/openwa_validator.dll`
-
-**Step 4: Commit**
-
-```
-feat: scaffold openwa-validator WormKit DLL crate
-```
-
----
-
-### Task 3: Add address validation
-
-**Files:**
-- Modify: `crates/openwa-validator/src/lib.rs`
-
-This runs immediately on DLL load — no hooks needed. It reads memory at our
-known addresses and checks plausibility.
-
-**Step 1: Add address validation module**
-
-Add a `validate_addresses` function that checks:
-- Vtable addresses: read first DWORD, verify it's in .text range (0x401000..0x61A000)
-- Function addresses: read first bytes, verify common x86 prologue patterns
-- Global variable addresses: verify they're in .data range (0x694000..0x8C4158)
-
-```rust
-use openwa_types::address::va;
-
-struct ValidationResult {
-    pass: u32,
-    fail: u32,
-}
-
-impl ValidationResult {
-    fn new() -> Self {
-        Self { pass: 0, fail: 0 }
-    }
-
-    fn check(&mut self, name: &str, passed: bool, detail: &str) {
-        if passed {
-            self.pass += 1;
-            let _ = log_line(&format!("[PASS] {}: {}", name, detail));
-        } else {
-            self.fail += 1;
-            let _ = log_line(&format!("[FAIL] {}: {}", name, detail));
-        }
-    }
-
-    fn summary(&self) {
-        let total = self.pass + self.fail;
-        let _ = log_line(&format!(
-            "[INFO] {}/{} checks passed, {} failed",
-            self.pass, total, self.fail
-        ));
-    }
-}
-
-unsafe fn read_u32(addr: u32) -> u32 {
-    *(addr as *const u32)
-}
-
-unsafe fn read_u8(addr: u32) -> u8 {
-    *(addr as *const u8)
-}
-
-fn is_in_text(addr: u32) -> bool {
-    addr >= va::TEXT_START && addr <= va::TEXT_END
-}
-
-fn is_in_rdata(addr: u32) -> bool {
-    addr >= va::RDATA_START && addr < va::DATA_START
-}
-
-fn validate_addresses(result: &mut ValidationResult) {
-    unsafe {
-        // --- Vtable checks: first entry should be a function pointer in .text ---
-        let vtables: &[(&str, u32)] = &[
-            ("CTASK_VTABLE", va::CTASK_VTABLE),
-            ("CGAMETASK_VTABLE", va::CGAMETASK_VTABLE),
-            ("CGAMETASK_VTABLE2", va::CGAMETASK_VTABLE2),
-            ("DDGAME_WRAPPER_VTABLE", va::DDGAME_WRAPPER_VTABLE),
-            ("GFX_HANDLER_VTABLE", va::GFX_HANDLER_VTABLE),
-            ("DISPLAY_GFX_VTABLE", va::DISPLAY_GFX_VTABLE),
-            ("PC_LANDSCAPE_VTABLE", va::PC_LANDSCAPE_VTABLE),
-            ("LANDSCAPE_SHADER_VTABLE", va::LANDSCAPE_SHADER_VTABLE),
-            ("DS_SOUND_VTABLE", va::DS_SOUND_VTABLE),
-            ("TASK_STATE_MACHINE_VTABLE", va::TASK_STATE_MACHINE_VTABLE),
-            ("OPENGL_CPU_VTABLE", va::OPENGL_CPU_VTABLE),
-            ("WATER_EFFECT_VTABLE", va::WATER_EFFECT_VTABLE),
-        ];
-
-        for (name, addr) in vtables {
-            // Vtable itself should be in .rdata
-            let in_rdata = is_in_rdata(*addr);
-            result.check(
-                &format!("{} location", name),
-                in_rdata,
-                &format!("0x{:08X} in .rdata: {}", addr, in_rdata),
-            );
-
-            // First entry should point to .text
-            let first_entry = read_u32(*addr);
-            let valid = is_in_text(first_entry);
-            result.check(
-                &format!("{} first entry", name),
-                valid,
-                &format!("0x{:08X} -> 0x{:08X} (in .text: {})", addr, first_entry, valid),
-            );
-        }
-
-        // --- CTask vtable content: verify known method pointers ---
-        let ctask_vt_checks: &[(&str, u32, u32)] = &[
-            ("CTask vt[0] init", va::CTASK_VTABLE, va::CTASK_VT0_INIT),
-            ("CTask vt[1] free", va::CTASK_VTABLE + 4, va::CTASK_VT1_FREE),
-            ("CTask vt[2] handleMsg", va::CTASK_VTABLE + 8, va::CTASK_VT2_HANDLE_MESSAGE),
-            ("CTask vt[7] processFrame", va::CTASK_VTABLE + 0x1C, va::CTASK_VT7_PROCESS_FRAME),
-        ];
-
-        for (name, vt_addr, expected_fn) in ctask_vt_checks {
-            let actual = read_u32(*vt_addr);
-            result.check(
-                name,
-                actual == *expected_fn,
-                &format!("at 0x{:08X}: expected 0x{:08X}, got 0x{:08X}", vt_addr, expected_fn, actual),
-            );
-        }
-
-        // --- Function prologue checks ---
-        let functions: &[(&str, u32)] = &[
-            ("CTASK_CONSTRUCTOR", va::CTASK_CONSTRUCTOR),
-            ("CGAMETASK_CONSTRUCTOR", va::CGAMETASK_CONSTRUCTOR),
-            ("CONSTRUCT_DD_GAME", va::CONSTRUCT_DD_GAME),
-            ("CONSTRUCT_DD_GAME_WRAPPER", va::CONSTRUCT_DD_GAME_WRAPPER),
-            ("CONSTRUCT_PC_LANDSCAPE", va::CONSTRUCT_PC_LANDSCAPE),
-            ("CONSTRUCT_DS_SOUND", va::CONSTRUCT_DS_SOUND),
-            ("CREATE_EXPLOSION", va::CREATE_EXPLOSION),
-            ("FRONTEND_CHANGE_SCREEN", va::FRONTEND_CHANGE_SCREEN),
-        ];
-
-        // Common x86 prologues: 55 (push ebp), 53 (push ebx), 56 (push esi),
-        // 83 EC (sub esp), 8B (mov), 6A (push imm8), 81 (sub esp imm32)
-        let valid_first_bytes: &[u8] = &[0x55, 0x53, 0x56, 0x57, 0x83, 0x8B, 0x6A, 0x81, 0xB8, 0x51, 0x52];
-
-        for (name, addr) in functions {
-            let first_byte = read_u8(*addr);
-            let valid = valid_first_bytes.contains(&first_byte);
-            result.check(
-                name,
-                valid,
-                &format!("0x{:08X} starts with 0x{:02X} (valid prologue: {})", addr, first_byte, valid),
-            );
-        }
-    }
-}
-```
-
-**Step 2: Wire into run_validation**
-
-```rust
-fn run_validation() -> Result<(), Box<dyn std::error::Error>> {
-    // Clear log file
-    let _ = std::fs::write("OpenWA_validation.log", "");
-
-    let _ = log_line("=== OpenWA Validator ===");
-    let mut result = ValidationResult::new();
-
-    validate_addresses(&mut result);
-
-    result.summary();
-    Ok(())
-}
-```
-
-**Step 3: Verify it compiles**
-
-Run: `cargo build --target i686-pc-windows-msvc -p openwa-validator`
-Expected: Compiles
-
-**Step 4: Commit**
-
-```
-feat(validator): add address and vtable content validation
-```
-
----
-
-### Task 4: Add constructor hooks for struct validation
-
-**Files:**
-- Modify: `crates/openwa-validator/src/lib.rs`
-
-Hook CTask and DDGameWrapper constructors to validate struct field offsets
-when objects are actually constructed in the live game.
-
-**Step 1: Define static detours and hook functions**
-
-WA.exe constructors use `__thiscall` (ECX = this, args on stack).
-`retour`'s `extern "thiscall"` maps the first parameter to ECX.
-
-Note: DDGame constructor has many params. For validation we only need `this`
-(ECX) and the DDGameWrapper pointer. We capture what we can.
-
-```rust
-use retour::static_detour;
-use std::sync::atomic::{AtomicBool, Ordering};
-
-// Track whether we've validated each struct (only do it once)
-static CTASK_VALIDATED: AtomicBool = AtomicBool::new(false);
-static DDGAME_WRAPPER_VALIDATED: AtomicBool = AtomicBool::new(false);
-
-// CTask constructor: __thiscall with (this, parent_ptr, class_type)
-// At 0x5625A0
-type CTaskCtorFn = unsafe extern "thiscall" fn(this: u32, parent: u32, class_type: u32) -> u32;
-
-static_detour! {
-    static CTaskCtorHook: unsafe extern "thiscall" fn(u32, u32, u32) -> u32;
-}
-
-fn on_ctask_constructed(this: u32, parent: u32, class_type: u32) -> u32 {
-    let ret = unsafe { CTaskCtorHook.call(this, parent, class_type) };
-
-    if !CTASK_VALIDATED.swap(true, Ordering::Relaxed) {
-        validate_ctask(this);
-    }
-
-    ret
-}
-
-fn validate_ctask(this: u32) {
-    let mut result = ValidationResult::new();
-    unsafe {
-        // CTask.vtable at offset 0x00 should be CTASK_VTABLE
-        // Note: subclasses override this, so we check it's a valid .text-pointing vtable
-        let vtable = read_u32(this);
-        let first_method = read_u32(vtable);
-        result.check(
-            "CTask+0x00 (vtable)",
-            is_in_rdata(vtable),
-            &format!("vtable ptr 0x{:08X} (in .rdata: {})", vtable, is_in_rdata(vtable)),
-        );
-        result.check(
-            "CTask vtable[0] -> .text",
-            is_in_text(first_method),
-            &format!("first method 0x{:08X} (in .text: {})", first_method, is_in_text(first_method)),
-        );
-
-        // CTask._unknown_08 at offset 0x08 should be 0x10
-        let field_08 = read_u32(this + 0x08);
-        result.check(
-            "CTask+0x08 (init value)",
-            field_08 == 0x10,
-            &format!("expected 0x10, got 0x{:X}", field_08),
-        );
-
-        // CTask.class_type at offset 0x20 should be a valid ClassType
-        let class_type_val = read_u32(this + 0x20);
-        result.check(
-            "CTask+0x20 (class_type)",
-            class_type_val < 200, // reasonable range for enum
-            &format!("value {} (reasonable range: {})", class_type_val, class_type_val < 200),
-        );
-    }
-
-    let _ = log_line("--- CTask struct validation ---");
-    result.summary();
-}
-
-// DDGameWrapper constructor: __thiscall with (this) — simple
-// At 0x56DEF0
-type DDGameWrapperCtorFn = unsafe extern "thiscall" fn(this: u32) -> u32;
-
-static_detour! {
-    static DDGameWrapperCtorHook: unsafe extern "thiscall" fn(u32) -> u32;
-}
-
-fn on_ddgame_wrapper_constructed(this: u32) -> u32 {
-    let ret = unsafe { DDGameWrapperCtorHook.call(this) };
-
-    if !DDGAME_WRAPPER_VALIDATED.swap(true, Ordering::Relaxed) {
-        // Delay validation slightly — the constructor sets fields but
-        // DDGame is allocated later. We validate what we can now.
-        validate_ddgame_wrapper_immediate(this);
-
-        // Spawn a thread that waits briefly then checks DDGame pointer
-        let wrapper_addr = this;
-        std::thread::spawn(move || {
-            std::thread::sleep(std::time::Duration::from_secs(5));
-            validate_ddgame_wrapper_deferred(wrapper_addr);
-        });
-    }
-
-    ret
-}
-
-fn validate_ddgame_wrapper_immediate(this: u32) {
-    let mut result = ValidationResult::new();
-    unsafe {
-        // DDGameWrapper.vtable at +0x00
-        let vtable = read_u32(this);
-        result.check(
-            "DDGameWrapper+0x00 (vtable)",
-            vtable == va::DDGAME_WRAPPER_VTABLE,
-            &format!("expected 0x{:08X}, got 0x{:08X}", va::DDGAME_WRAPPER_VTABLE, vtable),
-        );
-
-        // DDGameWrapper._field_4e0 at +0x4E0 should be -100 (0xFFFFFF9C)
-        let field_4e0 = read_u32(this + 0x4E0);
-        result.check(
-            "DDGameWrapper+0x4E0 (init -100)",
-            field_4e0 == 0xFFFFFF9C,
-            &format!("expected 0xFFFFFF9C, got 0x{:08X}", field_4e0),
-        );
-    }
-
-    let _ = log_line("--- DDGameWrapper struct validation (immediate) ---");
-    result.summary();
-}
-
-fn validate_ddgame_wrapper_deferred(this: u32) {
-    let mut result = ValidationResult::new();
-    unsafe {
-        // DDGameWrapper.ddgame at +0x488
-        let ddgame_ptr = read_u32(this + 0x488);
-        result.check(
-            "DDGameWrapper+0x488 (ddgame ptr)",
-            ddgame_ptr != 0,
-            &format!("0x{:08X} (non-null: {})", ddgame_ptr, ddgame_ptr != 0),
-        );
-
-        if ddgame_ptr != 0 {
-            // DDGame.landscape at +0x20 should match wrapper.landscape at +0x4CC
-            let ddgame_landscape = read_u32(ddgame_ptr + 0x20);
-            let wrapper_landscape = read_u32(this + 0x4CC);
-            result.check(
-                "DDGame+0x20 == DDGameWrapper+0x4CC (landscape)",
-                ddgame_landscape == wrapper_landscape,
-                &format!(
-                    "DDGame: 0x{:08X}, Wrapper: 0x{:08X}",
-                    ddgame_landscape, wrapper_landscape
-                ),
-            );
-
-            // DDGame+0x7EFC should be 1 (init value)
-            let field_7efc = read_u32(ddgame_ptr + 0x7EFC);
-            result.check(
-                "DDGame+0x7EFC (init 1)",
-                field_7efc == 1,
-                &format!("expected 1, got {}", field_7efc),
-            );
-
-            // DDGame.display_gfx at +0x138 — if set, vtable should be DISPLAY_GFX_VTABLE
-            let display_gfx = read_u32(ddgame_ptr + 0x138);
-            if display_gfx != 0 {
-                let dgfx_vt = read_u32(display_gfx);
-                result.check(
-                    "DDGame+0x138 display_gfx vtable",
-                    dgfx_vt == va::DISPLAY_GFX_VTABLE,
-                    &format!("expected 0x{:08X}, got 0x{:08X}", va::DISPLAY_GFX_VTABLE, dgfx_vt),
-                );
-            }
-
-            // DDGame.task_state_machine at +0x380 — if set, vtable should be TASK_STATE_MACHINE_VTABLE
-            let tsm = read_u32(ddgame_ptr + 0x380);
-            if tsm != 0 {
-                let tsm_vt = read_u32(tsm);
-                result.check(
-                    "DDGame+0x380 task_state_machine vtable",
-                    tsm_vt == va::TASK_STATE_MACHINE_VTABLE,
-                    &format!("expected 0x{:08X}, got 0x{:08X}", va::TASK_STATE_MACHINE_VTABLE, tsm_vt),
-                );
-            }
-        }
-
-        // DDGameWrapper.gfx_handler_0 at +0x4C0 — vtable should be GFX_HANDLER_VTABLE
-        let gfx0 = read_u32(this + 0x4C0);
-        if gfx0 != 0 {
-            let gfx0_vt = read_u32(gfx0);
-            result.check(
-                "DDGameWrapper+0x4C0 gfx_handler_0 vtable",
-                gfx0_vt == va::GFX_HANDLER_VTABLE,
-                &format!("expected 0x{:08X}, got 0x{:08X}", va::GFX_HANDLER_VTABLE, gfx0_vt),
-            );
-        }
-
-        // DDGameWrapper.landscape at +0x4CC — vtable should be PC_LANDSCAPE_VTABLE
-        let landscape = read_u32(this + 0x4CC);
-        if landscape != 0 {
-            let land_vt = read_u32(landscape);
-            result.check(
-                "DDGameWrapper+0x4CC landscape vtable",
-                land_vt == va::PC_LANDSCAPE_VTABLE,
-                &format!("expected 0x{:08X}, got 0x{:08X}", va::PC_LANDSCAPE_VTABLE, land_vt),
-            );
-        }
-    }
-
-    let _ = log_line("--- DDGameWrapper/DDGame struct validation (deferred) ---");
-    result.summary();
-}
-```
-
-**Step 2: Install hooks in run_validation**
-
-```rust
-fn run_validation() -> Result<(), Box<dyn std::error::Error>> {
-    let _ = std::fs::write("OpenWA_validation.log", "");
-    let _ = log_line("=== OpenWA Validator ===");
-
-    let mut result = ValidationResult::new();
-    validate_addresses(&mut result);
-    result.summary();
-
-    // Install constructor hooks
-    let _ = log_line("\nInstalling constructor hooks...");
-
-    unsafe {
-        let ctask_ctor: CTaskCtorFn = std::mem::transmute(va::CTASK_CONSTRUCTOR as usize);
-        CTaskCtorHook
-            .initialize(ctask_ctor, |this, parent, class_type| {
-                on_ctask_constructed(this, parent, class_type)
-            })?
-            .enable()?;
-        let _ = log_line("[HOOK] CTask constructor hooked at 0x5625A0");
-
-        let wrapper_ctor: DDGameWrapperCtorFn =
-            std::mem::transmute(va::CONSTRUCT_DD_GAME_WRAPPER as usize);
-        DDGameWrapperCtorHook
-            .initialize(wrapper_ctor, |this| {
-                on_ddgame_wrapper_constructed(this)
-            })?
-            .enable()?;
-        let _ = log_line("[HOOK] DDGameWrapper constructor hooked at 0x56DEF0");
-    }
-
-    let _ = log_line("Hooks installed. Start a game to trigger struct validation.\n");
-    Ok(())
-}
-```
-
-**Step 3: Verify it compiles**
-
-Run: `cargo build --target i686-pc-windows-msvc -p openwa-validator`
-Expected: Compiles
-
-**Step 4: Commit**
-
-```
-feat(validator): add constructor hooks for CTask and DDGameWrapper validation
-```
-
----
-
-### Task 5: Manual testing with WA.exe
-
-**Step 1: Build release**
-
-Run: `cargo build --target i686-pc-windows-msvc -p openwa-validator --release`
-
-**Step 2: Deploy to game directory**
-
-Copy `target/i686-pc-windows-msvc/release/openwa_validator.dll` to
-`I:\games\SteamLibrary\steamapps\common\Worms Armageddon\wkOpenWAValidator.dll`
-
-Note: WormKit's HookLib auto-loads any `wk*.dll` in the game directory.
-If HookLib isn't present, the DLL won't load. In that case, we can use
-a simple injector or rename to test with manual LoadLibrary.
-
-**Step 3: Launch the game and start a match**
-
-1. Launch WA.exe (via Steam or directly)
-2. Start a single-player deathmatch (to trigger DDGame/CTask constructors)
-3. Exit the game
-
-**Step 4: Check the log**
-
-Read `I:\games\SteamLibrary\steamapps\common\Worms Armageddon\OpenWA_validation.log`
-
-Expected: A mix of PASS/FAIL lines showing which addresses and struct offsets
-are correct. Any FAILs indicate bugs in our `openwa-types` definitions.
-
-**Step 5: Fix any failures**
-
-If struct offsets are wrong, update `openwa-types` accordingly and re-run.
-This is the core value of the validator — it tells us exactly which
-fields are at wrong offsets.
-
-**Step 6: Commit any fixes**
-
-```
-fix(types): correct struct offsets based on runtime validation
-```
-
----
-
-### Task 6: Add offset_of validation for Rust struct layouts
-
-**Files:**
-- Modify: `crates/openwa-validator/src/lib.rs`
-
-Use `core::mem::offset_of!` (stable since Rust 1.77) to verify our `#[repr(C)]`
-struct field offsets match the documented byte offsets. This catches mistakes
-where padding or field ordering is wrong, without needing live game memory.
-
-**Step 1: Add compile-time / load-time offset checks**
-
-```rust
-use openwa_types::task::{CTask, CGameTask};
-use openwa_types::ddgame::DDGame;
-use openwa_types::ddgame_wrapper::DDGameWrapper;
-
-fn validate_struct_offsets(result: &mut ValidationResult) {
-    // CTask offsets
-    let checks: &[(&str, usize, usize)] = &[
-        ("CTask::vtable", core::mem::offset_of!(CTask, vtable), 0x00),
-        ("CTask::parent", core::mem::offset_of!(CTask, parent), 0x04),
-        ("CTask::_unknown_08", core::mem::offset_of!(CTask, _unknown_08), 0x08),
-        ("CTask::class_type", core::mem::offset_of!(CTask, class_type), 0x20),
-
-        // CGameTask offsets
-        ("CGameTask::base", core::mem::offset_of!(CGameTask, base), 0x00),
-        ("CGameTask::pos_x", core::mem::offset_of!(CGameTask, pos_x), 0x84),
-        ("CGameTask::pos_y", core::mem::offset_of!(CGameTask, pos_y), 0x88),
-        ("CGameTask::speed_x", core::mem::offset_of!(CGameTask, speed_x), 0x90),
-        ("CGameTask::speed_y", core::mem::offset_of!(CGameTask, speed_y), 0x94),
-        ("CGameTask::vtable2", core::mem::offset_of!(CGameTask, vtable2), 0xE8),
-
-        // DDGame offsets
-        ("DDGame::landscape", core::mem::offset_of!(DDGame, landscape), 0x20),
-        ("DDGame::game_state", core::mem::offset_of!(DDGame, game_state), 0x24),
-        ("DDGame::arrow_sprites", core::mem::offset_of!(DDGame, arrow_sprites), 0x38),
-        ("DDGame::arrow_gfxdirs", core::mem::offset_of!(DDGame, arrow_gfxdirs), 0xB8),
-        ("DDGame::display_gfx", core::mem::offset_of!(DDGame, display_gfx), 0x138),
-        ("DDGame::task_state_machine", core::mem::offset_of!(DDGame, task_state_machine), 0x380),
-        ("DDGame::sprite_regions", core::mem::offset_of!(DDGame, sprite_regions), 0x46C),
-        ("DDGame::coord_list", core::mem::offset_of!(DDGame, coord_list), 0x50C),
-
-        // DDGameWrapper offsets
-        ("DDGameWrapper::vtable", core::mem::offset_of!(DDGameWrapper, vtable), 0x00),
-        ("DDGameWrapper::ddgame", core::mem::offset_of!(DDGameWrapper, ddgame), 0x488),
-        ("DDGameWrapper::gfx_handler_0", core::mem::offset_of!(DDGameWrapper, gfx_handler_0), 0x4C0),
-        ("DDGameWrapper::landscape", core::mem::offset_of!(DDGameWrapper, landscape), 0x4CC),
-        ("DDGameWrapper::display", core::mem::offset_of!(DDGameWrapper, display), 0x4D0),
-    ];
-
-    for (name, actual, expected) in checks {
-        result.check(
-            &format!("offset_of {}", name),
-            *actual == *expected,
-            &format!("expected 0x{:X}, got 0x{:X}", expected, actual),
-        );
-    }
-}
-```
-
-**Step 2: Call from run_validation, before the hook installation**
-
-Add after `validate_addresses`:
-
-```rust
-let _ = log_line("\n--- Struct offset validation (compile-time layout) ---");
-validate_struct_offsets(&mut result);
-```
-
-**Step 3: Verify it compiles**
-
-Run: `cargo build --target i686-pc-windows-msvc -p openwa-validator`
-
-**Step 4: Commit**
-
-```
-feat(validator): add offset_of! checks for Rust struct layouts
-```
-
----
-
-## Deployment Checklist
-
-1. `rustup target add i686-pc-windows-msvc`
-2. `cargo build --target i686-pc-windows-msvc -p openwa-validator --release`
-3. Copy DLL to game dir as `wkOpenWAValidator.dll`
-4. Ensure WormKit HookLib is in game dir (or use alternative injection)
-5. Launch game, start a match, exit
-6. Read `OpenWA_validation.log`

docs/plans/2026-03-06-configuration-system-design.md

@@ -1,110 +0,0 @@
-# Port Configuration System to Rust
-
-## Context
-
-The WA configuration system has three subsystems: theme file I/O, Windows Registry management, and game options loading. All are self-contained leaf functions with no graphics or game state dependencies beyond simple struct field writes.
-
-## Scope — 7 Functions
-
-### Theme File I/O (3 functions)
-
-| Function | Address | Convention | Params | What it does |
-|----------|---------|------------|--------|-------------|
-| `Theme__GetFileSize` | 0x44BA80 | cdecl | 0 | Opens `data\current.thm`, returns file length (0 if missing) |
-| `Theme__Load` | 0x44BB20 | stdcall | 1 (dest buffer) | Reads entire theme file into buffer; MessageBox on failure |
-| `Theme__Save` | 0x44BBC0 | stdcall | 2 (buffer, size) | Writes buffer to theme file; MessageBox on create failure |
-
-Replace MFC CFile with `std::fs`. Replace `AfxMessageBox` with `MessageBoxA` from the `windows` crate.
-
-### Registry Management (2 functions)
-
-| Function | Address | Convention | Params | What it does |
-|----------|---------|------------|--------|-------------|
-| `Registry__DeleteKeyRecursive` | 0x4E4D10 | stdcall | 2 (hkey, subkey) | Recursively enumerates and deletes registry subkeys |
-| `Registry__CleanAll` | 0x4C90D0 | stdcall | 1 (struct ptr) | Deletes Data/Options/ExportVideo/VSyncAssist subsections + clears INI |
-
-Pure Win32 registry API. Original uses malloc/realloc for key name buffer — Rust `Vec<u8>` replaces this.
-
-### Game Options (2 functions)
-
-| Function | Address | Convention | Params | What it does |
-|----------|---------|------------|--------|-------------|
-| `GameInfo__LoadOptions` | 0x460AC0 | stdcall | 1 (GameInfo ptr) | Reads ~12 registry values into GameInfo struct fields |
-| `Options__GetCrashReportURL` | 0x5A63F0 | cdecl | 0 | Reads CrashReportURL from Options registry key |
-
-LoadOptions reads from `HKCU\Software\Team17SoftwareLTD\WormsArmageddon\Options` via MFC `GetProfileIntW`. We replace with direct `RegOpenKeyExA` + `RegQueryValueExA`.
-
-Key value transformations in LoadOptions:
-- `BackgroundDebrisParallax`: clamp to i16 range, then `<< 16` (fixed-point 16.16)
-- `CameraUnlockMouseSpeed`: clamp to max 0xB504, then square
-- `InfoSpy`: stored as `!= 0` (bool)
-- All others: simple cast to byte or store as u32
-
-LoadOptions also copies various globals into the GameInfo struct and formats the speech path via sprintf.
-
-## Dependencies
-
-### `windows` crate
-
-Add to `openwa-lib` with features:
-- `Win32_System_Registry` — RegOpenKeyExA, RegQueryValueExA, RegEnumKeyExA, RegDeleteKeyA, RegCloseKey
-- `Win32_UI_WindowsAndMessaging` — MessageBoxA, WriteProfileSectionA
-
-Existing raw FFI in `resource.rs` and `rebase.rs` stays as-is for now — migration to `windows` crate is a separate future task.
-
-### Registry helper in openwa-lib
-
-`read_profile_int(section: &str, key: &str, default: u32) -> u32`
-
-Opens `HKCU\Software\Team17SoftwareLTD\WormsArmageddon\{section}`, reads a DWORD via `RegQueryValueExA`, returns default on any failure. Matches MFC `GetProfileIntW` behavior for the registry-mode path.
-
-## Hook Strategy
-
-All 7 functions are full Rust replacements — no trampolines needed. All conventions are plain cdecl or stdcall (confirmed via RET instruction analysis).
-
-## File Layout
-
-| File | Change |
-|------|--------|
-| `crates/openwa-types/src/address.rs` | Add 7 address constants |
-| `crates/openwa-lib/Cargo.toml` | Add `windows` crate dependency |
-| `crates/openwa-lib/src/wa/registry.rs` (new) | `read_profile_int`, `delete_key_recursive` |
-| `crates/openwa-lib/src/wa/mod.rs` | Add `pub mod registry;` |
-| `crates/openwa-dll/src/replacements/config.rs` (new) | 7 hook functions + `install()` |
-| `crates/openwa-dll/src/replacements/mod.rs` | Add `pub mod config;` |
-
-## Global Data References in LoadOptions
-
-| Global Address | Description | GameInfo Offset |
-|---------------|-------------|-----------------|
-| 0x0088E282 | Base directory string | +0xF404 (speech path) |
-| 0x0088DFF3 | 64 bytes copied verbatim | +0xF485 |
-| 0x0064DA58 | `"data\land.dat"` string (14 bytes) | +0xDAEC |
-| 0x007C0D38 | Unknown byte | +0xF3A0 |
-| 0x0088E39C..0x0088E3AC | 5 DWORDs | +0xF3B4..+0xF3D0 |
-| 0x0088C374 | Guard flag for conditional copies | — |
-| 0x0088E3B8..0x0088E3C4 | 4 DWORDs (conditional) | +0xF3F4..+0xF400 |
-| 0x0088E390 | DWORD | +0xDAE8 |
-| 0x0088E3B0..0x0088E3B4 | 2 DWORDs | +0xF3D4..+0xF3D8 |
-| 0x0088E400..0x0088E408 | 3 DWORDs | +0xF3C4..+0xF3CC |
-| 0x0088E44C | DWORD | +0xF3E4 |
-
-These are read via rebased pointers (`rb(addr)`) and written to the GameInfo struct at the given offsets.
-
-## Verification
-
-1. Build: `cargo build --release -p openwa-dll` — clean
-2. Deploy wkOpenWA.dll to game directory
-3. Launch game, check OpenWA.log for config hook messages
-4. Verify game options persist (change Detail Level, restart, confirm it's saved)
-5. Verify theme loads correctly (visual appearance unchanged)
-6. Test Registry__CleanAll if reachable (it's called from a "reset all settings" path)
-7. Check CrashReportURL is read correctly (visible in crash dialog if triggered)
-
-## Decisions
-
-- **`windows` crate**: Add now, migrate existing FFI later
-- **Theme error messages**: Use `MessageBoxA` from `windows` crate (replaces AfxMessageBox)
-- **Registry reads**: Direct Win32 API, not MFC GetProfileIntW (Steam always uses registry mode)
-- **GameInfo struct**: Write to raw pointer at known offsets (don't type the full 0xF500-byte struct)
-- **std::fs over CFile**: For theme I/O

docs/plans/2026-03-06-configuration-system-plan.md

@@ -1,877 +0,0 @@
-# Configuration System Port — Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Port 7 WA.exe configuration functions (theme I/O, registry management, game options loading) to Rust.
-
-**Architecture:** New `config.rs` replacement module in openwa-dll hooks 7 functions. Registry helpers live in openwa-lib for reuse. Uses `windows` crate for Win32 registry/MessageBox APIs, `std::fs` for theme file I/O.
-
-**Tech Stack:** Rust, `windows` crate (Win32 registry + UI), MinHook inline hooks, `std::fs`
-
----
-
-### Task 1: Add `windows` crate dependency to openwa-lib
-
-**Files:**
-- Modify: `crates/openwa-lib/Cargo.toml`
-
-**Step 1: Add the dependency**
-
-```toml
-[dependencies]
-openwa-types = { path = "../openwa-types" }
-
-[target.'cfg(target_os = "windows")'.dependencies]
-windows-sys = { version = "0.59", features = [
-    "Win32_System_Registry",
-    "Win32_UI_WindowsAndMessaging",
-] }
-```
-
-Note: Use `windows-sys` (not `windows`) — it's the raw FFI bindings crate, already used by openwa-dll. Lower overhead, no COM wrappers.
-
-**Step 2: Build to verify**
-
-Run: `cargo build --release -p openwa-lib`
-Expected: clean build
-
-**Step 3: Commit**
-
-```
-feat: add windows-sys registry + UI features to openwa-lib
-```
-
----
-
-### Task 2: Add address constants
-
-**Files:**
-- Modify: `crates/openwa-types/src/address.rs`
-
-**Step 1: Add constants**
-
-Add to the `va` module, in a new `// === Configuration / registry ===` section after the scheme section:
-
-```rust
-// === Configuration / registry ===
-
-/// Theme file size check: cdecl() -> u32 (file length or 0)
-pub const THEME_GET_FILE_SIZE: u32 = 0x0044_BA80;
-/// Theme file load: stdcall(dest_buffer)
-pub const THEME_LOAD: u32 = 0x0044_BB20;
-/// Theme file save: stdcall(buffer, size)
-pub const THEME_SAVE: u32 = 0x0044_BBC0;
-/// Recursive registry key deletion: stdcall(hkey, subkey) -> i32
-pub const REGISTRY_DELETE_KEY_RECURSIVE: u32 = 0x004E_4D10;
-/// Registry cleanup — deletes all 4 subsections + clears INI: stdcall(struct_ptr)
-pub const REGISTRY_CLEAN_ALL: u32 = 0x004C_90D0;
-/// Loads game options from registry into GameInfo struct: stdcall(game_info_ptr)
-pub const GAMEINFO_LOAD_OPTIONS: u32 = 0x0046_0AC0;
-/// Reads CrashReportURL from Options registry key: cdecl() -> *const u8
-pub const OPTIONS_GET_CRASH_REPORT_URL: u32 = 0x005A_63F0;
-```
-
-**Step 2: Build to verify**
-
-Run: `cargo build --release -p openwa-types`
-Expected: clean build
-
-**Step 3: Commit**
-
-```
-feat: add configuration system address constants
-```
-
----
-
-### Task 3: Add registry helpers to openwa-lib
-
-**Files:**
-- Create: `crates/openwa-lib/src/wa/registry.rs`
-- Modify: `crates/openwa-lib/src/wa/mod.rs`
-
-**Step 1: Add `pub mod registry;` to mod.rs**
-
-After the existing `pub mod resource;` line:
-
-```rust
-pub mod registry;
-```
-
-**Step 2: Create registry.rs**
-
-```rust
-//! Win32 registry helpers for WA configuration.
-
-use windows_sys::Win32::System::Registry::*;
-
-const WA_REGISTRY_PATH: &str = "Software\\Team17SoftwareLTD\\WormsArmageddon\\";
-
-/// Read an integer value from the WA registry.
-///
-/// Opens `HKCU\Software\Team17SoftwareLTD\WormsArmageddon\{section}\{key}`
-/// and reads it as a DWORD. Returns `default` on any failure.
-///
-/// This replaces MFC's `CWinApp::GetProfileIntW` for the registry-mode path.
-pub fn read_profile_int(section: &str, key: &str, default: u32) -> u32 {
-    let mut full_path = String::with_capacity(WA_REGISTRY_PATH.len() + section.len() + 1);
-    full_path.push_str(WA_REGISTRY_PATH);
-    full_path.push_str(section);
-    full_path.push('\0');
-
-    let mut key_buf = String::with_capacity(key.len() + 1);
-    key_buf.push_str(key);
-    key_buf.push('\0');
-
-    unsafe {
-        let mut hkey: HKEY = 0;
-        let status = RegOpenKeyExA(
-            HKEY_CURRENT_USER,
-            full_path.as_ptr(),
-            0,
-            KEY_READ,
-            &mut hkey,
-        );
-        if status != 0 {
-            return default;
-        }
-
-        let mut value: u32 = 0;
-        let mut value_size: u32 = 4;
-        let mut value_type: u32 = 0;
-        let status = RegQueryValueExA(
-            hkey,
-            key_buf.as_ptr(),
-            core::ptr::null_mut(),
-            &mut value_type,
-            &mut value as *mut u32 as *mut u8,
-            &mut value_size,
-        );
-        RegCloseKey(hkey);
-
-        if status == 0 && value_type == REG_DWORD {
-            value
-        } else {
-            default
-        }
-    }
-}
-
-/// Read a string value from the WA registry.
-///
-/// Opens `HKCU\Software\Team17SoftwareLTD\WormsArmageddon\{section}\{key}`
-/// and reads it as a REG_SZ string into `buf`. Returns the number of bytes
-/// written (excluding null terminator), or 0 on failure.
-pub fn read_profile_string(section: &str, key: &str, buf: &mut [u8]) -> usize {
-    let mut full_path = String::with_capacity(WA_REGISTRY_PATH.len() + section.len() + 1);
-    full_path.push_str(WA_REGISTRY_PATH);
-    full_path.push_str(section);
-    full_path.push('\0');
-
-    let mut key_buf = String::with_capacity(key.len() + 1);
-    key_buf.push_str(key);
-    key_buf.push('\0');
-
-    unsafe {
-        let mut hkey: HKEY = 0;
-        let status = RegOpenKeyExA(
-            HKEY_CURRENT_USER,
-            full_path.as_ptr(),
-            0,
-            KEY_READ,
-            &mut hkey,
-        );
-        if status != 0 {
-            return 0;
-        }
-
-        let mut value_size: u32 = buf.len() as u32;
-        let mut value_type: u32 = 0;
-        let status = RegQueryValueExA(
-            hkey,
-            key_buf.as_ptr(),
-            core::ptr::null_mut(),
-            &mut value_type,
-            buf.as_mut_ptr(),
-            &mut value_size,
-        );
-        RegCloseKey(hkey);
-
-        if status == 0 && value_type == REG_SZ && value_size > 0 {
-            // value_size includes null terminator
-            (value_size - 1) as usize
-        } else {
-            0
-        }
-    }
-}
-
-/// Recursively delete a registry key and all its subkeys.
-///
-/// Replacement for WA's Registry__DeleteKeyRecursive (0x4E4D10).
-/// Returns 0 on success, Win32 error code on failure.
-pub unsafe fn delete_key_recursive(parent: HKEY, subkey: &str) -> i32 {
-    if subkey.is_empty() {
-        return 0x3F2; // ERROR_INVALID_PARAMETER equivalent used by original
-    }
-
-    let mut subkey_buf = String::with_capacity(subkey.len() + 1);
-    subkey_buf.push_str(subkey);
-    subkey_buf.push('\0');
-
-    let mut hkey: HKEY = 0;
-    let status = RegOpenKeyExA(
-        parent,
-        subkey_buf.as_ptr(),
-        0,
-        KEY_READ | KEY_ENUMERATE_SUB_KEYS,
-        &mut hkey,
-    );
-    if status != 0 {
-        return status;
-    }
-
-    // Enumerate and recursively delete all child keys
-    let mut name_buf = vec![0u8; 256];
-    loop {
-        let mut name_len = name_buf.len() as u32;
-        let status = RegEnumKeyExA(
-            hkey,
-            0, // always index 0 since we delete as we go
-            name_buf.as_mut_ptr(),
-            &mut name_len,
-            core::ptr::null_mut(),
-            core::ptr::null_mut(),
-            core::ptr::null_mut(),
-            core::ptr::null_mut(),
-        );
-
-        if status == 0x103 {
-            // ERROR_NO_MORE_ITEMS — all children deleted
-            break;
-        }
-        if status != 0 {
-            RegCloseKey(hkey);
-            return status;
-        }
-
-        if name_len as usize == name_buf.len() {
-            // Name buffer too small, grow it
-            name_buf.resize(name_buf.len() * 2, 0);
-            continue;
-        }
-
-        // Null-terminate and recurse
-        name_buf[name_len as usize] = 0;
-        let child_name = core::str::from_utf8_unchecked(&name_buf[..name_len as usize]);
-        let result = delete_key_recursive(hkey, child_name);
-        if result != 0 {
-            RegCloseKey(hkey);
-            return result;
-        }
-    }
-
-    // All children deleted, now delete the key itself
-    let status = RegDeleteKeyA(parent, subkey_buf.as_ptr());
-    RegCloseKey(hkey);
-    status
-}
-```
-
-**Step 3: Build to verify**
-
-Run: `cargo build --release -p openwa-lib`
-Expected: clean build
-
-**Step 4: Commit**
-
-```
-feat: add Win32 registry helpers to openwa-lib
-```
-
----
-
-### Task 4: Create config.rs with Theme hooks
-
-**Files:**
-- Create: `crates/openwa-dll/src/replacements/config.rs`
-- Modify: `crates/openwa-dll/src/replacements/mod.rs`
-
-**Step 1: Add `mod config;` to mod.rs and call install**
-
-```rust
-mod config;
-mod frontend;
-mod scheme;
-
-pub fn install_all() -> Result<(), String> {
-    frontend::install()?;
-    scheme::install()?;
-    config::install()?;
-    Ok(())
-}
-```
-
-**Step 2: Create config.rs with theme functions**
-
-```rust
-//! Configuration system hooks.
-//!
-//! Replaces WA.exe configuration functions with Rust implementations:
-//! - Theme__GetFileSize (0x44BA80): theme file size query
-//! - Theme__Load (0x44BB20): theme file read
-//! - Theme__Save (0x44BBC0): theme file write
-//! - Registry__DeleteKeyRecursive (0x4E4D10): recursive registry deletion
-//! - Registry__CleanAll (0x4C90D0): full registry cleanup
-//! - GameInfo__LoadOptions (0x460AC0): game options from registry
-//! - Options__GetCrashReportURL (0x5A63F0): crash report URL from registry
-
-use crate::log_line;
-use openwa_lib::rebase::rb;
-use openwa_types::address::va;
-
-const THEME_PATH: &str = "data\\current.thm";
-
-// ============================================================
-// Theme__GetFileSize replacement (0x44BA80)
-// ============================================================
-
-/// Rust replacement for Theme__GetFileSize.
-/// cdecl() -> u32 (file length, or 0 if missing)
-unsafe extern "cdecl" fn hook_theme_get_file_size() -> u32 {
-    match std::fs::metadata(THEME_PATH) {
-        Ok(m) => m.len() as u32,
-        Err(_) => 0,
-    }
-}
-
-// ============================================================
-// Theme__Load replacement (0x44BB20)
-// ============================================================
-
-/// Rust replacement for Theme__Load.
-/// stdcall(dest_buffer: *mut u8)
-unsafe extern "stdcall" fn hook_theme_load(dest: u32) {
-    match std::fs::read(THEME_PATH) {
-        Ok(data) => {
-            core::ptr::copy_nonoverlapping(data.as_ptr(), dest as *mut u8, data.len());
-        }
-        Err(_) => {
-            show_error_message("ERROR: NO CURRENT.THM FILE FOUND");
-        }
-    }
-}
-
-// ============================================================
-// Theme__Save replacement (0x44BBC0)
-// ============================================================
-
-/// Rust replacement for Theme__Save.
-/// stdcall(buffer: *const u8, size: u32)
-unsafe extern "stdcall" fn hook_theme_save(buffer: u32, size: u32) {
-    let data = core::slice::from_raw_parts(buffer as *const u8, size as usize);
-    if let Err(_) = std::fs::write(THEME_PATH, data) {
-        show_error_message("ERROR: Could Not create CURRENT.THM File");
-    }
-}
-
-/// Show an error message box, matching AfxMessageBox behavior.
-fn show_error_message(msg: &str) {
-    use windows_sys::Win32::UI::WindowsAndMessaging::*;
-    let mut msg_buf: Vec<u8> = msg.bytes().collect();
-    msg_buf.push(0);
-    unsafe {
-        MessageBoxA(0, msg_buf.as_ptr(), core::ptr::null(), MB_OK);
-    }
-}
-
-// ============================================================
-// Hook installation
-// ============================================================
-
-pub fn install() -> Result<(), String> {
-    unsafe {
-        let _ = crate::hook::install(
-            "Theme__GetFileSize",
-            va::THEME_GET_FILE_SIZE,
-            hook_theme_get_file_size as *const (),
-        )?;
-
-        let _ = crate::hook::install(
-            "Theme__Load",
-            va::THEME_LOAD,
-            hook_theme_load as *const (),
-        )?;
-
-        let _ = crate::hook::install(
-            "Theme__Save",
-            va::THEME_SAVE,
-            hook_theme_save as *const (),
-        )?;
-    }
-
-    Ok(())
-}
-```
-
-**Step 3: Add windows-sys dependency to openwa-dll Cargo.toml**
-
-The `windows-sys` dep in openwa-dll needs the UI feature too. Update the existing entry:
-
-```toml
-[target.'cfg(target_os = "windows")'.dependencies]
-windows-sys = { version = "0.59", features = [
-    "Win32_System_Memory",
-    "Win32_UI_WindowsAndMessaging",
-] }
-```
-
-**Step 4: Build to verify**
-
-Run: `cargo build --release -p openwa-dll`
-Expected: clean build
-
-**Step 5: Deploy + test theme**
-
-Copy DLL, launch game. Theme should load normally (visual appearance unchanged). Check OpenWA.log for hook messages.
-
-**Step 6: Commit**
-
-```
-feat: add Theme file I/O hooks (GetFileSize, Load, Save)
-```
-
----
-
-### Task 5: Add Registry hooks
-
-**Files:**
-- Modify: `crates/openwa-dll/src/replacements/config.rs`
-
-**Step 1: Add registry hook functions**
-
-Add after the Theme section, before `install()`:
-
-```rust
-// ============================================================
-// Registry__DeleteKeyRecursive replacement (0x4E4D10)
-// ============================================================
-
-/// Rust replacement for Registry__DeleteKeyRecursive.
-/// stdcall(hkey: HKEY, subkey: *const u8) -> i32
-unsafe extern "stdcall" fn hook_delete_key_recursive(hkey: u32, subkey: u32) -> i32 {
-    use windows_sys::Win32::System::Registry::HKEY;
-
-    let c_subkey = std::ffi::CStr::from_ptr(subkey as *const i8);
-    let subkey_str = c_subkey.to_string_lossy();
-
-    let _ = log_line(&format!("[Config] DeleteKeyRecursive: {subkey_str}"));
-
-    let result = openwa_lib::wa::registry::delete_key_recursive(
-        hkey as HKEY,
-        &subkey_str,
-    );
-
-    let _ = log_line(&format!("[Config] DeleteKeyRecursive result: {result}"));
-    result
-}
-
-// ============================================================
-// Registry__CleanAll replacement (0x4C90D0)
-// ============================================================
-
-/// Rust replacement for Registry__CleanAll.
-/// stdcall(struct_ptr: u32)
-unsafe extern "stdcall" fn hook_registry_clean_all(struct_ptr: u32) {
-    use windows_sys::Win32::System::Registry::HKEY_CURRENT_USER;
-    use windows_sys::Win32::UI::WindowsAndMessaging::*;
-
-    let _ = log_line("[Config] CleanAll: deleting registry sections");
-
-    let sections = [
-        "Software\\Team17SoftwareLTD\\WormsArmageddon\\Data",
-        "Software\\Team17SoftwareLTD\\WormsArmageddon\\Options",
-        "Software\\Team17SoftwareLTD\\WormsArmageddon\\ExportVideo",
-        "Software\\Team17SoftwareLTD\\WormsArmageddon\\VSyncAssist",
-    ];
-
-    for section in &sections {
-        openwa_lib::wa::registry::delete_key_recursive(HKEY_CURRENT_USER, section);
-    }
-
-    // Clear the NetSettings INI section
-    WriteProfileSectionA(b"NetSettings\0".as_ptr(), b"\0".as_ptr());
-
-    // Set struct_ptr + 0xE0 = 0
-    *((struct_ptr + 0xE0) as *mut u8) = 0;
-
-    let _ = log_line("[Config] CleanAll completed");
-}
-```
-
-**Step 2: Wire up in install()**
-
-Add before the closing `Ok(())`:
-
-```rust
-        let _ = crate::hook::install(
-            "Registry__DeleteKeyRecursive",
-            va::REGISTRY_DELETE_KEY_RECURSIVE,
-            hook_delete_key_recursive as *const (),
-        )?;
-
-        let _ = crate::hook::install(
-            "Registry__CleanAll",
-            va::REGISTRY_CLEAN_ALL,
-            hook_registry_clean_all as *const (),
-        )?;
-```
-
-**Step 3: Build to verify**
-
-Run: `cargo build --release -p openwa-dll`
-Expected: clean build
-
-**Step 4: Commit**
-
-```
-feat: add Registry cleanup hooks (DeleteKeyRecursive, CleanAll)
-```
-
----
-
-### Task 6: Add GameInfo__LoadOptions hook
-
-**Files:**
-- Modify: `crates/openwa-dll/src/replacements/config.rs`
-- Modify: `crates/openwa-types/src/address.rs` (global data addresses)
-
-**Step 1: Add global data address constants**
-
-Add to `address.rs` in the `// === Global variables (in .data) ===` section:
-
-```rust
-/// Base directory string (null-terminated)
-pub const G_BASE_DIR: u32 = 0x0088_E282;
-/// 64-byte data block copied into GameInfo+0xF485
-pub const G_GAMEINFO_BLOCK_F485: u32 = 0x0088_DFF3;
-/// "data\land.dat" string constant (14 bytes)
-pub const G_LAND_DAT_STRING: u32 = 0x0064_DA58;
-/// Unknown byte read into GameInfo+0xF3A0
-pub const G_CONFIG_BYTE_F3A0: u32 = 0x007C_0D38;
-/// 5 DWORDs: GameInfo offsets +0xF3B4..+0xF3D0
-pub const G_CONFIG_DWORDS_F3B4: u32 = 0x0088_E39C;
-/// Guard flag for conditional config copies
-pub const G_CONFIG_GUARD: u32 = 0x0088_C374;
-/// 4 DWORDs (conditional): GameInfo offsets +0xF3F4..+0xF400
-pub const G_CONFIG_DWORDS_F3F4: u32 = 0x0088_E3B8;
-/// DWORD → GameInfo+0xDAE8
-pub const G_CONFIG_DWORD_DAE8: u32 = 0x0088_E390;
-/// 2 DWORDs → GameInfo+0xF3D4, +0xF3D8
-pub const G_CONFIG_DWORDS_F3D4: u32 = 0x0088_E3B0;
-/// 3 DWORDs → GameInfo+0xF3C4..+0xF3CC
-pub const G_CONFIG_DWORDS_F3C4: u32 = 0x0088_E400;
-/// DWORD → GameInfo+0xF3E4
-pub const G_CONFIG_DWORD_F3E4: u32 = 0x0088_E44C;
-/// Streams directory path buffer
-pub const G_STREAMS_DIR: u32 = 0x0088_AE18;
-/// Random stream indices (16 entries)
-pub const G_STREAM_INDICES: u32 = 0x0088_AE9C;
-/// Stream index end sentinel
-pub const G_STREAM_INDICES_END: u32 = 0x0088_AEDC;
-/// DAT_0088E394 flag for stream volume
-pub const G_STREAM_FLAG: u32 = 0x0088_E394;
-/// Stream volume byte
-pub const G_STREAM_VOLUME: u32 = 0x0088_AEDD;
-```
-
-**Step 2: Add LoadOptions hook function**
-
-Add to config.rs before `install()`:
-
-```rust
-// ============================================================
-// GameInfo__LoadOptions replacement (0x460AC0)
-// ============================================================
-
-/// Rust replacement for GameInfo__LoadOptions.
-/// stdcall(game_info: u32)
-///
-/// Reads game options from the Windows registry and copies various globals
-/// into the GameInfo struct at known offsets.
-unsafe extern "stdcall" fn hook_load_options(gi: u32) {
-    use openwa_lib::wa::registry::read_profile_int;
-
-    let _ = log_line("[Config] LoadOptions: loading game options from registry");
-
-    // Format speech path: "%s\user\speech"
-    let base_dir = rb(va::G_BASE_DIR) as *const u8;
-    let speech_dest = (gi + 0xF404) as *mut u8;
-    let base_str = std::ffi::CStr::from_ptr(base_dir as *const i8);
-    let speech_path = format!("{}\\user\\speech\0", base_str.to_string_lossy());
-    core::ptr::copy_nonoverlapping(
-        speech_path.as_ptr(),
-        speech_dest,
-        speech_path.len(),
-    );
-
-    // Copy 64 bytes from global 0x88DFF3 → GameInfo+0xF485
-    core::ptr::copy_nonoverlapping(
-        rb(va::G_GAMEINFO_BLOCK_F485) as *const u8,
-        (gi + 0xF485) as *mut u8,
-        64,
-    );
-
-    // Format streams directory and randomize stream indices
-    let streams_dest = rb(va::G_STREAMS_DIR) as *mut u8;
-    let streams_path = format!("{}\\streams\0", base_str.to_string_lossy());
-    core::ptr::copy_nonoverlapping(
-        streams_path.as_ptr(),
-        streams_dest,
-        streams_path.len(),
-    );
-
-    // Randomize stream indices (16 entries, each rand() % 11 + 1)
-    let indices = rb(va::G_STREAM_INDICES) as *mut u32;
-    let indices_end = rb(va::G_STREAM_INDICES_END) as usize;
-    let mut ptr = indices;
-    while (ptr as usize) < indices_end {
-        extern "cdecl" { fn rand() -> i32; }
-        *ptr = (rand() % 11 + 1) as u32;
-        ptr = ptr.add(1);
-    }
-
-    // Stream volume: 0x10 if flag set, else 0
-    let stream_vol_addr = rb(va::G_STREAM_INDICES_END) as *mut u8;
-    *stream_vol_addr = if *(rb(va::G_STREAM_FLAG) as *const u32) != 0 { 0x10 } else { 0 };
-    // Secondary volume byte
-    *(rb(va::G_STREAM_VOLUME) as *mut u8) = 0x4B;
-
-    // Copy "data\land.dat" string (14 bytes) → GameInfo+0xDAEC
-    core::ptr::copy_nonoverlapping(
-        rb(va::G_LAND_DAT_STRING) as *const u8,
-        (gi + 0xDAEC) as *mut u8,
-        14,
-    );
-
-    // Copy byte from global → GameInfo+0xF3A0
-    *((gi + 0xF3A0) as *mut u8) = *(rb(va::G_CONFIG_BYTE_F3A0) as *const u8);
-
-    // Read registry values from "Options" section
-    let detail = read_profile_int("Options", "DetailLevel", 5);
-    *((gi + 0xF3A1) as *mut u8) = detail as u8;
-
-    // Zero 2 bytes at +0xF3F0
-    *((gi + 0xF3F0) as *mut u16) = 0;
-
-    // Copy 5 DWORDs from globals → GameInfo+0xF3B4..+0xF3D0
-    let src = rb(va::G_CONFIG_DWORDS_F3B4) as *const u32;
-    for i in 0u32..5 {
-        let offset = 0xF3B4 + i * 4;
-        *((gi + offset) as *mut u32) = *src.add(i as usize);
-    }
-
-    // Conditional copy: 4 DWORDs if guard == 0
-    if *(rb(va::G_CONFIG_GUARD) as *const u32) == 0 {
-        let src = rb(va::G_CONFIG_DWORDS_F3F4) as *const u32;
-        for i in 0u32..4 {
-            let offset = 0xF3F4 + i * 4;
-            *((gi + offset) as *mut u32) = *src.add(i as usize);
-        }
-    }
-
-    // Single DWORDs from globals
-    *((gi + 0xDAE8) as *mut u32) = *(rb(va::G_CONFIG_DWORD_DAE8) as *const u32);
-
-    let src_d4 = rb(va::G_CONFIG_DWORDS_F3D4) as *const u32;
-    *((gi + 0xF3D4) as *mut u32) = *src_d4;
-    *((gi + 0xF3D8) as *mut u32) = *src_d4.add(1);
-
-    // EnergyBar
-    let energy = read_profile_int("Options", "EnergyBar", 1);
-    *((gi + 0xF3A2) as *mut u8) = energy as u8;
-
-    // 3 DWORDs from globals → +0xF3C4..+0xF3CC
-    let src_c4 = rb(va::G_CONFIG_DWORDS_F3C4) as *const u32;
-    for i in 0u32..3 {
-        let offset = 0xF3C4 + i * 4;
-        *((gi + offset) as *mut u32) = *src_c4.add(i as usize);
-    }
-
-    // Remaining registry values
-    let info_trans = read_profile_int("Options", "InfoTransparency", 0);
-    *((gi + 0xF3A3) as *mut u8) = info_trans as u8;
-
-    let info_spy = read_profile_int("Options", "InfoSpy", 1);
-    *((gi + 0xF3A4) as *mut u8) = if info_spy != 0 { 1 } else { 0 };
-
-    let chat_pinned = read_profile_int("Options", "ChatPinned", 0);
-    *((gi + 0xF3A5) as *mut u8) = chat_pinned as u8;
-
-    let chat_lines = read_profile_int("Options", "ChatLines", 0);
-    *((gi + 0xF3A8) as *mut u32) = chat_lines;
-
-    let pinned_lines = read_profile_int("Options", "PinnedChatLines", 0xFFFFFFFF);
-    *((gi + 0xF3AC) as *mut u32) = pinned_lines;
-
-    let home_lock = read_profile_int("Options", "HomeLock", 0);
-    *((gi + 0xF3B0) as *mut u8) = home_lock as u8;
-
-    // BackgroundDebrisParallax: clamp to i16 range, then << 16
-    let mut parallax = read_profile_int("Options", "BackgroundDebrisParallax", 0x50);
-    let parallax_i32 = parallax as i32;
-    if parallax_i32 < -0x8000 || parallax_i32 > 0x7FFF {
-        // Clamp to i16 range
-        if parallax_i32 < 0 {
-            parallax = (-0x8000i32) as u32;
-        } else {
-            parallax = 0x7FFF;
-        }
-    }
-    *((gi + 0xF3E8) as *mut u32) = parallax << 16;
-
-    let onomatopoeia = read_profile_int("Options", "TopmostExplosionOnomatopoeia", 0);
-    *((gi + 0xF3EC) as *mut u32) = onomatopoeia;
-
-    let capture_png = read_profile_int("Options", "CaptureTransparentPNGs", 0);
-    *((gi + 0xF3DC) as *mut u32) = capture_png;
-
-    // CameraUnlockMouseSpeed: clamp to max 0xB504, then square
-    let mut mouse_speed = read_profile_int("Options", "CameraUnlockMouseSpeed", 0x10);
-    if mouse_speed > 0xB504 {
-        if (mouse_speed as i32) < 0 {
-            mouse_speed = 0; // negative → 0
-        } else {
-            mouse_speed = 0xB504;
-        }
-    }
-    *((gi + 0xF3E0) as *mut u32) = mouse_speed * mouse_speed;
-
-    // Final global DWORD
-    *((gi + 0xF3E4) as *mut u32) = *(rb(va::G_CONFIG_DWORD_F3E4) as *const u32);
-
-    let _ = log_line("[Config] LoadOptions completed (Rust)");
-}
-```
-
-**Step 3: Wire up in install()**
-
-Add to the unsafe block in `install()`:
-
-```rust
-        let _ = crate::hook::install(
-            "GameInfo__LoadOptions",
-            va::GAMEINFO_LOAD_OPTIONS,
-            hook_load_options as *const (),
-        )?;
-```
-
-**Step 4: Build to verify**
-
-Run: `cargo build --release -p openwa-dll`
-Expected: clean build
-
-**Step 5: Deploy + test options**
-
-Launch game, change Detail Level in options, restart, verify it persists. Check OpenWA.log.
-
-**Step 6: Commit**
-
-```
-feat: add GameInfo__LoadOptions hook (registry reads)
-```
-
----
-
-### Task 7: Add Options__GetCrashReportURL hook
-
-**Files:**
-- Modify: `crates/openwa-dll/src/replacements/config.rs`
-- Modify: `crates/openwa-types/src/address.rs`
-
-**Step 1: Add global address for the URL buffer**
-
-Add to address.rs globals section:
-
-```rust
-/// CrashReportURL static buffer (0x400 bytes)
-pub const G_CRASH_REPORT_URL: u32 = 0x0079_FFD8;
-```
-
-**Step 2: Add hook function**
-
-Add to config.rs before `install()`:
-
-```rust
-// ============================================================
-// Options__GetCrashReportURL replacement (0x5A63F0)
-// ============================================================
-
-/// Rust replacement for Options__GetCrashReportURL.
-/// cdecl() -> *const u8 (pointer to static buffer, or null)
-unsafe extern "cdecl" fn hook_get_crash_report_url() -> u32 {
-    let buf = rb(va::G_CRASH_REPORT_URL) as *mut u8;
-    let mut buf_slice = core::slice::from_raw_parts_mut(buf, 0x401);
-
-    let len = openwa_lib::wa::registry::read_profile_string(
-        "Options",
-        "CrashReportURL",
-        &mut buf_slice[..0x400],
-    );
-
-    if len > 0 {
-        // Null-terminate
-        *buf.add(len) = 0;
-        buf as u32
-    } else {
-        0 // null pointer = not found
-    }
-}
-```
-
-**Step 3: Wire up in install()**
-
-```rust
-        let _ = crate::hook::install(
-            "Options__GetCrashReportURL",
-            va::OPTIONS_GET_CRASH_REPORT_URL,
-            hook_get_crash_report_url as *const (),
-        )?;
-```
-
-**Step 4: Build to verify**
-
-Run: `cargo build --release -p openwa-dll`
-Expected: clean build
-
-**Step 5: Commit**
-
-```
-feat: add Options__GetCrashReportURL hook
-```
-
----
-
-### Task 8: Full integration test + final commit
-
-**Step 1: Build clean**
-
-Run: `cargo build --release -p openwa-dll`
-Expected: clean build, no warnings
-
-**Step 2: Deploy**
-
-```bash
-cp target/i686-pc-windows-msvc/release/openwa.dll "I:/games/SteamLibrary/steamapps/common/Worms Armageddon/wkOpenWA.dll"
-```
-
-**Step 3: In-game verification**
-
-1. Launch game → main menu
-2. Check OpenWA.log for all 7 `[REPLACE]` messages + `[Config] LoadOptions completed`
-3. Verify theme loads correctly (visual appearance unchanged)
-4. Go to Options, change Detail Level, accept
-5. Restart game, verify Detail Level persists
-6. Verify existing scheme functionality still works (quick game setup)
-
-**Step 4: Squash/rebase if desired, or leave incremental commits**

docs/plans/2026-03-07-replay-testing-design.md

@@ -1,97 +0,0 @@
-# Replay-Based Automated Testing Design
-
-**Date:** 2026-03-07
-**Status:** Approved
-
-## Problem
-
-The current validation workflow is manual: start WA.exe, navigate menus, start a game, press F9/F10 hotkeys, read logs. This is slow and non-reproducible. We need an automated way to launch the game into a known gameplay state for validation and RE discovery.
-
-## Key Insight
-
-WA.exe accepts a replay file (`.WAgame`) as a command-line argument. It starts playing automatically, skipping menus, and closes when the replay finishes. This gives us a deterministic, automated path into gameplay state.
-
-## Design
-
-### Components
-
-#### 1. PowerShell script (`replay-test.ps1`)
-
-Orchestrates the full workflow:
-
-1. Build both DLLs (`cargo build --release -p openwa-dll -p openwa-validator`)
-2. Deploy to game directory (same as `deploy.ps1`)
-3. Clear old `OpenWA_validation.log` and `OpenWA.log` in game directory
-4. Set `OPENWA_REPLAY_TEST=1` in environment
-5. Launch `WA.exe <replay-file>` and wait for process exit
-6. Copy both log files to `testdata/logs/` in the project
-7. Print summary (PASS/FAIL counts from log)
-
-Accepts one argument: replay file path. Defaults to `testdata/replays/bots.WAgame`.
-
-#### 2. Validator DLL changes (`openwa-validator`)
-
-At startup in `run_validation()`, check `std::env::var("OPENWA_REPLAY_TEST")`:
-
-- **Not set:** Current behavior (deferred timer threads, hotkey listener, runs indefinitely).
-- **Set:** Spawn a single "auto-capture" thread that:
-  1. Waits 30 seconds (enough for replay to reach gameplay)
-  2. Runs `deferred_global_validation()`
-  3. Runs `dump_team_blocks()`
-  4. Runs `dump_landscape()`
-  5. Logs `"--- Auto-capture complete, exiting ---"`
-  6. Calls `ExitProcess(0)` to terminate WA.exe
-
-No hotkey listener or timer threads in automated mode -- one clean capture sequence.
-
-#### 3. Claude Code skill (`replay-test`)
-
-A skill that:
-- Invokes `replay-test.ps1` via Bash
-- Reads the resulting log files from `testdata/logs/`
-- Presents results in the conversation
-
-### Data Flow
-
-```
-/replay-test
-  -> Bash: powershell -File replay-test.ps1 testdata/replays/bots.WAgame
-    -> cargo build --release
-    -> deploy DLLs to game dir
-    -> clear logs
-    -> set OPENWA_REPLAY_TEST=1
-    -> start WA.exe bots.WAgame (blocks until exit)
-      -> validator DLL starts
-      -> detects env var -> auto-capture mode
-      -> waits 30s -> dumps -> ExitProcess(0)
-    -> WA.exe exits
-    -> copy logs to testdata/logs/
-    -> print summary
-  -> Skill reads testdata/logs/*.log
-  -> presents to user
-```
-
-### File Locations
-
-| File | Location |
-|------|----------|
-| Orchestration script | `replay-test.ps1` (project root) |
-| Replay files | `testdata/replays/*.WAgame` |
-| Captured logs | `testdata/logs/` (gitignored) |
-| Skill definition | User's Claude Code skills directory |
-
-### Environment Variable
-
-| Variable | Value | Effect |
-|----------|-------|--------|
-| `OPENWA_REPLAY_TEST` | `1` | Validator enters auto-capture mode: single 30s wait, dump all, ExitProcess |
-| (unset) | -- | Normal interactive mode with hotkeys and timer threads |
-
-## Future Expansion (Not In Scope)
-
-- Configurable wait time or dump selection via env vars or config file
-- Event-based hooks (dump on CreateExplosion, WeaponRelease, etc.)
-- Frame-count triggers via ProcessFrame hook
-- Structured output (JSON) for programmatic diffing
-- Multiple replay files in one run
-- CI integration with exit codes based on PASS/FAIL counts

docs/plans/2026-03-07-replay-testing-plan.md

@@ -1,332 +0,0 @@
-# Replay-Based Automated Testing Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Enable automated validation and RE discovery by launching WA.exe with replay files, auto-capturing memory dumps, and presenting results via a Claude Code skill.
-
-**Architecture:** A PowerShell script orchestrates build/deploy/launch/log-copy. The validator DLL detects `OPENWA_REPLAY_TEST` env var and runs a single auto-capture sequence (wait 30s, dump all, ExitProcess). A Claude Code skill wraps the script and reads logs.
-
-**Tech Stack:** PowerShell, Rust (openwa-validator), Claude Code skills (markdown)
-
----
-
-### Task 1: Add `testdata/logs/` to `.gitignore`
-
-**Files:**
-- Modify: `.gitignore`
-
-**Step 1: Add the gitignore entry**
-
-Append to `.gitignore`:
-```
-testdata/logs/
-```
-
-**Step 2: Commit**
-
-```bash
-git add .gitignore
-git commit -m "chore: gitignore testdata/logs/"
-```
-
----
-
-### Task 2: Add auto-capture mode to validator DLL
-
-**Files:**
-- Modify: `crates/openwa-validator/Cargo.toml` (add `Win32_System_Threading` feature)
-- Modify: `crates/openwa-validator/src/lib.rs` (add auto-capture branch in `run_validation()`)
-
-**Step 1: Add `Win32_System_Threading` feature to Cargo.toml**
-
-In `crates/openwa-validator/Cargo.toml`, add `"Win32_System_Threading"` to the windows-sys features list. This is needed for `ExitProcess`.
-
-```toml
-windows-sys = { version = "0.59", features = [
-    "Win32_System_Memory",
-    "Win32_System_LibraryLoader",
-    "Win32_UI_Input_KeyboardAndMouse",
-    "Win32_System_Threading",
-] }
-```
-
-**Step 2: Modify `run_validation()` in `crates/openwa-validator/src/lib.rs`**
-
-After the static validation and hook installation (after step 6 in current code, line ~814), add a branch that checks the env var. Replace the current deferred/hotkey thread spawning (lines 816-856) with:
-
-```rust
-    // 7. Mode-dependent: auto-capture vs interactive
-    let auto_mode = std::env::var("OPENWA_REPLAY_TEST").is_ok();
-
-    if auto_mode {
-        let _ = log_line("");
-        let _ = log_line("--- Auto-Capture Mode (OPENWA_REPLAY_TEST) ---");
-        std::thread::spawn(move || {
-            let _ = log_line("  Waiting 30s for replay to reach gameplay...");
-            std::thread::sleep(std::time::Duration::from_secs(30));
-
-            let _ = log_line("  Running deferred global validation...");
-            deferred_global_validation();
-
-            let _ = log_line("  Running team block dump...");
-            dump_team_blocks();
-
-            let _ = log_line("  Running landscape dump...");
-            dump_landscape();
-
-            let _ = log_line("");
-            let _ = log_line("--- Auto-capture complete, exiting ---");
-
-            unsafe {
-                windows_sys::Win32::System::Threading::ExitProcess(0);
-            }
-        });
-    } else {
-        // Existing interactive mode: deferred timers + hotkey listener
-        let _ = log_line("");
-        let _ = log_line("--- Interactive Mode (deferred polling + hotkeys) ---");
-        std::thread::spawn(move || {
-            std::thread::sleep(std::time::Duration::from_secs(10));
-            deferred_global_validation();
-        });
-        let _ = log_line("  Polling thread started (10s delay).");
-
-        std::thread::spawn(move || {
-            std::thread::sleep(std::time::Duration::from_secs(30));
-            dump_team_blocks();
-        });
-        let _ = log_line("  Team block dump thread started (30s delay).");
-
-        std::thread::spawn(move || {
-            std::thread::sleep(std::time::Duration::from_secs(15));
-            dump_landscape();
-        });
-        let _ = log_line("  Landscape dump thread started (15s delay).");
-
-        std::thread::spawn(|| {
-            const VK_F9: i32 = 0x78;
-            const VK_F10: i32 = 0x79;
-            let _ = log_line("  Hotkey listener started (F9=team blocks, F10=landscape).");
-            loop {
-                std::thread::sleep(std::time::Duration::from_millis(100));
-                unsafe {
-                    if GetAsyncKeyState(VK_F9) & 1 != 0 {
-                        dump_team_blocks();
-                    }
-                    if GetAsyncKeyState(VK_F10) & 1 != 0 {
-                        dump_landscape();
-                    }
-                }
-            }
-        });
-    }
-```
-
-**Step 3: Verify it compiles**
-
-Run: `cargo build --release -p openwa-validator`
-Expected: Compiles successfully.
-
-**Step 4: Commit**
-
-```bash
-git add crates/openwa-validator/Cargo.toml crates/openwa-validator/src/lib.rs
-git commit -m "feat: add auto-capture mode to validator DLL via OPENWA_REPLAY_TEST env var"
-```
-
----
-
-### Task 3: Create the PowerShell orchestration script
-
-**Files:**
-- Create: `replay-test.ps1`
-
-**Step 1: Create `replay-test.ps1`**
-
-```powershell
-# replay-test.ps1 - Automated replay-based testing
-# Usage: powershell -File replay-test.ps1 [replay-file]
-
-param(
-    [string]$ReplayFile = "testdata\replays\bots.WAgame"
-)
-
-$ErrorActionPreference = "Stop"
-
-$gameDir = "I:\games\SteamLibrary\steamapps\common\Worms Armageddon"
-$waExe = "$gameDir\WA.exe"
-$src = "target\i686-pc-windows-msvc\release"
-$logDir = "testdata\logs"
-
-# Resolve replay file to absolute path
-if (-not [System.IO.Path]::IsPathRooted($ReplayFile)) {
-    $ReplayFile = Join-Path (Get-Location) $ReplayFile
-}
-
-if (-not (Test-Path $ReplayFile)) {
-    Write-Error "Replay file not found: $ReplayFile"
-    exit 1
-}
-
-# 1. Build
-Write-Host "Building..." -ForegroundColor Cyan
-cargo build --release -p openwa-dll -p openwa-validator
-if ($LASTEXITCODE -ne 0) { exit 1 }
-
-# 2. Deploy
-Write-Host "Deploying to $gameDir..." -ForegroundColor Cyan
-Copy-Item "$src\openwa.dll" "$gameDir\wkOpenWA.dll"
-Copy-Item "$src\openwa_validator.dll" "$gameDir\wkOpenWAValidator.dll"
-
-# 3. Clear old logs
-Remove-Item "$gameDir\OpenWA.log" -ErrorAction SilentlyContinue
-Remove-Item "$gameDir\OpenWA_validation.log" -ErrorAction SilentlyContinue
-
-# 4. Launch WA.exe with replay, env var set
-Write-Host "Launching WA.exe with replay: $ReplayFile" -ForegroundColor Cyan
-Write-Host "  (Auto-capture mode: will exit after 30s)" -ForegroundColor Yellow
-
-$env:OPENWA_REPLAY_TEST = "1"
-$proc = Start-Process -FilePath $waExe -ArgumentList "`"$ReplayFile`"" -PassThru
-$proc.WaitForExit()
-$env:OPENWA_REPLAY_TEST = $null
-
-Write-Host "WA.exe exited with code $($proc.ExitCode)" -ForegroundColor Cyan
-
-# 5. Copy logs back
-if (-not (Test-Path $logDir)) {
-    New-Item -ItemType Directory -Path $logDir | Out-Null
-}
-
-$timestamp = Get-Date -Format "yyyy-MM-dd_HH-mm-ss"
-
-if (Test-Path "$gameDir\OpenWA_validation.log") {
-    Copy-Item "$gameDir\OpenWA_validation.log" "$logDir\validation_$timestamp.log"
-    Copy-Item "$gameDir\OpenWA_validation.log" "$logDir\validation_latest.log"
-    Write-Host "Validation log copied." -ForegroundColor Green
-} else {
-    Write-Host "WARNING: No validation log found!" -ForegroundColor Red
-}
-
-if (Test-Path "$gameDir\OpenWA.log") {
-    Copy-Item "$gameDir\OpenWA.log" "$logDir\openwa_$timestamp.log"
-    Copy-Item "$gameDir\OpenWA.log" "$logDir\openwa_latest.log"
-    Write-Host "OpenWA log copied." -ForegroundColor Green
-}
-
-# 6. Print summary
-Write-Host ""
-Write-Host "=== Validation Summary ===" -ForegroundColor Cyan
-if (Test-Path "$logDir\validation_latest.log") {
-    $content = Get-Content "$logDir\validation_latest.log" -Raw
-    $passes = ([regex]::Matches($content, "\[PASS\]")).Count
-    $fails = ([regex]::Matches($content, "\[FAIL\]")).Count
-    Write-Host "  PASS: $passes" -ForegroundColor Green
-    Write-Host "  FAIL: $fails" -ForegroundColor $(if ($fails -gt 0) { "Red" } else { "Green" })
-
-    if ($content -match "Auto-capture complete") {
-        Write-Host "  Auto-capture: completed successfully" -ForegroundColor Green
-    } else {
-        Write-Host "  Auto-capture: NOT found in log (may not have reached gameplay)" -ForegroundColor Yellow
-    }
-}
-Write-Host "  Logs: $logDir\" -ForegroundColor Gray
-```
-
-**Step 2: Test the script manually**
-
-Run: `powershell -File replay-test.ps1`
-
-Expected: Builds, deploys, launches WA.exe with `bots.WAgame`, WA exits after ~30s, logs appear in `testdata/logs/`.
-
-**Step 3: Commit**
-
-```bash
-git add replay-test.ps1
-git commit -m "feat: add replay-test.ps1 orchestration script"
-```
-
----
-
-### Task 4: Create the Claude Code skill
-
-**Files:**
-- Create: `.claude/skills/replay-test.md`
-
-**Step 1: Create skill directory and file**
-
-Create `.claude/skills/replay-test.md`:
-
-```markdown
----
-name: replay-test
-description: Run automated replay-based testing - builds, deploys, launches WA.exe with a replay file, captures validation logs, and presents results. Use when you need to validate struct layouts, hooks, or game state against live WA.exe.
-user_invocable: true
----
-
-# Replay Test
-
-Run the replay-based automated testing pipeline.
-
-## Steps
-
-1. Run the replay test script:
-
-```bash
-powershell -File replay-test.ps1
-```
-
-This will:
-- Build openwa-dll and openwa-validator
-- Deploy DLLs to the WA game directory
-- Launch WA.exe with the default replay file (testdata/replays/bots.WAgame)
-- Wait for auto-capture (30s) and process exit
-- Copy logs to testdata/logs/
-
-2. Read the validation log and present results:
-
-Read `testdata/logs/validation_latest.log` and summarize:
-- Total PASS/FAIL counts
-- Any [FAIL] lines (quote them exactly)
-- Whether auto-capture completed
-- Key data from dumps (team blocks, landscape) if present
-
-3. If the user also has `testdata/logs/openwa_latest.log`, read it and note any errors or interesting hook activity.
-
-## Notes
-
-- The script takes ~40 seconds total (build + 30s auto-capture wait)
-- If WA.exe doesn't exit, the validator DLL may not have loaded. Check that wkOpenWAValidator.dll exists in the game directory.
-- Replay file can be changed by editing the script invocation: `powershell -File replay-test.ps1 path\to\other.WAgame`
-```
-
-**Step 2: Commit**
-
-```bash
-git add .claude/skills/replay-test.md
-git commit -m "feat: add /replay-test Claude Code skill"
-```
-
----
-
-### Task 5: End-to-end test
-
-**Step 1: Run the skill**
-
-Invoke `/replay-test` and verify the full pipeline works:
-- Build succeeds
-- WA.exe launches with replay
-- WA.exe exits after ~30s
-- Logs are copied to `testdata/logs/`
-- Validation summary shows PASS/FAIL counts
-- Auto-capture complete message is present in log
-
-**Step 2: Review logs for correctness**
-
-Check that:
-- Static validation (vtables, prologues, struct offsets) all PASS
-- Deferred global validation ran (DDGameWrapper vtable check)
-- Team block dump shows team data (worm names, health, state)
-- Landscape dump shows level data (dimensions, layers)
-
-**Step 3: Fix any issues found, commit fixes**

docs/plans/2026-03-08-replay-fastforward-design.md

@@ -1,61 +0,0 @@
-# Replay Fast-Forward Design
-
-## Goal
-
-Automatically fast-forward through entire WA replays during `OPENWA_REPLAY_TEST=1` mode, enabling comprehensive testing beyond the current 5-second window.
-
-## Background
-
-The current replay test captures only 5 seconds of gameplay — often not enough for a single worm turn. WA advances one turn per spacebar press during replay playback. The game detects key-DOWN transitions (not held state) and has no key repeat, so spacebar must be repeatedly pressed and released.
-
-WA.exe exits automatically when a replay finishes, so no explicit exit is needed if we can fast-forward through the whole thing.
-
-## Approach: Hook GetAsyncKeyState
-
-Hook `GetAsyncKeyState` from `user32.dll` via MinHook. When the game queries `VK_SPACE` and fast-forward mode is active, return simulated key-down/key-up transitions.
-
-**Why this over keybd_event/SendInput:**
-- Works when WA.exe is minimized (no window focus required)
-- Intercepts at the API level regardless of how WA reads the result
-- No timing races with the game's message pump
-- Existing MinHook infrastructure
-
-### Key simulation
-
-GetAsyncKeyState returns a SHORT:
-- Bit 15 (0x8000) = key currently down
-- Bit 0 (0x0001) = key pressed since last call
-
-Toggle between calls:
-- Even: `0x8001` (down + transition)
-- Odd: `0x0000` (up, no transition)
-
-All other virtual keys pass through to the real function.
-
-### Activation
-
-1. DLL loads, detects `OPENWA_REPLAY_TEST=1`
-2. Spawns thread that waits ~3 seconds for game to reach gameplay
-3. Sets atomic flag to enable fast-forward
-4. GetAsyncKeyState hook checks flag on each VK_SPACE query
-
-### Validation integration
-
-Current: thread waits 5s -> validate -> ExitProcess.
-
-New: thread waits 3s -> enable fast-forward -> wait up to 120s for natural exit. Validation dumps trigger on a timeout (60s) as a safety net. Normally the game exits on its own when the replay finishes.
-
-### Script changes
-
-`replay-test.ps1`: add timeout to `WaitForExit()` (120s). Remove the implicit 5s assumption from comments.
-
-## Future: Turn-Start Hook
-
-Hooking the function that runs at each turn start would enable per-turn assertions and proper unit-test-style validation during replay playback. This is out of scope for this design but is the natural next step.
-
-## Files
-
-- `crates/openwa-dll/src/replacements/input.rs` (new) — GetAsyncKeyState hook
-- `crates/openwa-dll/src/validation/mod.rs` — Update auto-capture timeout
-- `crates/openwa-dll/src/lib.rs` — Register input module
-- `replay-test.ps1` — Add WaitForExit timeout

docs/plans/2026-03-19-init-game-state-design.md

@@ -1,100 +0,0 @@
-# DDGame__InitGameState Porting Plan
-
-## Overview
-
-Port `DDGame__InitGameState` (0x526500, 1226 decompiled lines) using the same
-incremental strategy as the DDGame constructor: port sub-functions individually
-as hooks, test each group, then eventually combine into a full Rust replacement.
-
-InitGameState is called once after the DDGame constructor. It creates all runtime
-game objects: HUD panel, weapon table, team arena, turn game task, camera state,
-scoring, alliance data, and more.
-
-## Structure
-
-InitGameState is actually two merged functions:
-- Wrapper (0x526500-0x52657B): SEH setup, copies 2 scheme bytes, calls FUN_541620
-- Falls through into CTaskGameState__vmethod_7 (0x52657C, ~2000 instructions)
-
-`param_1` = DDGameWrapper. `param_1+0x488` = DDGame. `DDGame+0x24` = GameInfo/scheme.
-
-## Phase 1: Port usercall functions to pure Rust
-
-All 7 usercall functions are small (<80 lines), mostly pure field writes, and
-have zero or minimal dependencies. Porting them eliminates naked asm bridges.
-
-### Group A — Zero-dependency functions (port first, test)
-
-| Function | Address | Lines | What it does |
-|---|---|---|---|
-| FUN_541620 | 0x541620 | ~15 | Sprite/gfx table init (fastcall ECX,EDX, loop + 3 fields) |
-| FUN_541060 | 0x541060 | ~15 | Buffer alloc constructor (EAX=size, ESI=output, calls wa_malloc) |
-
-### Group B — Team/scoring init (port, test)
-
-| Function | Address | Lines | What it does |
-|---|---|---|---|
-| InitTeamScoring | 0x528510 | ~65 | Pure field writes to CGameTask scoring arrays, zero calls |
-| InitAllianceData | 0x5262D0 | ~80 | Alliance bitmask computation, pure field writes + bitmath |
-
-### Group C — Turn state + weapon availability (port, test)
-
-| Function | Address | Lines | What it does |
-|---|---|---|---|
-| InitTurnState | 0x528690 | ~80 | DDGame turn fields + camera center. Calls FUN_524700 (bridge) |
-| FUN_53FFC0 | 0x53FFC0 | ~50 | Weapon availability switch (port FUN_565960 ~20 lines too) |
-| FUN_528480 | 0x528480 | ~20 | Post-init: scheme flag + 1 vtable dispatch |
-
-### Bridge (defer porting)
-
-| Function | Address | Lines | Why |
-|---|---|---|---|
-| FUN_524700 | 0x524700 | ~600 | Scheme-version feature flags. Pure computation but massive. |
-
-## Phase 2: Hook stdcall constructors individually
-
-All verified via RET instruction. Hook each, test in isolation.
-
-### Group D — Core game objects
-
-| Function | Address | RET | Params | Creates |
-|---|---|---|---|---|
-| HudPanel__Constructor | 0x524070 | 0x4 | 1 | DDGame+0x534 |
-| InitWeaponTable | 0x53CAB0 | 0x4 | 1 | Weapon table setup |
-| InitTeamsFromSetup | 0x5220B0 | 0x8 | 2 | DDGame+0x4628 team arena |
-
-### Group E — Task objects
-
-| Function | Address | RET | Params | Creates |
-|---|---|---|---|---|
-| TeamManager__Constructor | 0x563D40 | 0x8 | 2 | DDGame+0x530 |
-| CTaskTurnGame__Constructor | 0x55B280 | 0x8 | 2 | Turn game task |
-| CTaskGameState__Constructor | 0x532330 | 0x8 | 2 | Game state task |
-
-### Group F — Display objects
-
-| Function | Address | RET | Params | Creates |
-|---|---|---|---|---|
-| DisplayGfx__Constructor | 0x563FC0 | 0x14 | 5 | Full display gfx |
-| DDDisplay__ConstructTextbox | 0x4FAF00 | 0xC | 3 | Textbox |
-| FUN_567770 | 0x567770 | 0x4 | 1 | Final conditional display ctor |
-
-### Group G — Buffer/stream objects
-
-| Function | Address | RET | Params | Creates |
-|---|---|---|---|---|
-| FUN_545FD0 | 0x545FD0 | 0xC | 3 | Buffer object (called twice) |
-| FUN_4FB490 | 0x4FB490 | 0x4 | 1 | GameStateStream sub-init |
-
-## Testing Strategy
-
-- Run headful + headless replay tests after each group (A, B, C, D, E, F, G)
-- Headless MUST pass (deterministic output match) before proceeding
-- Headful validates no crashes, correct rendering, game completion
-- Name all functions in Ghidra as they're analyzed
-
-## Naming Convention
-
-Functions ported to Rust: `init_sprite_table`, `init_team_scoring`, etc.
-Functions bridged via FFI: `wa_init_feature_flags` (for FUN_524700)
-Ghidra labels: `CGameTask__InitTeamScoring`, `CGameTask__InitAllianceData`, etc.

docs/re-notes/README.md

@@ -0,0 +1 @@
+These are notes and documentation generated by Claude during the development of OpenWA. They are already outdated and inaccurate, but might contain something of value.

docs/superpowers/plans/2026-03-16-ddgame-constructor.md

@@ -1,553 +0,0 @@
-# DDGame Constructor Port — Implementation Plan
-
-> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Replace DDGame__Constructor (0x56E220) with a Rust `DDGame::new()` function that creates the 0x98B8-byte game state object field by field, bridging WA sub-calls initially.
-
-**Architecture:** The constructor allocates DDGame via `wa_malloc(0x98B8)`, zero-fills it, then runs ~35 initialization steps covering param storage, sub-object creation (GfxHandler, PCLandscape, SpriteRegions, CoordList, DisplayGfx objects), resource loading (sprites, gradients, WAVs), and configuration. We'll implement `DDGame::new()` in openwa-core, call it from `construct_ddgame_wrapper` in game_session.rs, and bridge complex sub-calls via typed function pointers.
-
-**Tech Stack:** Rust (i686-pc-windows-msvc), `wa_alloc` for WA heap, `core::ptr` for field writes, Ghidra MCP for decompilation reference.
-
----
-
-## Chunk 1: Foundation — DDGame::new() with Parameter Storage
-
-### Task 1: Add Missing Sub-Function Addresses
-
-**Files:**
-- Modify: `crates/openwa-core/src/address.rs`
-
-- [ ] **Step 1: Add addresses for all sub-functions called by the constructor**
-
-Add to `address.rs` in the appropriate section:
-
-```rust
-// --- DDGame Constructor sub-calls ---
-
-/// DDGame__InitFields (0x526120): usercall(EDI=ddgame), plain RET.
-/// Zeroes stride-0x194 table, coordinate entries, calls FUN_00526080.
-pub const DDGAME_INIT_FIELDS: u32 = 0x0052_6120;  // already exists
-
-/// FUN_00526080: usercall(ESI=ddgame), plain RET.
-/// Initializes RenderQueue index arrays at +0xC4..+0x4A2.
-pub const DDGAME_INIT_RENDER_INDICES: u32 = 0x0052_6080;
-
-/// FUN_00525BE0: stdcall(ddgame_wrapper), plain RET.
-/// Sets DDGame+0x7E2E/0x7E2F/0x7E3F flags based on game version/mode.
-pub const DDGAME_INIT_VERSION_FLAGS: u32 = 0x0052_5BE0;
-
-/// FUN_005411A0: unknown convention, called at start.
-/// Initializes some CRT / MFC state.
-pub const FUN_5411A0: u32 = 0x0054_11A0;
-
-/// GfxHandler constructor pattern: alloc 0x19C, memset 0, set vtable.
-/// vtable at GfxHandler__vtable global.
-pub const GFX_HANDLER_VTABLE: u32 = 0x0066_4308; // verify in Ghidra
-
-/// GfxHandler__LoadDir (called after fopen).
-pub const GFX_HANDLER_LOAD_DIR: u32 = 0x0057_0B50; // verify
-
-/// FUN_00570A90: called before display palette setup (non-headless).
-pub const FUN_570A90: u32 = 0x0057_0A90;
-
-/// FUN_00570E20: called after GfxHandler init.
-pub const FUN_570E20: u32 = 0x0057_0E20;
-
-/// FUN_00570F30: called before DSSound_LoadEffectWAVs.
-pub const FUN_570F30: u32 = 0x0057_0F30;
-
-/// PCLandscape__Constructor (0xB44 bytes).
-pub const PC_LANDSCAPE_CONSTRUCTOR: u32 = 0x0050_56F0; // verify
-
-/// SpriteRegion__Constructor (0x9C bytes).
-pub const SPRITE_REGION_CONSTRUCTOR: u32 = 0x0057_DB20;
-
-/// FUN_005717A0: weapon sprite loading.
-pub const LOAD_WEAPON_SPRITES: u32 = 0x0057_17A0;
-
-/// HUD_LoadWeaponSprites_Maybe.
-pub const HUD_LOAD_WEAPON_SPRITES: u32 = 0x0052_4070; // verify address
-
-/// FUN_004F6300: creates some graphics object, returns ptr or null.
-pub const FUN_4F6300: u32 = 0x004F_6300;
-
-/// FUN_004F6370: initializes TaskStateMachine-like object.
-pub const FUN_4F6370: u32 = 0x004F_6370;
-
-/// FUN_0056A830: called for non-headless display finalization.
-pub const FUN_56A830: u32 = 0x0056_A830;
-
-/// DSSound_LoadEffectWAVs (loads all sound effect WAV files).
-pub const DSSOUND_LOAD_EFFECT_WAVS: u32 = 0x0057_1530; // verify
-
-/// DSSound_LoadAllSpeechBanks.
-pub const DSSOUND_LOAD_ALL_SPEECH_BANKS: u32 = 0x0057_1A70;
-
-/// g_GameInfo global (0x7749A0).
-pub const G_GAME_INFO: u32 = 0x0077_49A0;
-```
-
-- [ ] **Step 2: Verify addresses in Ghidra and label unnamed functions**
-
-Use Ghidra MCP `batch_create_labels` / `batch_rename_function_components` for all newly identified sub-functions. Cross-reference with the decompile to confirm each address.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add crates/openwa-core/src/address.rs
-git commit -m "feat: add DDGame constructor sub-function addresses"
-```
-
-### Task 2: Add DDGameWrapper Fields Used by Constructor
-
-**Files:**
-- Modify: `crates/openwa-core/src/engine/ddgame_wrapper.rs`
-
-The constructor accesses DDGameWrapper at offsets +0x488 (ddgame ptr), +0x48C, +0x490, +0x4C0, +0x4C4, +0x4C8, +0x4CC, +0x4D0, +0x4D8, +0x4DC, +0x4E0. Many of these are sub-object pointers set during the DDGame construction.
-
-- [ ] **Step 1: Read current DDGameWrapper struct**
-
-Read `crates/openwa-core/src/engine/ddgame_wrapper.rs` and identify which offsets are already mapped.
-
-- [ ] **Step 2: Add missing DDGameWrapper fields**
-
-Add fields for offsets used by the constructor that aren't yet mapped:
-- +0x48C: Network-related object pointer (0x2C bytes, conditional)
-- +0x490: Network flag byte
-- +0x4C0: Primary GfxHandler pointer (0x19C bytes)
-- +0x4C4: Secondary GfxHandler pointer (0x19C bytes, conditional)
-- +0x4C8: GfxHandler index/flag (uint)
-- +0x4CC: PCLandscape pointer (0xB44 bytes)
-- +0x4D0: Display pointer (copied from DDGame display)
-- +0x4D8: Unknown (set to 0)
-- +0x4DC: Calculated height value
-- +0x4E0: Set to -100 (0xFFFFFF9C)
-
-- [ ] **Step 3: Verify with runtime dump**
-
-Use the F7/validator debug tools to confirm field values at these offsets match expectations.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add crates/openwa-core/src/engine/ddgame_wrapper.rs
-git commit -m "feat: add DDGameWrapper fields used by DDGame constructor"
-```
-
-### Task 3: Implement DDGame::new() — Phase 1 (Trivial Inits + Param Storage)
-
-**Files:**
-- Modify: `crates/openwa-core/src/engine/ddgame.rs`
-
-This is the core of the port. Phase 1 covers: allocation, zero-fill, parameter storage, and simple field writes. Complex sub-calls are bridged.
-
-- [ ] **Step 1: Create DDGame::new() skeleton**
-
-```rust
-/// Construct a new DDGame, matching DDGame__Constructor (0x56E220).
-///
-/// # Safety
-/// All pointer params must be valid WA objects. `wrapper` must be
-/// a valid DDGameWrapper with fields initialized up to this point.
-pub unsafe fn new(
-    wrapper: *mut DDGameWrapper,
-    keyboard: *mut DDKeyboard,
-    display: *mut DDDisplay,
-    sound: *mut DSSound,
-    palette: *mut Palette,
-    music: *mut Music,
-    param7: *mut u8,      // timer? 0x1F4 observed
-    net_game: *mut u8,    // from GameSession
-    game_info: *mut GameInfo,
-    network_ecx: u32,     // implicit ECX from caller
-) -> *mut DDGame {
-    // 1. Allocate and zero-fill
-    let ddgame = wa_malloc(0x98B8) as *mut DDGame;
-    if ddgame.is_null() {
-        return core::ptr::null_mut();
-    }
-    core::ptr::write_bytes(ddgame as *mut u8, 0, 0x98B8);
-
-    // 2. Call InitFields (usercall EDI=ddgame)
-    call_init_fields(ddgame);
-
-    // 3. Store at DDGameWrapper+0x488
-    (*wrapper).ddgame = ddgame;
-
-    // 4. Store constructor parameters
-    (*ddgame).display = display;
-    (*ddgame).sound = sound;
-    (*ddgame).keyboard = keyboard;
-    (*ddgame).palette = palette;
-    (*ddgame).music = music;
-    (*ddgame)._param_018 = param7;
-    (*ddgame)._caller = network_ecx as *mut u8;
-    (*ddgame).game_info = game_info;
-    (*ddgame)._param_028 = net_game;
-
-    // 5. Set global
-    *(rb(va::G_GAME_INFO) as *mut *mut GameInfo) = game_info;
-
-    // 6. Sound available + always-1 flags
-    (*ddgame).sound_available =
-        if (*(game_info as *const u8).add(0xF914) as *const i32).read() == 0 { 1 } else { 0 };
-    (*ddgame)._field_7efc = 1;
-
-    // ... (Phase 2 sub-calls added incrementally)
-
-    ddgame
-}
-```
-
-- [ ] **Step 2: Implement bridge for DDGame__InitFields**
-
-InitFields is `usercall(EDI=ddgame)`, plain RET. Create a naked bridge:
-
-```rust
-/// Bridge to DDGame__InitFields (0x526120).
-/// Convention: usercall(EDI=ddgame), plain RET.
-#[unsafe(naked)]
-unsafe extern "C" fn call_init_fields(_ddgame: *mut DDGame) {
-    core::arch::naked_asm!(
-        "pushl %edi",
-        "movl 8(%esp), %edi",     // EDI = ddgame
-        "calll *({addr})",
-        "popl %edi",
-        "retl",
-        addr = sym INIT_FIELDS_ADDR,
-        options(att_syntax),
-    );
-}
-static mut INIT_FIELDS_ADDR: u32 = 0;
-```
-
-- [ ] **Step 3: Implement bridge for FUN_00525BE0 (version flags)**
-
-This is `stdcall(ddgame_wrapper)` — simple transmute call:
-
-```rust
-/// Bridge to FUN_00525BE0 — sets DDGame+0x7E2E/0x7E2F/0x7E3F flags.
-unsafe fn call_init_version_flags(wrapper: *mut DDGameWrapper) {
-    let f: unsafe extern "stdcall" fn(*mut DDGameWrapper) =
-        core::mem::transmute(rb(va::DDGAME_INIT_VERSION_FLAGS) as usize);
-    f(wrapper);
-}
-```
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add crates/openwa-core/src/engine/ddgame.rs
-git commit -m "feat: DDGame::new() phase 1 — allocation, params, trivial inits"
-```
-
-### Task 4: Wire DDGame::new() into game_session.rs
-
-**Files:**
-- Modify: `crates/openwa-dll/src/replacements/game_session.rs`
-
-- [ ] **Step 1: Replace ddgame_constructor_call with DDGame::new()**
-
-In `construct_ddgame_wrapper`, replace:
-```rust
-DDGAME_CTOR_ECX = input_ctrl as u32;
-ddgame_constructor_call(
-    this, display, sound, keyboard, palette, streaming_audio,
-    timer_obj, net_game, game_info,
-);
-```
-
-With:
-```rust
-DDGame::new(
-    this, keyboard, display, sound, palette, streaming_audio as *mut Music,
-    timer_obj, net_game, game_info,
-    input_ctrl as u32,
-);
-```
-
-- [ ] **Step 2: Remove the naked ddgame_constructor_call bridge and DDGAME_CTOR_ECX/DDGAME_CTOR_ADDR statics**
-
-These are no longer needed. Clean up dead code.
-
-- [ ] **Step 3: Trap DDGame__Constructor**
-
-Add to `game_session::install()`:
-```rust
-hook::install_trap!("DDGame__Constructor", va::CONSTRUCT_DD_GAME);
-```
-
-- [ ] **Step 4: Build and test**
-
-Run: `cargo build --target i686-pc-windows-msvc -p openwa-dll --release`
-
-This will fail at runtime because DDGame::new() doesn't yet call all the sub-constructors. That's expected — the next tasks add them incrementally.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add crates/openwa-dll/src/replacements/game_session.rs
-git commit -m "refactor: wire DDGame::new() into game_session, trap original"
-```
-
----
-
-## Chunk 2: Sub-Object Creation Bridges
-
-### Task 5: Network Object Init (DDGameWrapper+0x48C)
-
-**Files:**
-- Modify: `crates/openwa-core/src/engine/ddgame.rs`
-
-- [ ] **Step 1: Add conditional network object creation**
-
-Condition: `game_info+0xD778 == -2`. Alloc 0x2C bytes, zero-fill, store DDGame ptr at [0], copy 2 config bytes from game_info. If `network_ecx != 0`, store at `network_ecx+0x18`.
-
-```rust
-// Conditional network object (game_info+0xD778 == -2)
-let d778 = *((game_info as *const u8).add(0xD778) as *const i32);
-if d778 == -2 {
-    let net_obj = wa_malloc(0x2C) as *mut u8;
-    core::ptr::write_bytes(net_obj, 0, 0x2C);
-    *(net_obj as *mut *mut DDGame) = ddgame;
-    // piVar3[1..3] = 0, piVar3[6] = 0 (already zero from memset)
-    *net_obj.add(0x28) = *((*(ddgame as *const u8).add(0x24) as *const *const u8)
-        .read().add(0xD944));
-    *net_obj.add(0x29) = *((*(ddgame as *const u8).add(0x24) as *const *const u8)
-        .read().add(0xD946));
-    // Store at DDGameWrapper+0x48C
-    *(wrapper as *mut u8).add(0x48C).cast::<*mut u8>().write(net_obj);
-    if network_ecx != 0 {
-        *((network_ecx as *mut u8).add(0x18) as *mut *mut u8) = net_obj;
-    }
-}
-```
-
-- [ ] **Step 2: Test with replay test**
-
-Run headful replay test — game should not crash during init.
-
-- [ ] **Step 3: Commit**
-
-### Task 6: GfxHandler Init + Gfx.dir Loading
-
-**Files:**
-- Modify: `crates/openwa-core/src/engine/ddgame.rs`
-
-This is a complex section that opens Gfx.dir files, tries multiple paths, and conditionally creates a second GfxHandler. For now, bridge entirely.
-
-- [ ] **Step 1: Create bridge for GfxHandler creation and Gfx.dir loading**
-
-Extract the entire GfxHandler init section (lines 151-250 of decompile) into a single bridged call. This section operates on DDGameWrapper fields (+0x4C0, +0x4C4, +0x4C8), not DDGame directly, so we can bridge it as one unit.
-
-Option A: Call the original constructor section via a calculated offset.
-Option B: Reimplement the file-open logic in Rust (fopen/GfxHandler__LoadDir are simple).
-
-Start with Option A (bridge) and convert later.
-
-- [ ] **Step 2: Test**
-- [ ] **Step 3: Commit**
-
-### Task 7: Audio Init (Sound Effects + Speech + ActiveSoundTable)
-
-**Files:**
-- Modify: `crates/openwa-core/src/engine/ddgame.rs`
-
-- [ ] **Step 1: Add audio initialization**
-
-Condition: `game_info+0xF914 == 0` (not headless) AND `ddgame.sound != null`.
-
-```rust
-if *((game_info as *const u8).add(0xF914) as *const i32) == 0 {
-    call_fun_570f30();  // bridge
-    if !(*ddgame).sound.is_null() {
-        call_dssound_load_effect_wavs();   // bridge
-        call_dssound_load_all_speech_banks();  // bridge
-        // Allocate ActiveSoundTable (0x608 bytes)
-        let ast = wa_malloc(0x608) as *mut ActiveSoundTable;
-        (*ast).ddgame = ddgame;
-        (*ast).counter = 0;
-        core::ptr::write_bytes(ast as *mut u8, 0, 0x600);  // zero entries only
-        (*ddgame).active_sounds = ast;
-    }
-}
-```
-
-Note: DSSound_LoadEffectWAVs and DSSound_LoadAllSpeechBanks are already known addresses. The ActiveSoundTable allocation can be done in pure Rust since we have the struct.
-
-- [ ] **Step 2: Test with headful replay**
-- [ ] **Step 3: Commit**
-
-### Task 8: PCLandscape + TaskStateMachine + SpriteRegions
-
-**Files:**
-- Modify: `crates/openwa-core/src/engine/ddgame.rs`
-
-- [ ] **Step 1: Bridge PCLandscape__Constructor**
-
-Alloc 0xB44, zero-fill, call PCLandscape constructor (complex, many params). Store at DDGameWrapper+0x4CC and DDGame+0x020.
-
-- [ ] **Step 2: Bridge TaskStateMachine creation**
-
-Alloc 0x2C, zero-fill, call FUN_004F6370 for init, set vtable. Store at DDGame+0x380.
-
-- [ ] **Step 3: Bridge 8× SpriteRegion creation**
-
-Each: alloc 0x9C, zero-fill, call SpriteRegion__Constructor with (param1, param2). Store at DDGame+0x46C..0x488 (note: these are offsets 0x46C, 0x470, 0x474, 0x478, 0x47C, 0x480, 0x484, 0x488 — the 8 sprite_regions).
-
-SpriteRegion params (from decompile):
-| DDGame offset | param1 | param2 |
-|---------------|--------|--------|
-| +0x474 | 0x24 | 0x2E |
-| +0x46C | 0x07 | 0x2D |
-| +0x470 | 0x0A | 0x0D |
-| +0x478 | 0x20 | 0x00 |
-| +0x47C | 0x00 | 0x00 |
-| +0x484 | 0x09 | 0x173 |
-| +0x488 | 0x07 | 0x1E5 |
-| +0x480 | 0x07 | 0x2D |
-
-- [ ] **Step 4: Set landscape-derived value at +0x468**
-
-```rust
-// (*ddgame).landscape_val = landscape.vtable[0xB].call()
-let landscape = (*ddgame).landscape;
-let vtable = *(landscape as *const *const u32);
-let get_val: unsafe extern "thiscall" fn(*mut u8) -> u32 =
-    core::mem::transmute(*vtable.add(0xB));
-(*ddgame)._landscape_val = get_val(landscape as *mut u8) as *mut u8;
-```
-
-- [ ] **Step 5: Test**
-- [ ] **Step 6: Commit**
-
-### Task 9: Arrow Sprites + Collision Regions (32 iterations)
-
-**Files:**
-- Modify: `crates/openwa-core/src/engine/ddgame.rs`
-
-- [ ] **Step 1: Bridge arrow sprite loading loop**
-
-The loop loads 32 `arrow##.img` files, creates DisplayGfx objects, and creates SpriteRegion collision regions. This is complex graphics code — bridge the entire loop initially.
-
-Create a helper that encapsulates the loop body using GfxHandler vtable calls.
-
-- [ ] **Step 2: Test**
-- [ ] **Step 3: Commit**
-
-### Task 10: CoordList, DisplayGfx, Resource Loading
-
-**Files:**
-- Modify: `crates/openwa-core/src/engine/ddgame.rs`
-
-- [ ] **Step 1: Create CoordList in Rust**
-
-Pure Rust — this is simple allocation:
-```rust
-// CoordList: 3 u32s (count, capacity, data_ptr) + 0x12C0 buffer
-let coord_list = wa_malloc(12) as *mut u32;
-*coord_list = 0;            // count
-*coord_list.add(1) = 600;   // capacity
-let coord_data = wa_malloc(0x12C0) as *mut u8;
-core::ptr::write_bytes(coord_data, 0, 0x12C0);
-*coord_list.add(2) = coord_data as u32;
-(*ddgame).coord_list = coord_list as *mut u8;
-```
-
-- [ ] **Step 2: Bridge coordinate list population from landscape**
-
-The loop reads from landscape data and inserts unique entries.
-
-- [ ] **Step 3: Bridge DisplayGfx at +0x138**
-
-Alloc 0x2C, init via FUN_004F6370, set vtable to DisplayGfx__vtable.
-
-- [ ] **Step 4: Bridge weapon sprite loading (FUN_005717A0 ×2)**
-- [ ] **Step 5: Bridge gradient/layer/fill image loading**
-- [ ] **Step 6: Bridge HUD weapon sprite loading**
-- [ ] **Step 7: Set fill pixel at +0x7338**
-- [ ] **Step 8: Bridge display finalization calls**
-- [ ] **Step 9: Test with full headful replay**
-- [ ] **Step 10: Commit**
-
----
-
-## Chunk 3: Integration and Verification
-
-### Task 11: DDGameWrapper Field Updates
-
-**Files:**
-- Modify: `crates/openwa-core/src/engine/ddgame.rs`
-
-- [ ] **Step 1: Add DDGameWrapper field writes that happen during the constructor**
-
-The original constructor writes to many DDGameWrapper fields:
-- +0x4D8 = 0
-- +0x4DC = calculated from param8+0x44C: `byte_val * 0x38 + 0x7E + 0x2AD`
-- +0x4E0 = -100 (0xFFFFFF9C)
-- +0x6EE8 = 0 (speech name count)
-
-- [ ] **Step 2: Commit**
-
-### Task 12: Full Integration Test
-
-- [ ] **Step 1: Run headful replay test**
-
-```bash
-powershell -ExecutionPolicy Bypass -File replay-test.ps1
-```
-
-Expected: Game plays through replay without crashes. Verify audio, visuals, and turn transitions.
-
-- [ ] **Step 2: Run headless replay test**
-
-```bash
-powershell -ExecutionPolicy Bypass -File replay-test.ps1 -Headless
-```
-
-Expected: Byte-identical log output compared to baseline.
-
-- [ ] **Step 3: Manual gameplay test**
-
-Start a local match, play 2-3 turns. Verify:
-- Worm sprites render correctly
-- Weapons fire and explode
-- Sound effects play
-- Turn order widget shows
-- Camera follows active worm
-
-- [ ] **Step 4: Update Ghidra labels for all newly identified functions**
-
-Use `batch_create_labels` for any remaining unnamed functions.
-
-- [ ] **Step 5: Final commit**
-
-```bash
-git add -A
-git commit -m "feat: replace DDGame__Constructor with Rust DDGame::new()"
-```
-
----
-
-## Notes
-
-### Bridging Strategy
-
-For sub-calls that use unusual calling conventions (usercall with EDI/ESI), use `#[unsafe(naked)]` bridge functions matching the pattern in `game_session.rs`. For plain stdcall/thiscall sub-calls, use `core::mem::transmute` to typed function pointers.
-
-### Order Matters
-
-The init steps MUST execute in the exact order from the decompile. Some sub-calls depend on fields set by earlier steps (e.g., PCLandscape reads game_info from DDGame+0x24, GfxHandler is used by arrow sprite loading).
-
-### Testing Cadence
-
-After each Task, run a headful replay test. If anything crashes, check ERRORLOG.TXT and compare against the decompile to find which field or sub-call was missed.
-
-### Future: Bridge Elimination (Phase 3)
-
-Once all bridges are working, each can be independently converted to pure Rust:
-1. InitFields → direct field writes (already have the offset list)
-2. FUN_00526080 → Rust loop for render index arrays
-3. ActiveSoundTable → already done in Task 7
-4. CoordList → already done in Task 10
-5. SpriteRegion / PCLandscape / GfxHandler → larger projects, future plans

docs/superpowers/plans/2026-03-19-replay-loader.md

@@ -1,980 +0,0 @@
-# ReplayLoader Port Implementation Plan
-
-> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development
-> (if subagents available) or superpowers:executing-plans to implement this plan.
-> Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Port ReplayLoader (0x462DF0) and ParseReplayPosition (0x4E3490) from
-WA.exe to Rust, enabling .WAgame file parsing in Rust code.
-
-**Architecture:** Hook-and-replace strategy. ReplayLoader is stdcall(2 params),
-~1800 lines. We decompose it into: (1) a ReplayStream cursor abstraction porting
-the 6 usercall stream helpers, (2) ParseReplayPosition as a standalone pure
-function, (3) the main ReplayLoader function replacing incrementally — header
-first, then payload parsing, delegating unimplemented modes to the original via
-trampoline.
-
-**Tech Stack:** Rust (i686-pc-windows-msvc), MinHook, openwa-core types, WA.exe
-FFI bridges for complex sub-functions.
-
-**Spec:** `docs/superpowers/specs/2026-03-19-replay-loader-design.md`
-
----
-
-## File Structure
-
-| File | Action | Responsibility |
-|------|--------|---------------|
-| `crates/openwa-core/src/engine/replay.rs` | Create | ReplayStream struct, ParseReplayPosition, replay data types |
-| `crates/openwa-core/src/engine/mod.rs` | Modify | Add `pub mod replay` |
-| `crates/openwa-core/src/address.rs` | Modify | Add replay global addresses |
-| `crates/openwa-dll/src/replacements/replay.rs` | Create | Hook installation, ReplayLoader replacement |
-| `crates/openwa-dll/src/replacements/mod.rs` | Modify | Add `mod replay` + `replay::install()?` |
-
----
-
-## Task 1: Add Replay Addresses to address.rs
-
-**Files:**
-- Modify: `crates/openwa-core/src/address.rs`
-
-- [ ] **Step 1: Add replay global addresses**
-
-In the `va` module (top-level function addresses section), the addresses
-`REPLAY_LOADER` (0x462DF0) and `PARSE_REPLAY_POSITION` (0x4E3490) already exist.
-Add the remaining replay-related globals and helper function addresses:
-
-```rust
-// In the va module, near the existing REPLAY_LOADER entries:
-
-/// Stream helper: read length-prefixed string. usercall(EDI=ctx) + stdcall(dest, max_len). RET 0x8.
-pub const REPLAY_READ_BYTES: u32 = 0x0046_1340;
-/// Stream helper: read byte with range validation. usercall(EAX=ctx) + stdcall(dest, min, max). RET 0xC.
-pub const REPLAY_READ_BYTE_VALIDATED: u32 = 0x0046_14D0;
-/// Stream helper: read byte with signed range validation. usercall(EAX=ctx) + stdcall(dest, min, max). RET 0xC.
-pub const REPLAY_READ_BYTE_RANGE: u32 = 0x0046_1540;
-/// Stream helper: read u16 with range validation. usercall(EAX=ctx) + stdcall(dest, min, max). RET 0xC.
-pub const REPLAY_READ_U16_VALIDATED: u32 = 0x0046_15B0;
-/// Stream helper: read worm name (0x11 bytes or length-prefixed). usercall(EAX=ctx) + thiscall(this, flag). RET 0x4.
-pub const REPLAY_READ_WORM_NAME: u32 = 0x0046_1620;
-/// Validate team type byte range. fastcall(ECX=type). Plain RET.
-pub const REPLAY_VALIDATE_TEAM_TYPE: u32 = 0x0046_1690;
-/// Post-process team color assignments. stdcall(1 param). RET 0x4.
-pub const REPLAY_PROCESS_TEAM_COLORS: u32 = 0x0046_6460;
-/// Apply scheme default values. No params (uses globals). Plain RET.
-pub const REPLAY_PROCESS_SCHEME_DEFAULTS: u32 = 0x0046_70F0;
-/// Process replay feature flags. No params (uses globals). Plain RET.
-pub const REPLAY_PROCESS_FLAGS: u32 = 0x0046_7280;
-/// Register observer team entry. stdcall(1 param). RET 0x4.
-pub const REPLAY_REGISTER_OBSERVER: u32 = 0x0046_7BC0;
-/// Process alliance/team setup. No params (uses globals). Plain RET.
-pub const REPLAY_PROCESS_ALLIANCE: u32 = 0x0046_8890;
-/// Validate team configuration. stdcall(1 param).
-pub const REPLAY_VALIDATE_TEAM_SETUP: u32 = 0x0046_5E10;
-```
-
-Add replay-related global data addresses:
-
-```rust
-// In a globals section (or near existing DAT_ references):
-
-/// Global game state struct passed to ReplayLoader. Always 0x87D3F8.
-pub const G_REPLAY_STATE: u32 = 0x0087_D3F8;
-/// Team header data buffer (0x5728 bytes), cleared by ReplayLoader.
-pub const G_TEAM_HEADER_DATA: u32 = 0x0087_79E4;
-/// Secondary team/game data buffer (0xD9DC bytes).
-pub const G_TEAM_SECONDARY_DATA: u32 = 0x0087_D438;
-/// XOR'd game ID (payload ^ 0xEF5B5C49).
-pub const G_REPLAY_GAME_ID: u32 = 0x0088_AF50;
-/// Replay sub-format flag.
-pub const G_REPLAY_SUB_FORMAT: u32 = 0x0088_AF54;
-/// Game version ID from replay.
-pub const G_REPLAY_VERSION_ID: u32 = 0x0088_ABB0;
-/// Scheme present flag (1 = has scheme data).
-pub const G_REPLAY_SCHEME_PRESENT: u32 = 0x0088_AE0C;
-/// Scheme defaults buffer (0x6E bytes).
-pub const G_SCHEME_DEFAULTS_BUF: u32 = 0x0088_DC04;
-/// Version/ArtClass counter. ReplayLoader fails if > 0x33.
-pub const G_ARTCLASS_COUNTER: u32 = 0x0088_C790;
-/// Random seed global.
-pub const G_RANDOM_SEED: u32 = 0x0088_D0B4;
-/// Saved random seed.
-pub const G_SAVED_RANDOM_SEED: u32 = 0x0088_ABAC;
-/// Replay filename buffer.
-pub const G_REPLAY_FILENAME: u32 = 0x0088_AF58;
-```
-
-- [ ] **Step 2: Label all replay functions in Ghidra**
-
-Use `batch_rename_function_components` to name all replay-related functions:
-- `FUN_00461340` → `Replay__ReadPrefixedString`
-- `FUN_004614D0` → `Replay__ReadByteValidated`
-- `FUN_00461540` → `Replay__ReadByteRange`
-- `FUN_004615B0` → `Replay__ReadU16Validated`
-- `FUN_00461620` → `Replay__ReadWormName`
-- `FUN_00461690` → `Replay__ValidateTeamType`
-- `FUN_00466460` → `Replay__ProcessTeamColors`
-- `FUN_004670F0` → `Replay__ProcessSchemeDefaults`
-- `FUN_00467280` → `Replay__ProcessReplayFlags`
-- `FUN_00467BC0` → `Replay__RegisterObserver`
-- `FUN_00468890` → `Replay__ProcessAllianceData`
-- `FUN_00465E10` → `Replay__ValidateTeamSetup`
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add crates/openwa-core/src/address.rs
-git commit -m "feat: add replay system addresses for stream helpers and globals"
-```
-
----
-
-## Task 2: Create ReplayStream and Port Stream Helpers
-
-**Files:**
-- Create: `crates/openwa-core/src/engine/replay.rs`
-- Modify: `crates/openwa-core/src/engine/mod.rs`
-
-The 6 stream helper functions all operate on a shared 3-DWORD context:
-`[data_ptr: *const u8, total_size: u32, cursor: u32]`. Port them all as methods
-on a Rust `ReplayStream` struct.
-
-- [ ] **Step 1: Define ReplayStream struct and error type**
-
-```rust
-// crates/openwa-core/src/engine/replay.rs
-
-/// Error codes returned by ReplayLoader.
-#[repr(i32)]
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum ReplayError {
-    FileNotFound = -1,       // 0xFFFFFFFF
-    InvalidFormat = -2,      // 0xFFFFFFFE
-    VersionTooNew = -3,      // 0xFFFFFFFD
-    MallocFailure = -4,      // 0xFFFFFFFC
-    MapLoadFailure = -5,     // 0xFFFFFFFB
-    ArtClassLimit = -6,      // 0xFFFFFFFA
-    RepairWithTeams = -7,    // 0xFFFFFFF9
-    NoScheme = -9,           // 0xFFFFFFF7
-    SchemeSaveFailure = -10, // 0xFFFFFFF6
-}
-
-/// Replay file magic: "WA" in little-endian.
-pub const REPLAY_MAGIC: u16 = 0x4157;
-/// Maximum supported replay version.
-pub const REPLAY_MAX_VERSION: u16 = 0x13;
-/// XOR key for game ID integrity check.
-pub const REPLAY_XOR_KEY: u32 = 0xEF5B_5C49;
-
-/// Cursor over a replay payload byte buffer.
-///
-/// Mirrors the 3-DWORD stream context used by WA's stream helper functions:
-/// `[data_ptr, total_size, cursor_offset]`.
-pub struct ReplayStream<'a> {
-    data: &'a [u8],
-    cursor: usize,
-}
-
-impl<'a> ReplayStream<'a> {
-    pub fn new(data: &'a [u8]) -> Self {
-        Self { data, cursor: 0 }
-    }
-
-    pub fn remaining(&self) -> usize {
-        self.data.len().saturating_sub(self.cursor)
-    }
-
-    pub fn cursor(&self) -> usize {
-        self.cursor
-    }
-
-    /// Advance cursor by `n` bytes, returning the slice. Fails if not enough data.
-    fn advance(&mut self, n: usize) -> Result<&'a [u8], ReplayError> {
-        let end = self.cursor + n;
-        if end > self.data.len() {
-            return Err(ReplayError::InvalidFormat);
-        }
-        let slice = &self.data[self.cursor..end];
-        self.cursor = end;
-        Ok(slice)
-    }
-
-    /// Read a single byte. Port of parts of FUN_004614D0 / FUN_00461540.
-    pub fn read_u8(&mut self) -> Result<u8, ReplayError> {
-        let slice = self.advance(1)?;
-        Ok(slice[0])
-    }
-
-    /// Read a single byte, validating it is in [min, max]. Port of FUN_004614D0.
-    pub fn read_u8_validated(&mut self, min: u8, max: u8) -> Result<u8, ReplayError> {
-        let val = self.read_u8()?;
-        if val < min || val > max {
-            return Err(ReplayError::InvalidFormat);
-        }
-        Ok(val)
-    }
-
-    /// Read a little-endian u16. Part of FUN_004615B0.
-    pub fn read_u16(&mut self) -> Result<u16, ReplayError> {
-        let slice = self.advance(2)?;
-        Ok(u16::from_le_bytes([slice[0], slice[1]]))
-    }
-
-    /// Read a little-endian u16, validating range. Port of FUN_004615B0.
-    pub fn read_u16_validated(&mut self, min: u16, max: u16) -> Result<u16, ReplayError> {
-        let val = self.read_u16()?;
-        if val < min || val > max {
-            return Err(ReplayError::InvalidFormat);
-        }
-        Ok(val)
-    }
-
-    /// Read a little-endian u32.
-    pub fn read_u32(&mut self) -> Result<u32, ReplayError> {
-        let slice = self.advance(4)?;
-        Ok(u32::from_le_bytes([slice[0], slice[1], slice[2], slice[3]]))
-    }
-
-    /// Read a little-endian i32.
-    pub fn read_i32(&mut self) -> Result<i32, ReplayError> {
-        Ok(self.read_u32()? as i32)
-    }
-
-    /// Read `n` bytes into a destination buffer. Fails if not enough data.
-    pub fn read_into(&mut self, dest: &mut [u8]) -> Result<(), ReplayError> {
-        let slice = self.advance(dest.len())?;
-        dest.copy_from_slice(slice);
-        Ok(())
-    }
-
-    /// Read a length-prefixed string into buffer. Port of FUN_00461340.
-    ///
-    /// Reads 1 byte (length), then `length` bytes of string data, null-terminates.
-    /// `max_len` is the destination buffer capacity (excluding null).
-    pub fn read_prefixed_string(&mut self, dest: &mut [u8]) -> Result<usize, ReplayError> {
-        let len = self.read_u8()? as usize;
-        if len > dest.len().saturating_sub(1) {
-            return Err(ReplayError::InvalidFormat);
-        }
-        let slice = self.advance(len)?;
-        dest[..len].copy_from_slice(slice);
-        dest[len] = 0; // null-terminate
-        Ok(len)
-    }
-
-    /// Read a worm name: either 0x11 fixed bytes or length-prefixed. Port of FUN_00461620.
-    pub fn read_worm_name(&mut self, dest: &mut [u8; 0x11], use_fixed: bool) -> Result<(), ReplayError> {
-        if use_fixed {
-            let slice = self.advance(0x11)?;
-            dest.copy_from_slice(slice);
-        } else {
-            dest.fill(0);
-            self.read_prefixed_string(dest)?;
-        }
-        Ok(())
-    }
-
-    /// Skip `n` bytes.
-    pub fn skip(&mut self, n: usize) -> Result<(), ReplayError> {
-        self.advance(n)?;
-        Ok(())
-    }
-}
-
-/// Validate team type byte. Port of FUN_00461690.
-///
-/// Returns true if the team type value is in a valid range:
-/// - Non-negative: 0..12 (0 through 12 exclusive → type < 13)
-/// - Negative: -100 or absolute value < 100
-pub fn validate_team_type(team_type: i8) -> bool {
-    if team_type >= 0 {
-        team_type < 13
-    } else {
-        team_type == -100 || -(team_type as i32) <= 100
-    }
-}
-```
-
-- [ ] **Step 2: Add module declaration**
-
-In `crates/openwa-core/src/engine/mod.rs`, add:
-```rust
-pub mod replay;
-```
-
-And in the re-exports section if desired (or leave access via `engine::replay::`).
-
-- [ ] **Step 3: Write unit tests for ReplayStream**
-
-Add tests at the bottom of `replay.rs`:
-
-```rust
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn test_read_u8() {
-        let data = [0x42, 0xFF];
-        let mut s = ReplayStream::new(&data);
-        assert_eq!(s.read_u8().unwrap(), 0x42);
-        assert_eq!(s.read_u8().unwrap(), 0xFF);
-        assert!(s.read_u8().is_err());
-    }
-
-    #[test]
-    fn test_read_u8_validated() {
-        let data = [5, 0, 20];
-        let mut s = ReplayStream::new(&data);
-        assert_eq!(s.read_u8_validated(0, 10).unwrap(), 5);
-        assert_eq!(s.read_u8_validated(0, 10).unwrap(), 0);
-        assert!(s.read_u8_validated(0, 10).is_err()); // 20 > 10
-    }
-
-    #[test]
-    fn test_read_u16_le() {
-        let data = [0x57, 0x41]; // "WA" = 0x4157
-        let mut s = ReplayStream::new(&data);
-        assert_eq!(s.read_u16().unwrap(), 0x4157);
-    }
-
-    #[test]
-    fn test_read_u32_le() {
-        let data = [0x78, 0x56, 0x34, 0x12];
-        let mut s = ReplayStream::new(&data);
-        assert_eq!(s.read_u32().unwrap(), 0x12345678);
-    }
-
-    #[test]
-    fn test_read_prefixed_string() {
-        let data = [3, b'f', b'o', b'o', 0, b'x']; // len=3, "foo"
-        let mut s = ReplayStream::new(&data);
-        let mut buf = [0u8; 16];
-        let len = s.read_prefixed_string(&mut buf).unwrap();
-        assert_eq!(len, 3);
-        assert_eq!(&buf[..4], b"foo\0");
-        assert_eq!(s.cursor(), 4);
-    }
-
-    #[test]
-    fn test_read_worm_name_fixed() {
-        let mut data = [0u8; 0x11];
-        data[0] = b'W';
-        data[1] = b'o';
-        data[2] = b'r';
-        data[3] = b'm';
-        let mut s = ReplayStream::new(&data);
-        let mut name = [0u8; 0x11];
-        s.read_worm_name(&mut name, true).unwrap();
-        assert_eq!(name[0], b'W');
-        assert_eq!(s.cursor(), 0x11);
-    }
-
-    #[test]
-    fn test_validate_team_type() {
-        assert!(validate_team_type(0));
-        assert!(validate_team_type(12));
-        assert!(!validate_team_type(13));
-        assert!(validate_team_type(-1));
-        assert!(validate_team_type(-99));
-        assert!(validate_team_type(-100));
-        assert!(!validate_team_type(-101));
-    }
-}
-```
-
-- [ ] **Step 4: Run tests**
-
-```bash
-cargo test -p openwa-core -- replay
-```
-
-Expected: all tests pass.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add crates/openwa-core/src/engine/replay.rs crates/openwa-core/src/engine/mod.rs
-git commit -m "feat: add ReplayStream cursor and stream helper ports"
-```
-
----
-
-## Task 3: Port ParseReplayPosition
-
-**Files:**
-- Modify: `crates/openwa-core/src/engine/replay.rs`
-
-Port the `ParseReplayPosition` function (0x4E3490) as pure Rust. This converts
-time strings like `"1:30.25"` to frame counts at 50fps.
-
-- [ ] **Step 1: Write failing tests**
-
-Add to the test module in `replay.rs`:
-
-```rust
-#[test]
-fn test_parse_replay_position_seconds() {
-    assert_eq!(parse_replay_position(b"30\0"), 30 * 50);
-}
-
-#[test]
-fn test_parse_replay_position_minutes_seconds() {
-    assert_eq!(parse_replay_position(b"1:30\0"), (60 + 30) * 50);
-}
-
-#[test]
-fn test_parse_replay_position_with_frames() {
-    assert_eq!(parse_replay_position(b"1:30.5\0"), (60 + 30) * 50 + 25);
-}
-
-#[test]
-fn test_parse_replay_position_zero() {
-    assert_eq!(parse_replay_position(b"0\0"), 0);
-}
-
-#[test]
-fn test_parse_replay_position_invalid() {
-    assert_eq!(parse_replay_position(b"abc\0"), -1);
-}
-
-#[test]
-fn test_parse_replay_position_seconds_over_59() {
-    // After a colon, seconds > 59 is invalid
-    assert_eq!(parse_replay_position(b"1:60\0"), -1);
-}
-```
-
-- [ ] **Step 2: Run tests to verify they fail**
-
-```bash
-cargo test -p openwa-core -- parse_replay
-```
-
-Expected: FAIL (function not defined).
-
-- [ ] **Step 3: Implement parse_replay_position**
-
-Add to `replay.rs`:
-
-```rust
-/// Parse a replay position time string to frame count (50fps).
-///
-/// Format: `[MM:]SS[.FF]` where:
-/// - MM = minutes (multiplied by 60)
-/// - SS = seconds (max 59 after a colon)
-/// - FF = fractional (multiplied by 50 for frames, divided by power of 10)
-/// - Maximum 2 colons allowed
-///
-/// Returns frame count, or -1 on parse error.
-/// Port of WA.exe ParseReplayPosition (0x4E3490).
-pub fn parse_replay_position(input: &[u8]) -> i32 {
-    let mut colon_count: i32 = 0;
-    let mut accumulated: i32 = 0;
-    let mut current: i32 = 0;
-    let mut digit_count: i32 = 0;
-    let mut frac_divisor: i32 = 0; // 0 = integer part, >0 = fractional
-    let mut i = 0;
-
-    loop {
-        if i >= input.len() {
-            return -1;
-        }
-        let ch = input[i];
-
-        // Process digit runs
-        while i < input.len() && input[i] >= b'0' && input[i] <= b'9' {
-            let max_digits = if colon_count < 1 { 4 } else { 2 };
-            if digit_count >= max_digits {
-                return -1;
-            }
-            if frac_divisor == 0 {
-                current = current * 10 + (input[i] - b'0') as i32;
-                digit_count += 1;
-            } else {
-                let frac_value = ((input[i] - b'0') as i32 * 50) / frac_divisor;
-                frac_divisor *= 10;
-                accumulated += frac_value;
-            }
-            i += 1;
-        }
-
-        // Check delimiter
-        if i >= input.len() {
-            return -1;
-        }
-        let delim = input[i];
-
-        if delim != b':' && delim != b'.' && delim != 0 {
-            return -1;
-        }
-
-        if frac_divisor == 0 {
-            // Integer part complete
-            if colon_count > 0 && current > 59 {
-                return -1;
-            }
-            accumulated = current + accumulated * 60;
-            current = 0;
-            digit_count = 0;
-
-            if delim == b':' {
-                if colon_count >= 2 {
-                    return -1;
-                }
-                colon_count += 1;
-            } else {
-                // '.' or '\0' — convert seconds to frames
-                accumulated *= 50;
-            }
-        } else {
-            // Fractional part — ':' and '.' are invalid after '.'
-            if delim == b':' || delim == b'.' {
-                return -1;
-            }
-        }
-
-        if delim == 0 {
-            return accumulated;
-        }
-
-        if delim == b'.' {
-            frac_divisor = 10;
-        }
-
-        i += 1;
-    }
-}
-```
-
-**Note:** This must match the original's behavior exactly. The decompilation shows
-the algorithm accumulates digits, multiplies by 60 at each colon, and by 50 at
-the final conversion. Fractional part: each digit contributes `(digit * 50) / 10^position`.
-
-- [ ] **Step 4: Run tests**
-
-```bash
-cargo test -p openwa-core -- parse_replay
-```
-
-Expected: all pass. If any fail, adjust to match the original's exact logic.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add crates/openwa-core/src/engine/replay.rs
-git commit -m "feat: port ParseReplayPosition to Rust"
-```
-
----
-
-## Task 4: Hook Installation — Passthrough + ParseReplayPosition Replacement
-
-**Files:**
-- Create: `crates/openwa-dll/src/replacements/replay.rs`
-- Modify: `crates/openwa-dll/src/replacements/mod.rs`
-
-Install hooks for both functions. ReplayLoader starts as a passthrough (call
-original, log params). ParseReplayPosition is fully replaced.
-
-- [ ] **Step 1: Create replay.rs hook file**
-
-```rust
-// crates/openwa-dll/src/replacements/replay.rs
-
-use crate::hook;
-use crate::log_line;
-use openwa_core::address::va;
-use openwa_core::engine::replay;
-
-static mut REPLAY_LOADER_ORIG: *const () = core::ptr::null();
-static mut PARSE_POSITION_ORIG: *const () = core::ptr::null();
-
-// ReplayLoader: stdcall(param_1: u32, mode: i32) -> u32. RET 0x8.
-unsafe extern "stdcall" fn hook_replay_loader(param_1: u32, mode: i32) -> u32 {
-    let _ = log_line(&format!(
-        "[Replay] ReplayLoader param_1=0x{param_1:08X} mode={mode}"
-    ));
-    let orig: unsafe extern "stdcall" fn(u32, i32) -> u32 =
-        core::mem::transmute(REPLAY_LOADER_ORIG);
-    let result = orig(param_1, mode);
-    let _ = log_line(&format!(
-        "[Replay] ReplayLoader returned 0x{result:08X}"
-    ));
-    result
-}
-
-// ParseReplayPosition: stdcall(input: *const u8) -> i32. RET 0x4.
-unsafe extern "stdcall" fn hook_parse_replay_position(input: *const u8) -> i32 {
-    // Build a safe slice from the C string
-    let mut len = 0usize;
-    while *input.add(len) != 0 {
-        len += 1;
-        if len > 256 { break; } // safety limit
-    }
-    let slice = core::slice::from_raw_parts(input, len + 1); // include null
-    replay::parse_replay_position(slice)
-}
-
-pub fn install() -> Result<(), String> {
-    unsafe {
-        REPLAY_LOADER_ORIG = hook::install(
-            "ReplayLoader",
-            va::REPLAY_LOADER,
-            hook_replay_loader as *const (),
-        )? as *const ();
-
-        // ParseReplayPosition — full replacement, trampoline stored but unused
-        PARSE_POSITION_ORIG = hook::install(
-            "ParseReplayPosition",
-            va::PARSE_REPLAY_POSITION,
-            hook_parse_replay_position as *const (),
-        )? as *const ();
-    }
-    Ok(())
-}
-```
-
-- [ ] **Step 2: Register in mod.rs**
-
-In `crates/openwa-dll/src/replacements/mod.rs`, add:
-- `mod replay;` in the module list
-- `replay::install()?;` in `install_all()`
-
-- [ ] **Step 3: Build**
-
-```bash
-cargo build --release -p openwa-dll
-```
-
-Expected: compiles successfully.
-
-- [ ] **Step 4: Run headful replay test**
-
-```bash
-powershell -ExecutionPolicy Bypass -File replay-test.ps1
-```
-
-Expected: game loads replay, plays through. Check `testdata/logs/openwa_latest.log`
-for `[Replay] ReplayLoader` log lines confirming the hook fires and returns 0.
-
-- [ ] **Step 5: Run headless replay test**
-
-```bash
-powershell -ExecutionPolicy Bypass -File replay-test.ps1 -Headless
-```
-
-Expected: PASS (byte-identical output). This confirms ParseReplayPosition's Rust
-port produces the same frame numbers as the original.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add crates/openwa-dll/src/replacements/replay.rs crates/openwa-dll/src/replacements/mod.rs
-git commit -m "feat: hook ReplayLoader (passthrough) and replace ParseReplayPosition"
-```
-
----
-
-## Task 5: ReplayLoader Skeleton — Mode Routing + Header Parsing
-
-**Files:**
-- Modify: `crates/openwa-dll/src/replacements/replay.rs`
-- Modify: `crates/openwa-core/src/engine/replay.rs`
-
-Replace the passthrough with a mode-routing skeleton. Mode 1 (play) enters Rust;
-other modes delegate to original. Start with header parsing only.
-
-**Resource cleanup:** The original uses SEH try/catch to ensure fclose + free on
-error. Our Rust replacement must use a guard pattern:
-
-```rust
-/// RAII guard for file handle and malloc'd buffer cleanup.
-struct ReplayGuard {
-    file: *mut FILE,
-    payload: *mut u8,
-}
-impl Drop for ReplayGuard {
-    fn drop(&mut self) {
-        unsafe {
-            if !self.payload.is_null() {
-                free(self.payload as *mut core::ffi::c_void);
-            }
-            if !self.file.is_null() {
-                fclose(self.file);
-            }
-        }
-    }
-}
-```
-
-- [ ] **Step 1: Add CRT FFI declarations and ReplayGuard**
-
-Add to `replay.rs` (wormkit crate) or a shared location:
-- `extern "cdecl"` declarations for `fopen`, `fread`, `fclose`, `fseek`,
-  `malloc`, `free`, `memset`, `memcpy`, `SetCurrentDirectoryA`
-- `ReplayGuard` struct with `Drop` impl
-
-- [ ] **Step 2: Implement mode routing + header**
-
-```rust
-unsafe extern "stdcall" fn hook_replay_loader(param_1: u32, mode: i32) -> u32 {
-    // Modes 2, 3, 4: delegate to original
-    if mode != 1 {
-        let orig: unsafe extern "stdcall" fn(u32, i32) -> u32 =
-            core::mem::transmute(REPLAY_LOADER_ORIG);
-        return orig(param_1, mode);
-    }
-
-    // Mode 1 (play): Rust implementation
-    match replay_loader_play(param_1) {
-        Ok(()) => 0,
-        Err(e) => e as u32,
-    }
-}
-```
-
-Header parsing in `replay_loader_play`:
-1. Check `DAT_0088c790 > 0x33` → return ArtClassLimit
-2. Set `param_1+0xDB48 = 1`, `param_1+0xEF60 = 0`
-3. `SetCurrentDirectoryA` to game data dir
-4. `fopen(param_1+0xDB60, "rb")` → create ReplayGuard
-5. Read 4 bytes: validate magic `0x4157`, extract version from upper 16 bits
-6. Validate version ≤ 0x13
-7. Store version at `param_1+0xDB50`, `param_1+0xDB54`, set `param_1+0xDB58 = 0xFFFFFFFF`
-8. Read 4-byte payload size, validate against file size
-9. malloc payload, fread into it → store in ReplayGuard
-
-On any error, `ReplayGuard::drop` handles cleanup automatically.
-
-- [ ] **Step 3: Run headful replay test**
-
-```bash
-powershell -ExecutionPolicy Bypass -File replay-test.ps1
-```
-
-If game crashes, debug calling convention. If it loads but errors, check header
-field offsets.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add crates/openwa-dll/src/replacements/replay.rs crates/openwa-core/src/engine/replay.rs
-git commit -m "feat: ReplayLoader mode routing + header parsing in Rust"
-```
-
----
-
-## Task 6: Version 2+ Payload Parsing — Scheme + Sub-version
-
-**Files:**
-- Modify: `crates/openwa-dll/src/replacements/replay.rs`
-- Modify: `crates/openwa-core/src/engine/replay.rs`
-
-Parse the first portion of the version 2+ payload: sub-version flags, game version
-ID, and scheme data. Version 1 (legacy) delegates to original.
-
-- [ ] **Step 1: Parse sub-version flags and format indicators**
-
-After reading the payload into a `ReplayStream`:
-1. Read secondary payload size + data
-2. Parse sub-version flags, set globals (`DAT_0088AF54`, `DAT_0088AF41` etc.)
-3. Read game version ID → `DAT_0088ABB0`, validate < 0x1F8
-4. Read scheme presence flag → `DAT_0088AE0C`
-
-- [ ] **Step 2: Parse scheme data**
-
-If scheme present:
-1. Read `SCHM` magic (4 bytes = `0x4D484353`), validate
-2. Read scheme version byte (1, 2, or 3)
-3. Call scheme reader helper via FFI bridge (`FUN_004613D0`)
-4. For version 3: call `Scheme__ValidateExtendedOptions` via existing bridge
-5. Copy scheme defaults from `SCHEME_V3_DEFAULTS` where needed
-
-- [ ] **Step 3: Run headful + headless tests**
-
-```bash
-powershell -ExecutionPolicy Bypass -File replay-test.ps1
-powershell -ExecutionPolicy Bypass -File replay-test.ps1 -Headless
-```
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add crates/openwa-dll/src/replacements/replay.rs crates/openwa-core/src/engine/replay.rs
-git commit -m "feat: ReplayLoader version 2+ scheme parsing"
-```
-
----
-
-## Task 7: Version 2+ Payload Parsing — Team Data
-
-**Files:**
-- Modify: `crates/openwa-dll/src/replacements/replay.rs`
-
-Parse the team data section. This is the largest parsing section: 6 teams ×
-0xD7B stride with per-worm names and weapon data blocks.
-
-- [ ] **Step 1: Observer team loop**
-
-Read observer/spectator player names (up to 0xD entries, stride 0x78) into global
-buffers. Uses `read_prefixed_string` for names.
-
-- [ ] **Step 2: Main team iteration**
-
-For each of 6 team slots (stride 0xD7B at `0x878120`):
-1. Read team flag byte — if zero, skip (empty slot)
-2. Read team type byte, validate via `validate_team_type`
-3. Read 5 sub-fields via stream helpers
-4. Read worm alliance byte
-5. Per-worm names: 8 worms × 0x11 bytes (fixed for version ≥ 10, else prefixed)
-6. Worm count (validate 1-8), color, flag, grave, soundbank bytes
-7. Team name (0x40 bytes), config name (0x40 bytes)
-8. Weapon data: `memcpy` 0x400 + 0x154 + 0x400 + 0x300 bytes into global buffers
-
-Write all data to the same global buffer addresses the original uses.
-
-- [ ] **Step 3: Post-team validation**
-
-1. Validate team count matches header
-2. XOR integrity: `DAT_0088AF50 = payload_dword ^ 0xEF5B5C49`
-3. Call `ProcessTeamColors` (0x466460, stdcall 1 param) via FFI
-4. Call `Scheme__CheckWeaponLimits` via existing bridge
-
-- [ ] **Step 4: Call remaining processing functions**
-
-Bridge calls to:
-- `ProcessSchemeDefaults` (0x4670F0, no params, plain RET)
-- `ProcessReplayFlags` (0x467280, no params, plain RET)
-- `ProcessAllianceData` (0x468890, no params, plain RET)
-- `ValidateTeamSetup` (0x465E10)
-
-- [ ] **Step 5: Run headful + headless tests**
-
-```bash
-powershell -ExecutionPolicy Bypass -File replay-test.ps1
-powershell -ExecutionPolicy Bypass -File replay-test.ps1 -Headless
-```
-
-Headful: game must load and play correctly.
-Headless: validates team/scheme data was written correctly.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add crates/openwa-dll/src/replacements/replay.rs
-git commit -m "feat: ReplayLoader team data parsing"
-```
-
----
-
-## Task 8: Post-Parse + Map Loading (Section 4)
-
-**Files:**
-- Modify: `crates/openwa-dll/src/replacements/replay.rs`
-
-- [ ] **Step 1: Port post-parse logic**
-
-1. Write payload to `data\playback.thm` via fopen/fwrite/fclose
-2. Call map loader (`FUN_00490890`) via FFI bridge
-3. Artclass index lookup via table at `0x6ACD38`
-4. Version flag setup for compatibility
-
-- [ ] **Step 2: Run headful + headless tests**
-
-```bash
-powershell -ExecutionPolicy Bypass -File replay-test.ps1
-powershell -ExecutionPolicy Bypass -File replay-test.ps1 -Headless
-```
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add crates/openwa-dll/src/replacements/replay.rs
-git commit -m "feat: ReplayLoader post-parse and map loading"
-```
-
----
-
-## Task 9: Log Output (Section 5)
-
-**Files:**
-- Modify: `crates/openwa-dll/src/replacements/replay.rs`
-
-Port the /getlog formatted output (~600 lines). This must match byte-for-byte
-for headless replay testing.
-
-**Strategy:** Use WA's own string resource and formatting functions via FFI.
-Don't reimplement string resource loading or codepage conversion — bridge them.
-
-- [ ] **Step 1: Port version/game info header lines**
-
-1. Date/time via `_gmtime64` (CRT)
-2. Version string lookup from tables at `0x6AB480` / `0x6AB7A4`
-3. Format "Game:" and "Replay:" lines using `fprintf` or WA's format helpers
-4. WA version line ("3.8.1")
-
-- [ ] **Step 2: Port team listing**
-
-1. Per-team line with flag letter (uppercased via codepage)
-2. Team name in quotes, padded for alignment
-3. Player name assignment
-4. CPU teams: difficulty float
-5. Human teams: host/first markers
-6. Observer teams (negative team type)
-
-- [ ] **Step 3: Run headless test after each sub-section**
-
-```bash
-powershell -ExecutionPolicy Bypass -File replay-test.ps1 -Headless
-```
-
-Compare output byte-for-byte. Fix any differences.
-
-- [ ] **Step 4: Run full test suite**
-
-```bash
-powershell -ExecutionPolicy Bypass -File replay-test.ps1
-powershell -ExecutionPolicy Bypass -File replay-test.ps1 -Headless
-```
-
-Both must pass.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add crates/openwa-dll/src/replacements/replay.rs
-git commit -m "feat: ReplayLoader log output formatting"
-```
-
----
-
-## Task 10: Version 1 Legacy Path (Optional/Deferred)
-
-**Files:**
-- Modify: `crates/openwa-dll/src/replacements/replay.rs`
-
-Version 1 replays are from pre-3.5 WA. If encountered, the current implementation
-would need to delegate to the original. This task ports the version 1 path.
-
-**Deferred:** Only implement if a version 1 test replay is available.
-
-- [ ] **Step 1: Find or create a version 1 test replay**
-- [ ] **Step 2: Port version 1 parsing path**
-- [ ] **Step 3: Test with version 1 replay**
-- [ ] **Step 4: Commit**
-
----
-
----
-
-## Verification Checklist
-
-After Tasks 1-9:
-- [ ] Headful replay test passes (all validations)
-- [ ] Headless replay test passes (byte-identical output)
-- [ ] `cargo test -p openwa-core -- replay` passes (unit tests)
-- [ ] No regressions in existing tests
-- [ ] ReplayLoader uses Rust path for mode 1 (play)
-- [ ] ParseReplayPosition fully replaced (no trampoline calls)
-- [ ] All replay helper functions named in Ghidra

docs/superpowers/plans/2026-04-01-sprite-parser.md

@@ -1,1041 +0,0 @@
-# Sprite Parser Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Port WA's `.spr` sprite parser to Rust — a clean `ParsedSprite` type for tooling, plus hook replacements for `ConstructSprite` and `ProcessSprite`.
-
-**Architecture:** A shared `parse_spr_header()` function extracts metadata and data offsets from raw `.spr` bytes. `ParsedSprite::parse()` builds on it to produce an owned Rust struct with `Vec` data. The hook replacements use `parse_spr_header()` directly, operating on the raw buffer in-place for palette remapping and bitmap index translation.
-
-**Tech Stack:** Rust, `openwa-core` (types/parser), `openwa-dll` (hooks), `minhook` (hooking), WA.exe runtime (PaletteContext__MapColor)
-
----
-
-## File Structure
-
-| File | Responsibility |
-|---|---|
-| `crates/openwa-core/src/render/spr.rs` (create) | `SprHeader`, `SprError`, `parse_spr_header()`, `ParsedSprite`, `ParsedSprite::parse()` |
-| `crates/openwa-core/src/render/mod.rs` (modify) | Add `pub mod spr;` and re-exports |
-| `crates/openwa-core/src/address.rs` (modify) | Add `PALETTE_CONTEXT_MAP_COLOR`, `DISPLAYGFX_VTABLE` |
-| `crates/openwa-dll/src/replacements/sprite.rs` (create) | Hook trampolines + `install()` for ConstructSprite, ProcessSprite |
-| `crates/openwa-dll/src/replacements/mod.rs` (modify) | Wire `sprite::install()` |
-
-## Reference: .spr Binary Format
-
-Derived from Ghidra disassembly of ProcessSprite (0x4FAB80). All offsets relative to start of raw data.
-
-```
-+0x00  u32    (unused / magic — not validated by ProcessSprite)
-+0x04  u32    data_size — total payload size, added to global counter
-+0x08  u16    header_flags — stored at sprite+0x14
-+0x0A  u16    palette_entry_count
-+0x0C  3*N    palette RGB entries (3 bytes each: R, G, B)
-
-[After palette, if header_flags & 0x4000:]
-       u16    secondary_frame_count
-       align cursor to 4-byte boundary (relative to data start)
-       N*12   secondary SpriteFrame entries (12 bytes each)
-
-[Main frame header — 12 bytes:]
-       u16    unknown_08 → sprite+0x08
-       u16    fps → sprite+0x0A
-       u16    flags → sprite+0x10
-       u16    width → sprite+0x0C
-       u16    height → sprite+0x0E
-       u16    frame_count_raw → sprite+0x12/0x16 (negative = scaling)
-
-       align cursor to 4-byte boundary (relative to data start)
-       frame_count * 12 bytes of SpriteFrame metadata
-       remaining bytes: bitmap pixel data (8-bit palette indices)
-```
-
-**Scaling:** If frame_count_raw has bit 15 set (negative as i16):
-- `scale_x = ((frame_count_raw >> 8) & 0x7F) << 16 >> 5` (arithmetic shift)
-- `scale_y = (frame_count_raw & 0x7F) << 16 >> 5`
-- Actual frame_count = 1, is_scaled = true
-
-**Palette remapping (WA runtime only):**
-- `palette_data_ptr[0] = 0` (transparent index)
-- For each entry 1..N: `palette_data_ptr[i] = PaletteContext__MapColor(this=ECX, rgb_u32)`
-- Then ALL bitmap bytes remapped: `pixel = palette_data_ptr[pixel]`
-- Bitmap remapping only happens when header_flags & 0x4000 is NOT set
-
-## Reference: Key WA Functions
-
-| Address | Convention | Description |
-|---|---|---|
-| 0x4FAA30 | usercall(EAX=sprite, ECX=context), plain RET | ConstructSprite |
-| 0x4FAB80 | usercall(EAX=sprite, ECX=palette_ctx) + 1 stack(raw_data), RET 0x4 | ProcessSprite |
-| 0x5412B0 | thiscall(ECX=palette_ctx, stack=rgb_u32), RET 0x4, returns u8 | PaletteContext__MapColor |
-| 0x66418C | data | Sprite vtable address |
-| 0x664144 | data | DisplayGfx vtable address |
-
----
-
-### Task 1: Add Address Constants
-
-**Files:**
-- Modify: `crates/openwa-core/src/address.rs`
-
-- [ ] **Step 1: Add PALETTE_CONTEXT_MAP_COLOR and DISPLAYGFX_VTABLE**
-
-In `address.rs`, find the `class "Sprite"` block and add the DisplayGfx vtable. Find the DDDisplay section and add the palette function:
-
-```rust
-// In the class "Sprite" block, after PROCESS_SPRITE:
-// (no change needed here, but add DisplayGfx vtable nearby)
-
-// Add to the DDDisplay section (near PALETTE_CONTEXT_INIT):
-/// PaletteContext__MapColor — thiscall(ECX=ctx, stack=rgb), RET 0x4, returns u8
-fn/Thiscall PALETTE_CONTEXT_MAP_COLOR = 0x0054_12B0;
-
-// Add DisplayGfx vtable as a standalone entry near SPRITE_VTABLE:
-// In the class "Sprite" block:
-/// DisplayGfx vtable (embedded in Sprite at +0x34)
-vtable DISPLAYGFX_VTABLE = 0x0066_4144;
-```
-
-Specifically, in the `class "Sprite"` block after `fn/Usercall PROCESS_SPRITE`, add:
-
-```rust
-            /// DisplayGfx vtable (embedded in Sprite at +0x34)
-            vtable DISPLAYGFX_VTABLE = 0x0066_4144;
-```
-
-And near `PALETTE_CONTEXT_INIT` in the DDDisplay section, add:
-
-```rust
-        /// PaletteContext__MapColor — thiscall(palette_ctx, rgb_u32), returns nearest palette index
-        fn/Thiscall PALETTE_CONTEXT_MAP_COLOR = 0x0054_12B0;
-```
-
-- [ ] **Step 2: Verify it compiles**
-
-Run: `cargo build -p openwa-core 2>&1 | head -5`
-Expected: Compiles without errors.
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add crates/openwa-core/src/address.rs
-git commit -m "feat: add PALETTE_CONTEXT_MAP_COLOR and DISPLAYGFX_VTABLE addresses"
-```
-
----
-
-### Task 2: Create spr.rs — SprHeader and parse_spr_header()
-
-**Files:**
-- Create: `crates/openwa-core/src/render/spr.rs`
-- Modify: `crates/openwa-core/src/render/mod.rs`
-
-- [ ] **Step 1: Write the test for parse_spr_header**
-
-Create `crates/openwa-core/src/render/spr.rs` with the error type, header struct, and a test:
-
-```rust
-//! `.spr` sprite format parser.
-//!
-//! WA's sprite format stores paletted animated sprites with per-frame metadata.
-//! This module provides both a clean Rust parser (`ParsedSprite`) for tooling
-//! and shared metadata extraction (`parse_spr_header`) used by WormKit hook
-//! replacements.
-
-use crate::render::sprite::SpriteFrame;
-
-/// Errors from `.spr` parsing.
-#[derive(Debug)]
-pub enum SprError {
-    /// Data too short to contain required fields.
-    TooShort {
-        expected: usize,
-        actual: usize,
-    },
-    /// Internal structure is inconsistent.
-    InvalidData(&'static str),
-}
-
-impl core::fmt::Display for SprError {
-    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
-        match self {
-            SprError::TooShort { expected, actual } => {
-                write!(f, "spr data too short: need {} bytes, got {}", expected, actual)
-            }
-            SprError::InvalidData(msg) => write!(f, "invalid spr data: {}", msg),
-        }
-    }
-}
-
-/// Parsed metadata and byte offsets into raw `.spr` data.
-///
-/// Produced by `parse_spr_header`. Contains all scalar fields and the byte
-/// offsets needed to locate palette, frame, and bitmap data within the raw
-/// buffer. No heap allocation — just arithmetic on the input slice.
-#[derive(Debug, Clone)]
-pub struct SprHeader {
-    /// Total payload size from `.spr` header (+0x04). Used for global counter.
-    pub data_size: u32,
-    /// Header flags from `.spr` (+0x08).
-    pub header_flags: u16,
-    /// Number of RGB palette entries.
-    pub palette_count: u16,
-    /// Unknown field stored at sprite+0x08.
-    pub unknown_08: u16,
-    /// Animation speed (frames per second).
-    pub fps: u16,
-    /// Sprite flags.
-    pub flags: u16,
-    /// Sprite width in pixels.
-    pub width: u16,
-    /// Sprite height in pixels.
-    pub height: u16,
-    /// Frame count (1 if scaled).
-    pub frame_count: u16,
-    /// Max frames (same as frame_count after processing).
-    pub max_frames: u16,
-    /// Scale X: `((raw >> 8 & 0x7F) << 16) >> 5`, or 0 if not scaled.
-    pub scale_x: u32,
-    /// Scale Y: `((raw & 0x7F) << 16) >> 5`, or 0 if not scaled.
-    pub scale_y: u32,
-    /// True if the frame_count word encoded scaling instead of a count.
-    pub is_scaled: bool,
-    /// Number of secondary frames (0 if header_flags & 0x4000 is clear).
-    pub secondary_frame_count: u16,
-    /// Byte offset of RGB palette data (3 bytes per entry).
-    pub palette_offset: usize,
-    /// Byte offset of secondary frame table (0 if none).
-    pub secondary_frame_offset: usize,
-    /// Byte offset of main SpriteFrame metadata array.
-    pub frame_meta_offset: usize,
-    /// Byte offset of bitmap pixel data.
-    pub bitmap_offset: usize,
-    /// Size of bitmap pixel data in bytes.
-    pub bitmap_size: usize,
-}
-
-/// Align `offset` up to the next 4-byte boundary.
-fn align4(offset: usize) -> usize {
-    (offset + 3) & !3
-}
-
-/// Parse `.spr` header and compute data region offsets.
-///
-/// This is a pure function with no WA dependencies. Both `ParsedSprite::parse`
-/// and the WormKit ProcessSprite hook build on this.
-pub fn parse_spr_header(data: &[u8]) -> Result<SprHeader, SprError> {
-    // Minimum: 4 (unused) + 4 (data_size) + 2 (header_flags) + 2 (palette_count) = 12
-    if data.len() < 12 {
-        return Err(SprError::TooShort { expected: 12, actual: data.len() });
-    }
-
-    let data_size = u32::from_le_bytes([data[4], data[5], data[6], data[7]]);
-    let header_flags = u16::from_le_bytes([data[8], data[9]]);
-    let palette_count = u16::from_le_bytes([data[10], data[11]]);
-
-    let palette_offset = 12; // 0x0C
-    let palette_end = palette_offset + palette_count as usize * 3;
-
-    if data.len() < palette_end {
-        return Err(SprError::TooShort { expected: palette_end, actual: data.len() });
-    }
-
-    let mut cursor = palette_end;
-
-    // Secondary frame table (if header_flags & 0x4000)
-    let mut secondary_frame_count: u16 = 0;
-    let mut secondary_frame_offset: usize = 0;
-
-    if header_flags & 0x4000 != 0 {
-        if data.len() < cursor + 2 {
-            return Err(SprError::TooShort { expected: cursor + 2, actual: data.len() });
-        }
-        secondary_frame_count = u16::from_le_bytes([data[cursor], data[cursor + 1]]);
-        cursor = align4(cursor + 2);
-        secondary_frame_offset = cursor;
-        cursor += secondary_frame_count as usize * 12;
-    }
-
-    // Main frame header (12 bytes)
-    if data.len() < cursor + 12 {
-        return Err(SprError::TooShort { expected: cursor + 12, actual: data.len() });
-    }
-
-    let unknown_08 = u16::from_le_bytes([data[cursor], data[cursor + 1]]);
-    let fps = u16::from_le_bytes([data[cursor + 2], data[cursor + 3]]);
-    let flags = u16::from_le_bytes([data[cursor + 4], data[cursor + 5]]);
-    let width = u16::from_le_bytes([data[cursor + 6], data[cursor + 7]]);
-    let height = u16::from_le_bytes([data[cursor + 8], data[cursor + 9]]);
-    let frame_count_raw = u16::from_le_bytes([data[cursor + 10], data[cursor + 11]]);
-
-    cursor += 12;
-
-    // Scale processing
-    let (frame_count, max_frames, scale_x, scale_y, is_scaled) =
-        if (frame_count_raw as i16) < 0 {
-            let sx = (((frame_count_raw >> 8) & 0x7F) as u32) << 16 >> 5;
-            let sy = ((frame_count_raw & 0x7F) as u32) << 16 >> 5;
-            (1u16, 1u16, sx, sy, true)
-        } else {
-            (frame_count_raw, frame_count_raw, 0u32, 0u32, false)
-        };
-
-    // Frame metadata (aligned to 4 bytes)
-    let frame_meta_offset = align4(cursor);
-    let bitmap_offset = frame_meta_offset + frame_count as usize * 12;
-
-    // bitmap_size: remaining bytes from data_size
-    // ProcessSprite computes: data_size - (bitmap_offset - data_start)
-    // But data_size is measured from offset +4, and data_start is offset 0.
-    // Actually WA computes: bitmap_dword_count = (data_size - bitmap_ptr + raw_data_ptr + 3) / 4
-    // which simplifies to: (data_size + 4 - bitmap_offset + 3) / 4 * 4
-    // For our purposes: bitmap extends from bitmap_offset to the end of known data.
-    let bitmap_size = if data.len() > bitmap_offset {
-        data.len() - bitmap_offset
-    } else {
-        0
-    };
-
-    Ok(SprHeader {
-        data_size,
-        header_flags,
-        palette_count,
-        unknown_08,
-        fps,
-        flags,
-        width,
-        height,
-        frame_count,
-        max_frames,
-        scale_x,
-        scale_y,
-        is_scaled,
-        secondary_frame_count,
-        palette_offset,
-        secondary_frame_offset,
-        frame_meta_offset,
-        bitmap_offset,
-        bitmap_size,
-    })
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    /// Build a minimal single-frame .spr with given dimensions and palette.
-    fn make_spr(width: u16, height: u16, palette_count: u16, frame_count: u16) -> Vec<u8> {
-        let mut data = Vec::new();
-
-        // +0x00: unused magic
-        data.extend_from_slice(&0u32.to_le_bytes());
-        // +0x04: data_size (we'll fix up later)
-        let data_size_pos = data.len();
-        data.extend_from_slice(&0u32.to_le_bytes());
-        // +0x08: header_flags
-        data.extend_from_slice(&0u16.to_le_bytes());
-        // +0x0A: palette_entry_count
-        data.extend_from_slice(&palette_count.to_le_bytes());
-        // +0x0C: palette RGB entries (all zeros)
-        for _ in 0..palette_count {
-            data.extend_from_slice(&[0u8; 3]);
-        }
-
-        // Main frame header (12 bytes)
-        data.extend_from_slice(&0u16.to_le_bytes()); // unknown_08
-        data.extend_from_slice(&10u16.to_le_bytes()); // fps = 10
-        data.extend_from_slice(&0u16.to_le_bytes()); // flags
-        data.extend_from_slice(&width.to_le_bytes());
-        data.extend_from_slice(&height.to_le_bytes());
-        data.extend_from_slice(&frame_count.to_le_bytes());
-
-        // Align to 4 bytes
-        while data.len() % 4 != 0 {
-            data.push(0);
-        }
-
-        // Frame metadata (12 bytes per frame)
-        for i in 0..frame_count {
-            let offset = i as u32 * width as u32 * height as u32;
-            data.extend_from_slice(&offset.to_le_bytes()); // bitmap_offset
-            data.extend_from_slice(&0u16.to_le_bytes()); // start_x
-            data.extend_from_slice(&0u16.to_le_bytes()); // start_y
-            data.extend_from_slice(&width.to_le_bytes()); // end_x
-            data.extend_from_slice(&height.to_le_bytes()); // end_y
-        }
-
-        // Bitmap data (width * height * frame_count bytes)
-        let bitmap_bytes = width as usize * height as usize * frame_count as usize;
-        data.resize(data.len() + bitmap_bytes, 0);
-
-        // Fix up data_size (everything from +4 onward)
-        let total = (data.len() - 4) as u32;
-        data[data_size_pos..data_size_pos + 4].copy_from_slice(&total.to_le_bytes());
-
-        data
-    }
-
-    #[test]
-    fn parse_single_frame() {
-        let data = make_spr(32, 16, 4, 1);
-        let hdr = parse_spr_header(&data).unwrap();
-
-        assert_eq!(hdr.width, 32);
-        assert_eq!(hdr.height, 16);
-        assert_eq!(hdr.fps, 10);
-        assert_eq!(hdr.palette_count, 4);
-        assert_eq!(hdr.frame_count, 1);
-        assert!(!hdr.is_scaled);
-        assert_eq!(hdr.scale_x, 0);
-        assert_eq!(hdr.scale_y, 0);
-        assert_eq!(hdr.secondary_frame_count, 0);
-        assert_eq!(hdr.palette_offset, 12);
-        assert!(hdr.frame_meta_offset > 0);
-        assert!(hdr.bitmap_offset > hdr.frame_meta_offset);
-    }
-
-    #[test]
-    fn parse_multi_frame() {
-        let data = make_spr(8, 8, 2, 5);
-        let hdr = parse_spr_header(&data).unwrap();
-
-        assert_eq!(hdr.frame_count, 5);
-        assert_eq!(hdr.max_frames, 5);
-        // 5 frames * 12 bytes each = 60 bytes of frame metadata
-        assert_eq!(hdr.bitmap_offset - hdr.frame_meta_offset, 60);
-    }
-
-    #[test]
-    fn parse_scaled_sprite() {
-        // frame_count_raw = 0x8040: bit15 set, scale_x_raw = 0, scale_y_raw = 0x40
-        // Actually: high byte = 0x80, (0x80 >> 0) & 0x7F for scale from bits 8..14
-        // Let's use 0xA050: high byte 0xA0, low byte 0x50
-        // scale_x_raw = (0xA050 >> 8) & 0x7F = 0xA0 & 0x7F = 0x20
-        // scale_y_raw = 0xA050 & 0x7F = 0x50
-        let mut data = make_spr(32, 32, 0, 1);
-        // Overwrite frame_count_raw in the main frame header
-        // palette_count = 0, so palette_end = 12
-        // main frame header starts at 12, frame_count is at offset 10 within it = byte 22
-        data[22] = 0x50; // low byte
-        data[23] = 0xA0; // high byte (bit 15 set)
-
-        let hdr = parse_spr_header(&data).unwrap();
-
-        assert!(hdr.is_scaled);
-        assert_eq!(hdr.frame_count, 1);
-        assert_eq!(hdr.max_frames, 1);
-        // scale_x = (0x20 << 16) >> 5 = 0x200000 >> 5 = 0x10000
-        assert_eq!(hdr.scale_x, (0x20u32 << 16) >> 5);
-        // scale_y = (0x50 << 16) >> 5 = 0x500000 >> 5 = 0x28000
-        assert_eq!(hdr.scale_y, (0x50u32 << 16) >> 5);
-    }
-
-    #[test]
-    fn parse_too_short() {
-        assert!(parse_spr_header(&[0; 4]).is_err());
-    }
-}
-```
-
-- [ ] **Step 2: Add module to render/mod.rs**
-
-In `crates/openwa-core/src/render/mod.rs`, add:
-
-```rust
-pub mod spr;
-```
-
-And add re-exports:
-
-```rust
-pub use spr::{ParsedSprite, SprError, SprHeader};
-```
-
-(The `ParsedSprite` re-export will fail initially since we haven't defined it yet — that's fine, comment it out or add it in Task 3.)
-
-- [ ] **Step 3: Run tests**
-
-Run: `cargo test -p openwa-core -- spr::tests`
-Expected: All 4 tests pass.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add crates/openwa-core/src/render/spr.rs crates/openwa-core/src/render/mod.rs
-git commit -m "feat: add .spr header parser with SprHeader and parse_spr_header()"
-```
-
----
-
-### Task 3: Add ParsedSprite and ParsedSprite::parse()
-
-**Files:**
-- Modify: `crates/openwa-core/src/render/spr.rs`
-- Modify: `crates/openwa-core/src/render/mod.rs`
-
-- [ ] **Step 1: Write failing test for ParsedSprite::parse**
-
-Add to the `tests` module in `spr.rs`:
-
-```rust
-    #[test]
-    fn parsed_sprite_single_frame() {
-        let mut data = make_spr(4, 4, 3, 1);
-        // Fill palette with known RGB values
-        data[12] = 0xFF; data[13] = 0x00; data[14] = 0x00; // entry 0: red
-        data[15] = 0x00; data[16] = 0xFF; data[17] = 0x00; // entry 1: green
-        data[18] = 0x00; data[19] = 0x00; data[20] = 0xFF; // entry 2: blue
-
-        let parsed = ParsedSprite::parse(&data).unwrap();
-        assert_eq!(parsed.width, 4);
-        assert_eq!(parsed.height, 4);
-        assert_eq!(parsed.palette.len(), 3);
-        assert_eq!(parsed.palette[0], [0xFF, 0x00, 0x00]);
-        assert_eq!(parsed.palette[1], [0x00, 0xFF, 0x00]);
-        assert_eq!(parsed.palette[2], [0x00, 0x00, 0xFF]);
-        assert_eq!(parsed.frames.len(), 1);
-        assert_eq!(parsed.bitmap.len(), 16); // 4*4 pixels
-    }
-
-    #[test]
-    fn parsed_sprite_secondary_frames() {
-        let mut data = Vec::new();
-
-        // Header
-        data.extend_from_slice(&0u32.to_le_bytes()); // unused
-        data.extend_from_slice(&0u32.to_le_bytes()); // data_size (fix later)
-        data.extend_from_slice(&0x4000u16.to_le_bytes()); // header_flags: secondary frames
-        data.extend_from_slice(&0u16.to_le_bytes()); // palette_count = 0
-
-        // Secondary frame table
-        data.extend_from_slice(&2u16.to_le_bytes()); // 2 secondary frames
-        // Align to 4 bytes
-        while data.len() % 4 != 0 { data.push(0); }
-        // 2 secondary SpriteFrame entries (12 bytes each)
-        for _ in 0..2 {
-            data.extend_from_slice(&[0u8; 12]);
-        }
-
-        // Main frame header
-        data.extend_from_slice(&0u16.to_le_bytes()); // unknown_08
-        data.extend_from_slice(&15u16.to_le_bytes()); // fps
-        data.extend_from_slice(&0u16.to_le_bytes()); // flags
-        data.extend_from_slice(&8u16.to_le_bytes()); // width
-        data.extend_from_slice(&8u16.to_le_bytes()); // height
-        data.extend_from_slice(&1u16.to_le_bytes()); // frame_count
-
-        while data.len() % 4 != 0 { data.push(0); }
-        // 1 main SpriteFrame
-        data.extend_from_slice(&0u32.to_le_bytes()); // bitmap_offset
-        data.extend_from_slice(&0u16.to_le_bytes()); // start_x
-        data.extend_from_slice(&0u16.to_le_bytes()); // start_y
-        data.extend_from_slice(&8u16.to_le_bytes()); // end_x
-        data.extend_from_slice(&8u16.to_le_bytes()); // end_y
-
-        // Bitmap (8*8 = 64 bytes)
-        data.resize(data.len() + 64, 0);
-
-        // Fix data_size
-        let total = (data.len() - 4) as u32;
-        data[4..8].copy_from_slice(&total.to_le_bytes());
-
-        let parsed = ParsedSprite::parse(&data).unwrap();
-        assert_eq!(parsed.secondary_frames.len(), 2);
-        assert_eq!(parsed.frames.len(), 1);
-        assert_eq!(parsed.header_flags, 0x4000);
-    }
-```
-
-- [ ] **Step 2: Implement ParsedSprite**
-
-Add above the `#[cfg(test)]` block in `spr.rs`:
-
-```rust
-/// A fully parsed `.spr` sprite with owned data.
-///
-/// Contains raw RGB palette entries (not remapped to WA's display palette),
-/// raw bitmap pixel indices, and frame metadata. Suitable for standalone
-/// tooling, tests, and debugging.
-///
-/// For WormKit hook replacements, `parse_spr_header` is used directly
-/// with in-place buffer operations instead.
-#[derive(Debug, Clone)]
-pub struct ParsedSprite {
-    /// Unknown field at sprite+0x08.
-    pub unknown_08: u16,
-    /// Animation frames per second.
-    pub fps: u16,
-    /// Sprite flags.
-    pub flags: u16,
-    /// Header flags from `.spr` file.
-    pub header_flags: u16,
-    /// Sprite width in pixels.
-    pub width: u16,
-    /// Sprite height in pixels.
-    pub height: u16,
-    /// Number of animation frames.
-    pub frame_count: u16,
-    /// Maximum frame count.
-    pub max_frames: u16,
-    /// Scale X (`(raw << 16) >> 5`), or 0 if not scaled.
-    pub scale_x: u32,
-    /// Scale Y (`(raw << 16) >> 5`), or 0 if not scaled.
-    pub scale_y: u32,
-    /// Whether the sprite uses scaling instead of animation.
-    pub is_scaled: bool,
-    /// RGB palette entries (3 bytes each). NOT remapped to display palette.
-    pub palette: Vec<[u8; 3]>,
-    /// Per-frame metadata (bounding box + bitmap offset).
-    pub frames: Vec<SpriteFrame>,
-    /// Secondary frame table (non-empty iff header_flags & 0x4000).
-    pub secondary_frames: Vec<SpriteFrame>,
-    /// Bitmap pixel data — 8-bit indices into the sprite's local palette.
-    pub bitmap: Vec<u8>,
-    /// Total data size from `.spr` header (for global counter updates).
-    pub data_size: u32,
-}
-
-impl ParsedSprite {
-    /// Parse a `.spr` file from raw bytes.
-    ///
-    /// Returns owned data with no WA runtime dependencies.
-    pub fn parse(data: &[u8]) -> Result<Self, SprError> {
-        let hdr = parse_spr_header(data)?;
-
-        // Extract palette RGB triples
-        let mut palette = Vec::with_capacity(hdr.palette_count as usize);
-        let mut offset = hdr.palette_offset;
-        for _ in 0..hdr.palette_count {
-            palette.push([data[offset], data[offset + 1], data[offset + 2]]);
-            offset += 3;
-        }
-
-        // Extract secondary frames
-        let mut secondary_frames = Vec::new();
-        if hdr.secondary_frame_count > 0 {
-            secondary_frames.reserve(hdr.secondary_frame_count as usize);
-            let mut off = hdr.secondary_frame_offset;
-            for _ in 0..hdr.secondary_frame_count {
-                secondary_frames.push(read_sprite_frame(data, off));
-                off += 12;
-            }
-        }
-
-        // Extract main frames
-        let mut frames = Vec::with_capacity(hdr.frame_count as usize);
-        let mut off = hdr.frame_meta_offset;
-        for _ in 0..hdr.frame_count {
-            frames.push(read_sprite_frame(data, off));
-            off += 12;
-        }
-
-        // Extract bitmap data
-        let bitmap_end = data.len().min(hdr.bitmap_offset + hdr.bitmap_size);
-        let bitmap = data[hdr.bitmap_offset..bitmap_end].to_vec();
-
-        Ok(ParsedSprite {
-            unknown_08: hdr.unknown_08,
-            fps: hdr.fps,
-            flags: hdr.flags,
-            header_flags: hdr.header_flags,
-            width: hdr.width,
-            height: hdr.height,
-            frame_count: hdr.frame_count,
-            max_frames: hdr.max_frames,
-            scale_x: hdr.scale_x,
-            scale_y: hdr.scale_y,
-            is_scaled: hdr.is_scaled,
-            palette,
-            frames,
-            secondary_frames,
-            bitmap,
-            data_size: hdr.data_size,
-        })
-    }
-}
-
-/// Read a SpriteFrame from 12 bytes at the given offset.
-fn read_sprite_frame(data: &[u8], off: usize) -> SpriteFrame {
-    SpriteFrame {
-        bitmap_offset: u32::from_le_bytes([data[off], data[off+1], data[off+2], data[off+3]]),
-        start_x: u16::from_le_bytes([data[off+4], data[off+5]]),
-        start_y: u16::from_le_bytes([data[off+6], data[off+7]]),
-        end_x: u16::from_le_bytes([data[off+8], data[off+9]]),
-        end_y: u16::from_le_bytes([data[off+10], data[off+11]]),
-    }
-}
-```
-
-- [ ] **Step 3: Update render/mod.rs re-exports**
-
-```rust
-pub use spr::{ParsedSprite, SprError, SprHeader};
-```
-
-- [ ] **Step 4: Run tests**
-
-Run: `cargo test -p openwa-core -- spr::tests`
-Expected: All 6 tests pass (4 from Task 2 + 2 new).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add crates/openwa-core/src/render/spr.rs crates/openwa-core/src/render/mod.rs
-git commit -m "feat: add ParsedSprite type with owned .spr parser"
-```
-
----
-
-### Task 4: ConstructSprite Hook Replacement
-
-**Files:**
-- Create: `crates/openwa-dll/src/replacements/sprite.rs`
-
-- [ ] **Step 1: Create sprite.rs with ConstructSprite hook**
-
-Create `crates/openwa-dll/src/replacements/sprite.rs`:
-
-```rust
-//! Sprite loading hook replacements.
-//!
-//! Replaces ConstructSprite (0x4FAA30) and ProcessSprite (0x4FAB80) with
-//! Rust implementations. Uses `parse_spr_header` from openwa-core for
-//! format parsing.
-
-use openwa_core::address::va;
-use openwa_core::rebase::rb;
-
-use crate::hook::{self, usercall_trampoline};
-
-// ---------------------------------------------------------------------------
-// ConstructSprite (0x4FAA30) — usercall(EAX=sprite, ECX=context), plain RET
-// ---------------------------------------------------------------------------
-
-usercall_trampoline!(fn trampoline_construct_sprite; impl_fn = construct_sprite_impl;
-    regs = [eax, ecx]);
-
-unsafe extern "cdecl" fn construct_sprite_impl(sprite: u32, context: u32) {
-    let p = sprite as *mut u8;
-
-    // Zero the entire 0x70-byte struct first
-    core::ptr::write_bytes(p, 0, 0x70);
-
-    // Vtable
-    *(p as *mut u32) = rb(va::SPRITE_VTABLE);
-    // Context pointer (+0x04)
-    *(p.add(0x04) as *mut u32) = context;
-    // DisplayGfx vtable (+0x34)
-    *(p.add(0x34) as *mut u32) = rb(va::DISPLAYGFX_VTABLE);
-    // _unknown_38 = 1 (+0x38)
-    *(p.add(0x38) as *mut u32) = 1;
-    // _unknown_40 = 8 (+0x40)
-    *(p.add(0x40) as *mut u32) = 8;
-}
-
-// ---------------------------------------------------------------------------
-// Installation
-// ---------------------------------------------------------------------------
-
-pub fn install() -> Result<(), String> {
-    unsafe {
-        let _ = hook::install(
-            "ConstructSprite",
-            va::CONSTRUCT_SPRITE,
-            trampoline_construct_sprite as *const (),
-        )?;
-    }
-    Ok(())
-}
-```
-
-- [ ] **Step 2: Verify it compiles**
-
-Run: `cargo build -p openwa-dll --release 2>&1 | tail -5`
-Expected: Compiles (sprite.rs is not yet in mod.rs, so it won't be included — this just checks syntax).
-
-Actually, it won't compile unless added to mod.rs. Skip to step 3.
-
-- [ ] **Step 3: Add to mod.rs and verify**
-
-In `crates/openwa-dll/src/replacements/mod.rs`, add `mod sprite;` and add `sprite::install()?;` in `install_all()` after `render::install()?;`.
-
-Run: `cargo build -p openwa-dll --release 2>&1 | tail -5`
-Expected: Compiles without errors.
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add crates/openwa-dll/src/replacements/sprite.rs crates/openwa-dll/src/replacements/mod.rs
-git commit -m "feat: add ConstructSprite hook replacement"
-```
-
----
-
-### Task 5: ProcessSprite Hook Replacement
-
-**Files:**
-- Modify: `crates/openwa-dll/src/replacements/sprite.rs`
-
-This is the most complex task. ProcessSprite:
-1. Reads header metadata via `parse_spr_header`
-2. Builds a palette lookup table in-place (calling PaletteContext__MapColor)
-3. Sets all sprite struct fields + pointers into the raw buffer
-4. Remaps bitmap pixels through the lookup table (when no secondary frames)
-5. Computes and updates 4 global counters
-
-- [ ] **Step 1: Add PaletteContext__MapColor bridge**
-
-Add to `sprite.rs`, above the `install()` function:
-
-```rust
-// ---------------------------------------------------------------------------
-// PaletteContext__MapColor bridge (0x5412B0)
-// thiscall(ECX=palette_ctx, stack=rgb_u32), RET 0x4, returns u8
-// ---------------------------------------------------------------------------
-
-static mut PALETTE_MAP_COLOR_ADDR: u32 = 0;
-
-/// Call WA's PaletteContext__MapColor to find the nearest display palette index.
-#[cfg(target_arch = "x86")]
-unsafe fn palette_map_color(palette_ctx: u32, rgb: u32) -> u8 {
-    let f: unsafe extern "thiscall" fn(u32, u32) -> u32 =
-        core::mem::transmute(PALETTE_MAP_COLOR_ADDR as usize);
-    f(palette_ctx, rgb) as u8
-}
-```
-
-Note: we use `-> u32` for the transmuted function since WA returns the value in EAX (full register), and we mask to u8. This avoids potential ABI issues with `-> u8` on MSVC x86.
-
-- [ ] **Step 2: Add ProcessSprite trampoline and implementation**
-
-Add to `sprite.rs`:
-
-```rust
-// ---------------------------------------------------------------------------
-// ProcessSprite (0x4FAB80)
-// usercall(EAX=sprite, ECX=palette_ctx) + 1 stack(raw_data), RET 0x4
-// ---------------------------------------------------------------------------
-
-usercall_trampoline!(fn trampoline_process_sprite; impl_fn = process_sprite_impl;
-    regs = [eax, ecx]; stack_params = 1; ret_bytes = "0x4");
-
-unsafe extern "cdecl" fn process_sprite_impl(
-    sprite: u32,
-    palette_ctx: u32,
-    raw_data: u32,
-) -> u32 {
-    use openwa_core::render::spr::parse_spr_header;
-
-    let p = sprite as *mut u8;
-    let data_ptr = raw_data as *const u8;
-
-    // We need the data as a slice. Use data_size from header to determine length.
-    // data_size is at raw_data + 4.
-    let data_size = *(data_ptr.add(4) as *const u32);
-    // Total buffer: data_size covers from offset +4 onward, so total = data_size + 4.
-    // But we also need the initial 4 unused bytes, so slice length = data_size + 4.
-    // However, data_size might not include the bitmap — let's be safe and use
-    // data_size + 4 as the slice length (this matches what WA allocated).
-    let data_len = (data_size + 4) as usize;
-    let data = core::slice::from_raw_parts(data_ptr, data_len);
-
-    let hdr = match parse_spr_header(data) {
-        Ok(h) => h,
-        Err(e) => {
-            // This should never happen with valid WA game data
-            panic!("ProcessSprite: failed to parse .spr data: {}", e);
-        }
-    };
-
-    // --- Update global counter: data_size ---
-    let g_data_bytes = rb(va::G_SPRITE_DATA_BYTES) as *mut u32;
-    *g_data_bytes = (*g_data_bytes).wrapping_add(data_size);
-
-    // --- Store raw_frame_header_ptr (points to header_flags in raw buffer) ---
-    *(p.add(0x60) as *mut *const u8) = data_ptr.add(8);
-
-    // --- Store header_flags ---
-    *(p.add(0x14) as *mut u16) = hdr.header_flags;
-
-    // --- Build palette lookup table IN PLACE ---
-    // palette_data_ptr points to raw_data + 0x0A (the palette_entry_count field).
-    // WA overwrites this region with a 1-indexed palette index lookup table:
-    //   [0] = 0 (transparent)
-    //   [1..N] = PaletteContext__MapColor(rgb) for each entry
-    let palette_base = data_ptr.add(0x0A) as *mut u8;
-    *(p.add(0x68) as *mut *mut u8) = palette_base;
-
-    // Update global counter: palette bytes
-    let g_palette = rb(va::G_SPRITE_PALETTE_BYTES) as *mut u32;
-    *g_palette = (*g_palette).wrapping_add(hdr.palette_count as u32 * 3);
-
-    // Write transparent index
-    *palette_base = 0;
-
-    // Map each RGB entry to display palette index
-    let rgb_start = data_ptr.add(hdr.palette_offset);
-    for i in 0..hdr.palette_count as usize {
-        // Read 4 bytes (3 RGB + 1 from next entry, matching WA behavior)
-        let rgb_val = *(rgb_start.add(i * 3) as *const u32);
-        let mapped = palette_map_color(palette_ctx, rgb_val);
-        *palette_base.add(1 + i) = mapped;
-    }
-
-    // --- Secondary frame table (if header_flags & 0x4000) ---
-    let has_secondary = hdr.header_flags & 0x4000 != 0;
-    if has_secondary {
-        *(p.add(0x30) as *mut u16) = hdr.secondary_frame_count;
-        *(p.add(0x2C) as *mut *const u8) = data_ptr.add(hdr.secondary_frame_offset);
-    }
-
-    // --- Main frame header fields ---
-    // Copy unknown_08 + fps as a single u32 (matching WA's 4-byte copy)
-    let frame_header_ptr = if has_secondary {
-        // After secondary frames
-        data_ptr.add(hdr.secondary_frame_offset + hdr.secondary_frame_count as usize * 12)
-    } else {
-        data_ptr.add(hdr.palette_offset + hdr.palette_count as usize * 3)
-    };
-
-    // WA copies 4 bytes at once: *(u32*)(sprite+8) = *(u32*)(frame_header)
-    *(p.add(0x08) as *mut u32) = *(frame_header_ptr as *const u32);
-    *(p.add(0x10) as *mut u16) = hdr.flags;
-    *(p.add(0x0C) as *mut u16) = hdr.width;
-    *(p.add(0x0E) as *mut u16) = hdr.height;
-    *(p.add(0x12) as *mut u16) = hdr.frame_count;
-    *(p.add(0x16) as *mut u16) = hdr.max_frames;
-
-    // --- Scale fields ---
-    if hdr.is_scaled {
-        *(p.add(0x1C) as *mut u32) = hdr.scale_x;
-        *(p.add(0x20) as *mut u32) = hdr.scale_y;
-        *(p.add(0x24) as *mut u32) = 1; // is_scaled
-    } else {
-        *(p.add(0x24) as *mut u32) = 0;
-    }
-
-    // --- Frame metadata and bitmap pointers ---
-    let frame_meta_ptr = data_ptr.add(hdr.frame_meta_offset);
-    let bitmap_ptr = data_ptr.add(hdr.bitmap_offset);
-    *(p.add(0x28) as *mut *const u8) = frame_meta_ptr;
-    *(p.add(0x64) as *mut *const u8) = bitmap_ptr;
-
-    // --- Bitmap palette remapping (only when NO secondary frames) ---
-    if !has_secondary {
-        // Remap every bitmap byte: pixel = lookup_table[pixel]
-        // WA processes (data_size - bitmap_offset_relative + 3) / 4 dwords = that many * 4 bytes
-        // We compute the same count for exact WA behavior.
-        let bitmap_start_relative = hdr.bitmap_offset;
-        let bitmap_byte_count_raw = (data_size as usize + 4).saturating_sub(bitmap_start_relative);
-        let dword_count = (bitmap_byte_count_raw + 3) / 4;
-        let remap_byte_count = dword_count * 4;
-
-        let bmp = bitmap_ptr as *mut u8;
-        for i in 0..remap_byte_count {
-            let idx = *bmp.add(i) as usize;
-            *bmp.add(i) = *palette_base.add(idx);
-        }
-    }
-
-    // --- Update global counters: pixel area and frame count ---
-    if hdr.frame_count > 0 {
-        let g_pixel_area = rb(va::G_SPRITE_PIXEL_AREA) as *mut u32;
-        let frames_ptr = frame_meta_ptr as *const [u8; 12];
-        for i in 0..hdr.frame_count as usize {
-            let frame = &*frames_ptr.add(i);
-            let start_x = i16::from_le_bytes([frame[4], frame[5]]);
-            let start_y = i16::from_le_bytes([frame[6], frame[7]]);
-            let end_x = i16::from_le_bytes([frame[8], frame[9]]);
-            let end_y = i16::from_le_bytes([frame[10], frame[11]]);
-            let area = (end_x as i32 - start_x as i32) * (end_y as i32 - start_y as i32);
-            *g_pixel_area = (*g_pixel_area).wrapping_add(area as u32);
-        }
-    }
-
-    let g_frame_count = rb(va::G_SPRITE_FRAME_COUNT) as *mut u32;
-    *g_frame_count = (*g_frame_count).wrapping_add(hdr.frame_count as u32);
-
-    1 // success
-}
-```
-
-- [ ] **Step 3: Update install() to include ProcessSprite hook**
-
-Update the `install()` function:
-
-```rust
-pub fn install() -> Result<(), String> {
-    unsafe {
-        PALETTE_MAP_COLOR_ADDR = rb(va::PALETTE_CONTEXT_MAP_COLOR);
-
-        let _ = hook::install(
-            "ConstructSprite",
-            va::CONSTRUCT_SPRITE,
-            trampoline_construct_sprite as *const (),
-        )?;
-
-        let _ = hook::install(
-            "ProcessSprite",
-            va::PROCESS_SPRITE,
-            trampoline_process_sprite as *const (),
-        )?;
-    }
-    Ok(())
-}
-```
-
-- [ ] **Step 4: Build and verify**
-
-Run: `cargo build -p openwa-dll --release 2>&1 | tail -5`
-Expected: Compiles without errors.
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add crates/openwa-dll/src/replacements/sprite.rs
-git commit -m "feat: add ProcessSprite hook replacement with palette remapping"
-```
-
----
-
-### Task 6: Run Replay Tests
-
-**Files:** None (validation only)
-
-- [ ] **Step 1: Run all replay tests**
-
-Run: `powershell -ExecutionPolicy Bypass -File run-tests.ps1`
-Expected: All tests pass. If any fail, the sprite loading replacement has a bug.
-
-- [ ] **Step 2: If tests fail, diagnose**
-
-If a test shows `FAIL` (log mismatch), the sprite loading diverges from WA. Common causes:
-- Palette remapping producing different indices (check PaletteContext__MapColor bridge)
-- Global counter update order or values wrong
-- Bitmap remap byte count off by a few bytes
-- Alignment computation wrong for frame metadata offset
-
-If a test shows `CRASH`, check for stack corruption (wrong calling convention).
-
-Use `trace-desync` to find the exact divergent frame if needed:
-```
-powershell -ExecutionPolicy Bypass -File trace-desync.ps1 testdata/replays/<failing_replay>.WAgame
-```
-
-- [ ] **Step 3: Commit if all pass (final)**
-
-```bash
-git add -A
-git commit -m "feat: sprite parser and hook replacements for ConstructSprite + ProcessSprite"
-```
-
----
-
-## Known Risks
-
-1. **Palette remapping byte count**: WA computes `(data_size - bitmap_relative_offset + 3) / 4` dwords, which may process up to 3 bytes past the actual bitmap data. The implementation matches this behavior to avoid any divergence.
-
-2. **ECX = palette context**: ProcessSprite receives the palette context implicitly in ECX from LoadSpriteFromVfs. The `usercall_trampoline` with `regs = [eax, ecx]` captures both registers correctly.
-
-3. **Reading 4 bytes for RGB**: PaletteContext__MapColor receives a u32 where only the low 3 bytes are RGB. WA reads 4 bytes at each 3-byte-strided position (the 4th byte is garbage from the next entry or padding). This is safe because the function only uses `& 0xFFFFFF`.
-
-4. **Frame header location**: The main frame header's position depends on whether secondary frames exist. The code computes this position from `parse_spr_header`'s offsets, but the WA field copy (`*(u32*)(sprite+8) = *(u32*)(frame_header)`) needs the raw pointer to the frame header in the data buffer. This is computed by walking past palette + optional secondary frames.

docs/superpowers/specs/2026-03-15-ddgame-constructor-design.md

@@ -1,103 +0,0 @@
-# DDGame Constructor Port — Design Spec
-
-## Context
-
-DDGame (0x98B8 bytes) is the central game state object. Its constructor at
-0x56E220 is one of the largest remaining WA.exe dependencies — it allocates
-and initializes all gameplay subsystems (sprites, render queue, weapon table,
-coordinate lists, physics params, etc.).
-
-The init chain is already Rust up to this point:
-- `GameEngine__InitHardware` (hardware_init.rs) — creates display, sound, keyboard, palette
-- `DDGameWrapper__Constructor` (game_session.rs) — creates the wrapper, calls DDGame ctor via bridge
-
-The DDGame constructor is the last major bridge in the init path. Porting it
-to Rust means the entire game object creation is under our control.
-
-## Goal
-
-Replace `DDGame__Constructor` (0x56E220, stdcall 9 params + implicit ECX)
-with a Rust `DDGame::new()` that creates the object field by field. Use an
-incremental approach: port trivial inits immediately, bridge sub-constructor
-calls initially, and eliminate bridges one at a time.
-
-## Approach: Incremental Field-by-Field
-
-### Phase 1 — Decompile & Map
-
-1. Decompile DDGame__Constructor (0x56E220) fully in Ghidra
-2. Map every field write to our DDGame struct (already partially mapped in ddgame.rs)
-3. Categorize each initialization:
-   - **Trivial**: zero-fill, constant, pointer copy from params → port immediately
-   - **Sub-call**: allocates/inits a sub-object → bridge initially
-   - **Complex**: loops, conditionals, computed values → understand then port
-4. Add any missing struct fields discovered during decompilation
-5. Label all sub-functions called by the constructor in Ghidra
-
-### Phase 2 — Rust DDGame::new()
-
-1. Create `DDGame::new(params...) -> *mut DDGame` in openwa-core
-   - Allocates 0x98B8 bytes via `wa_malloc` (or `WABox<DDGame>`)
-   - Performs all trivial field initializations in Rust
-   - Calls WA sub-functions via typed bridge functions for complex parts
-2. Replace the `ddgame_constructor_call` naked bridge in game_session.rs
-   with a direct call to `DDGame::new()`
-3. Trap the original DDGame__Constructor (it should no longer be called)
-4. Verify with replay tests
-
-### Phase 3 — Bridge Elimination (iterative)
-
-Convert each bridged sub-call to pure Rust, simplest first:
-
-| Priority | Sub-call | Description |
-|----------|----------|-------------|
-| 1 | Field zero-fill regions | memset-style clears of large unknown regions |
-| 2 | Sprite cache init | Pointer array zeroing / allocation |
-| 3 | Coordinate list init | FUN_004FB3A0 — alloc + init capacity |
-| 4 | Object pool init | DDGame+0x600..0x3600 permutation arrays |
-| 5 | Render queue setup | Alloc + init the RenderQueue object |
-| 6 | Weapon table init | Alloc + populate weapon data tables |
-| 7 | Game state init | Complex conditional logic, terrain hooks |
-
-Each bridge elimination is a self-contained commit: convert, test, move on.
-
-## Parameters
-
-The constructor signature (from Ghidra + CLAUDE.md):
-```
-DDGame__Constructor(
-    this,           // allocated 0x98B8 bytes
-    keyboard,       // *mut DDKeyboard
-    display,        // *mut DDDisplay
-    sound,          // *mut DSSound (or null)
-    palette,        // *mut Palette
-    music,          // *mut Music (or null)
-    param7,         // unknown (0x1F4 observed)
-    caller,         // parent/caller pointer (often null)
-    game_info       // *mut GameInfo
-)
-// Implicit: ECX = network pointer (DDNetGameWrapper or null)
-// stdcall, RET 0x24 (9 stack params = 36 bytes)
-```
-
-## Critical Files
-
-| File | Action |
-|------|--------|
-| `crates/openwa-core/src/engine/ddgame.rs` | Add `DDGame::new()`, fill unknown fields |
-| `crates/openwa-dll/src/replacements/game_session.rs` | Replace bridge with `DDGame::new()` |
-| `crates/openwa-core/src/address.rs` | Add addresses for sub-functions |
-
-## Verification
-
-Each phase is verified independently:
-- **Headless replay test**: determinism preserved (byte-identical log output)
-- **Headful replay test**: game plays, no crashes, validation passes
-- **Manual gameplay**: start match, play a turn, verify no visual/audio glitches
-- **Struct assertions**: `size_of::<DDGame>() == 0x98B8` still holds
-
-## Risks
-
-- **Unknown fields**: DDGame has large unmapped regions (0x550..0x2600, 0x2E00..0x45EC, etc.). The constructor may write to fields we haven't identified. Mitigation: zero-fill unknowns and compare behavior.
-- **Sub-call ordering**: Some sub-calls may depend on fields set by earlier sub-calls. Mitigation: preserve exact ordering from the decompile.
-- **Implicit state**: ECX (network pointer) and global state may affect initialization. Mitigation: capture all implicit params in the bridge.

docs/superpowers/specs/2026-03-19-replay-loader-design.md

@@ -1,263 +0,0 @@
-# ReplayLoader Port Design
-
-## Summary
-
-Port `ReplayLoader` (0x462DF0) and `ParseReplayPosition` (0x4E3490) from WA.exe
-to Rust as hook-and-replace functions. ReplayLoader is a ~1800-line function that
-parses `.WAgame` replay files, validates their format, extracts team/scheme/map
-data, and produces `/getlog` formatted output. ParseReplayPosition is a small
-utility that converts `MM:SS.FF` time strings to frame counts at 50fps.
-
-## Target functions
-
-### ReplayLoader (0x462DF0)
-
-- **Signature:** `undefined4 ReplayLoader(uint param_1, int param_2)`
-- **Convention:** stdcall (`RET 0x8`, callee cleans 2 params). Also has a plain
-  `RET` at 0x465BC4 which is the SEH exception cleanup path.
-- **param_1:** Global game state struct at `0x87D3F8` (NOT DDGame). Always the
-  same global address — callers pass the literal constant `0x87D3F8`. The struct
-  holds replay/team/scheme state; its relationship to DDGame is that DDGame reads
-  from some of the same globals after ReplayLoader populates them.
-- **param_2:** Mode — 1=play, 2=getmap, 3=getscheme, 4=repair
-- **Returns:** 0 on success, negative error codes on failure
-
-Error codes:
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| -1 (0xFFFFFFFF) | File not found / read error |
-| -2 (0xFFFFFFFE) | Invalid format / validation failure |
-| -3 (0xFFFFFFFD) | Version too new / unsupported scheme version |
-| -4 (0xFFFFFFFC) | Malloc failure |
-| -5 (0xFFFFFFFB) | Map load failure |
-| -6 (0xFFFFFFFA) | DAT_0088c790 > 0x33 |
-| -7 (0xFFFFFFF9) | Repair with teams present |
-| -9 (0xFFFFFFF7) | No scheme in file / game type mismatch |
-| -8 (0xFFFFFFF8) | Not used by this function (gap in error codes) |
-| -10 (0xFFFFFFF6) | Scheme save failure |
-
-### ParseReplayPosition (0x4E3490)
-
-- **Signature:** `int ParseReplayPosition(char *param_1)`
-- **Convention:** stdcall (`RET 0x4`, callee cleans 1 param)
-- **Returns:** Frame count (50fps), or -1 on parse error
-- **Format:** `[H:]MM:SS[.FF]` — hours optional, fractional seconds optional
-
-## Function structure
-
-ReplayLoader breaks into 5 logical sections:
-
-### Section 1: Header & file I/O (~100 lines)
-
-1. Guard: `DAT_0088c790 > 0x33` → return -6
-2. Set `param_1+0xDB48 = 1` (replay active flag)
-3. Set `param_1+0xEF60 = 0` (init counter)
-4. `SetCurrentDirectoryA` to game data dir
-5. `fopen(param_1+0xDB60, "rb")` — replay file path
-6. Read 4-byte header: lower 16 bits must be `0x4157` ("WA")
-7. Version = upper 16 bits; must be ≤ 0x13 (19)
-8. Store version at `param_1+0xDB50`, `param_1+0xDB54`; set `param_1+0xDB58 = 0xFFFFFFFF`
-9. Read 4-byte payload size; validate against file size
-10. For modes 3/4: seek past payload. For modes 1/2: malloc + fread payload.
-
-### Section 2: Version 1 legacy path (~200 lines)
-
-When `version == 1`:
-- Read 4-byte team count from file, then 0x5728 bytes of team header into `0x8779E4`
-- Validate team count (1-6) and team type bounds
-- Iterate teams via `FUN_00461690` (team data reader)
-- Copy scheme defaults from `SCHEME_V3_DEFAULTS`
-- Read 0xD5D0-byte game state block via malloc, validate fields
-- Copy ~20 field groups from game state block into `param_1` at various offsets
-  (0x40, 0x44, 0x48C, 0x490, 0xD0FC, 0x4AF8, 0x4AFC, 0x4AFA, 0x8EFC, etc.)
-- Free temp buffer
-
-### Section 3: Version 2+ parsing (~500 lines)
-
-When `version >= 2`:
-1. Read second payload (team data) with size + content
-2. Parse sub-version flags and format indicators
-3. Read game version ID → `DAT_0088ABB0`; validate < 0x1F8
-4. Read scheme presence flag → `DAT_0088AE0C`
-5. If scheme present: read `SCHM` magic + version byte (1/2/3)
-   - Version 1/2: call `FUN_004613D0` (scheme reader), maybe set defaults
-   - Version 3: validate extended options via `Scheme__ValidateExtendedOptions`
-6. Read map seed byte, random state
-7. Read observer player names (up to 0xD teams, stride 0x78)
-8. Team iteration (up to 6 teams, stride 0xD7B at `0x878120`):
-   - Team flag byte, team type, alliance
-   - 5 sub-field reads via `FUN_00461540`
-   - Worm alliance byte
-   - Per-worm names: 8 worms × 0x11 bytes (or auto-generated for old versions)
-   - Worm count (validate 1-8), color, flag, grave, soundbank bytes
-   - Team name (0x40), team config name (0x40)
-   - Weapon data: 0x400 + 0x154 + 0x400 + 0x300 bytes
-9. Validate team count matches expected
-10. XOR integrity: `DAT_0088AF50 = payload_dword ^ 0xEF5B5C49`
-
-### Section 4: Post-parse & map load (~200 lines)
-
-1. If mode 1 (play): `Scheme__CheckWeaponLimits` validation
-2. If mode 3 (getscheme): version compatibility fixups, `Scheme__SaveFile`
-3. If mode 4 (repair): artclass name writing to replay file
-4. Map loading: read `playback.thm`, call map loader (`FUN_00490890`)
-5. Artclass index → terrain descriptor lookup via table at `0x6ACD38`
-6. Close file
-
-### Section 5: Log output (~600 lines)
-
-Generates `/getlog` formatted output to `DAT_0088C370` (log file handle):
-1. Date/time header via `_gmtime64`
-2. Version string lookup (negative IDs → hardcoded strings, positive → table at
-   `0x6AB480` or `0x6AB7A4` for BoomRacing mode)
-3. Format line: `"Game: <version> + <mods>..."` and `"Replay: <format>..."`
-4. Current WA version line: `"3.8.1"`
-5. Artclass line (if applicable)
-6. Per-team listing with alignment padding:
-   - Team flag letter (uppercased via codepage)
-   - Team name with quotes and padding
-   - Player name assignment
-   - CPU teams: difficulty level float
-   - Human teams: host/first markers
-7. Observer teams (negative team type)
-8. Final newline + flush
-
-**Critical:** This output must match byte-for-byte for headless replay testing.
-
-## Helper functions
-
-Several internal helpers are called repeatedly. These need bridges or ports:
-
-| Address | Name | Purpose | Approach | Convention |
-|---------|------|---------|----------|------------|
-| `0x461340` | ReadBytes | Read N bytes from stream cursor into buffer | Port | Verify during impl |
-| `0x4614D0` | ReadBytesValidated | Read + validate bounds | Port | Verify during impl |
-| `0x4615B0` | ReadU32Validated | Read u32 from stream | Port | Verify during impl |
-| `0x461540` | ReadByteRange | Read byte with signed range validation | Port | Verify during impl |
-| `0x461620` | ReadTeamWormAlliance | Read worm alliance data | Port | Verify during impl |
-| `0x461690` | ReadTeamData_V1 | Read team data (version 1 format) | Port | Verify during impl |
-| `0x466460` | ProcessTeamColors | Post-process team color assignments | Bridge | Verify (check RET) |
-| `0x4670F0` | ProcessSchemeDefaults | Apply scheme default values | Bridge | Verify (check RET) |
-| `0x467280` | ProcessReplayFlags | Process replay feature flags | Bridge | Verify (check RET) |
-| `0x467BC0` | RegisterObserverTeam | Register observer team entry | Bridge | Verify (check RET) |
-| `0x468890` | ProcessAllianceData | Process alliance/team setup | Bridge | Verify (check RET) |
-| `0x465E10` | ValidateTeamSetup | Validate team configuration | Bridge | Verify (check RET) |
-| `0x593180` | LoadStringResource | Load MFC string resource by ID | Bridge | Verify (check RET) |
-| `0x5978A0` | FormatString | sprintf-like string formatter | Bridge | Verify (check RET) |
-| `0x5978F0` | FormatString2 | Another format variant | Bridge | Verify (check RET) |
-
-**Note:** All helper function calling conventions must be verified via `RET imm16`
-disassembly before implementation. Wrong conventions cause stack corruption.
-
-**Policy:** Small functions (especially usercall) should be ported to Rust rather
-than bridged. Bridging usercall functions requires naked asm trampolines which add
-complexity and risk. Only bridge functions that are large or have many dependencies.
-
-## Global buffers written
-
-| Address | Size | Purpose |
-|---------|------|---------|
-| `0x87D3F8` | param_1 base | Game state struct (team/scheme/weapon data at various offsets) |
-| `0x8779E4` | 0x5728 | Team header data |
-| `0x87D438` | 0xD9DC | Secondary team/game data |
-| `0x88AF50` | 4 | XOR'd game ID |
-| `0x88AF54` | 4 | Replay sub-format flag |
-| `0x88ABB0` | 4 | Game version ID |
-| `0x88AE0C` | 4 | Scheme present flag |
-| `0x88DC04` | 0x6E | Scheme defaults buffer |
-| `0x88C790` | 4 | Version/ArtClass counter |
-| `0x88D0B4` | 4 | Random seed |
-| `0x88ABAC` | 4 | Saved random seed |
-
-## Implementation plan
-
-### Phase 0: Passthrough hook + ParseReplayPosition
-
-**Goal:** Validate calling convention, port the trivial function.
-
-1. Add `va::REPLAY_LOADER` and `va::PARSE_REPLAY_POSITION` to `address.rs`
-2. Add all replay-related global addresses to `address.rs`
-3. Create `replacements/replay.rs` with passthrough hook for ReplayLoader
-4. Port `ParseReplayPosition` as full Rust replacement
-5. Register in `replacements/mod.rs`
-6. Test: headful + headless replay
-
-### Phase 1: Header parsing + early returns
-
-**Goal:** Replace the header validation and mode routing in Rust.
-
-1. Port Section 1 (header & file I/O) to Rust
-2. For modes 2 (getmap) and 4 (repair): delegate to original via trampoline
-3. For mode 3 (getscheme): delegate to original initially
-4. For mode 1 (play): continue to Rust Section 2/3
-5. Test: headful replay with mode 1
-
-### Phase 2: Payload parsing (version 2+)
-
-**Goal:** Replace the core team/scheme data parsing.
-
-Focus on version 2+ path (version 1 is legacy, unlikely to be encountered):
-1. Port stream cursor helpers (ReadBytes, ReadU32, etc.) as Rust utilities
-2. Port the team iteration loop (6 teams × 0xD7B stride)
-3. Port scheme data reading (SCHM magic validation + delegation to existing bridges)
-4. Port weapon data block copies
-5. Bridge remaining sub-functions (ProcessTeamColors, ProcessSchemeDefaults, etc.)
-6. Test: headless determinism — game must play identically
-
-### Phase 3: Log output
-
-**Goal:** Reproduce /getlog formatted output byte-for-byte.
-
-This is the highest-risk phase. The output includes:
-- Codepage-aware character conversion
-- MFC string resources (localized strings)
-- Precise column alignment with padding
-- Version string table lookups
-- Date formatting via `_gmtime64`
-
-Approach:
-1. Start with a passthrough to the original log section
-2. Port incrementally, comparing output byte-for-byte via headless tests
-3. Use WA's own string resource functions via FFI bridges
-4. Test: headless diff must show zero differences
-
-## Verification
-
-| Phase | Test | Pass criteria |
-|-------|------|---------------|
-| 0 | Headful + headless replay | All existing validations pass, headless log matches |
-| 1 | Headful replay | Game loads and plays replay correctly |
-| 2 | Headless replay | Output log byte-identical to expected |
-| 3 | Headless replay | Output log byte-identical to expected |
-
-## Risks
-
-1. **Calling convention**: Confirmed stdcall (`RET 0x8`). The plain `RET` at
-   0x465BC4 is the SEH exception cleanup path, not the normal return.
-
-2. **C++ exception handling**: The version 2+ path uses `__CxxThrowException_8`
-   with SEH (`FS:[0]` exception chain) for validation errors. The version 1 path
-   uses direct returns. The SEH handler performs cleanup (freeing malloc'd buffers,
-   closing file handles) before returning the error code. The Rust replacement must
-   replicate this cleanup on every error path. Use a cleanup guard pattern (e.g., a
-   struct with `Drop` impl, or explicit cleanup before each early return) to ensure
-   no resource leaks.
-
-3. **Log output fidelity**: The /getlog output must match byte-for-byte. Codepage
-   conversion, string resources, and column alignment must be exact. This is the
-   hardest part and may require falling back to WA's own formatting functions.
-
-4. **Version 1 format**: Rarely encountered (pre-3.5 replays). Could be left as
-   a bridge to original initially, ported later if needed.
-
-5. **Helper function dependencies**: ~15 helper functions called. Trivial stream
-   helpers should be ported; complex ones (string resources, scheme processing)
-   should be bridged via FFI. All conventions must be verified before use.
-
-6. **Stdcall trampoline delegation**: When delegating to the original function for
-   unimplemented modes, the hook is `extern "stdcall"` and the MinHook trampoline
-   preserves the original stdcall convention. The Rust hook should call the
-   trampoline as a regular function pointer (the trampoline handles its own stack
-   cleanup internally — MinHook trampolines are designed for this). This is the
-   same pattern used by existing stdcall hooks in `game_state_hooks.rs`.

docs/superpowers/specs/2026-03-25-vtable-derive-design.md

@@ -1,337 +0,0 @@
-# Design: `#[vtable(...)]` System for OpenWA
-
-## Context
-
-OpenWA has 7+ manually-written vtable structs (`PaletteVtable`, `DisplayBaseVtable`, `DDDisplayVtable`, etc.) with hand-coded `#[repr(C)]` layouts, manual `impl` wrapper methods, and ad-hoc vtable patching. The existing `#[derive(FieldRegistry)]` macro and `inventory`-based registry provide a proven pattern for auto-generating struct metadata. This design extends that infrastructure to vtables, providing a single definition per vtable that handles introspection, calling, and replacement.
-
-**Constraints:**
-- A C++ class can have multiple vtables at different struct offsets (multiple inheritance)
-- The same vtable type can theoretically serve multiple classes
-- All vtable methods are `unsafe extern "thiscall"` (ECX = this)
-- Target is i686-pc-windows-msvc (32-bit, 4-byte pointers/fn pointers)
-
-## Design
-
-### 1. Vtable Definition (`#[vtable(...)]`)
-
-**Input syntax** — declare only known methods with `#[slot(N)]`:
-
-```rust
-#[openwa_core::vtable(size = 5, va = 0x0066_A2E4, class = "Palette")]
-pub struct PaletteVtable {
-    /// set_mode(this, mode) — called with mode=7 during hardware init
-    #[slot(2)]
-    pub set_mode: unsafe extern "thiscall" fn(*mut Palette, u32),
-    /// init(this) — called during hardware init
-    #[slot(3)]
-    pub init: unsafe extern "thiscall" fn(*mut Palette),
-    /// reset(this) — called first during hardware init
-    #[slot(4)]
-    pub reset: unsafe extern "thiscall" fn(*mut Palette),
-}
-```
-
-**Generated output:**
-
-```rust
-// 1. The actual #[repr(C)] struct with gap-fillers
-#[repr(C)]
-pub struct PaletteVtable {
-    pub _slot_0: usize,
-    pub _slot_1: usize,
-    /// set_mode(this, mode) — called with mode=7 during hardware init
-    pub set_mode: unsafe extern "thiscall" fn(*mut Palette, u32),
-    /// init(this) — called during hardware init
-    pub init: unsafe extern "thiscall" fn(*mut Palette),
-    /// reset(this) — called first during hardware init
-    pub reset: unsafe extern "thiscall" fn(*mut Palette),
-}
-
-// 2. Registry integration (introspection)
-impl HasVtableRegistry for PaletteVtable {
-    fn vtable_info() -> &'static VtableInfo {
-        static INFO: VtableInfo = VtableInfo {
-            struct_name: "PaletteVtable",
-            class_name: "Palette",
-            ghidra_va: 0x0066_A2E4,
-            slot_count: 5,
-            slots: &[
-                VtableSlotEntry { index: 2, name: "set_mode", doc: "set_mode(this, mode) ..." },
-                VtableSlotEntry { index: 3, name: "init", doc: "init(this) ..." },
-                VtableSlotEntry { index: 4, name: "reset", doc: "reset(this) ..." },
-            ],
-        };
-        &INFO
-    }
-}
-
-inventory::submit!(VtableRegistration {
-    info: <PaletteVtable as HasVtableRegistry>::vtable_info(),
-});
-
-// 3. Address registry entry (replaces define_addresses! for this vtable)
-inventory::submit!(AddrEntry {
-    va: 0x0066_A2E4,
-    name: "PALETTE_VTABLE",
-    kind: AddrKind::Vtable,
-    class_name: Some("Palette"),
-    calling_convention: None,
-});
-
-// 4. Companion binding macro (see Part 2)
-#[macro_export]
-macro_rules! bind_PaletteVtable { ... }
-```
-
-**Proc macro implementation** in `openwa-derive/src/lib.rs`:
-- Parse `#[vtable(...)]` attributes for `size`, `va` (optional), `class` (optional)
-- Parse `#[slot(N)]` on each field to determine position
-- Validate: no duplicate slots, all slots < size, slot indices ascending
-- Generate gap-filler fields `_slot_N: usize` for missing indices
-- Preserve doc comments, visibility, and field types from input
-- Generate compile-time size assertion: `const _: () = assert!(size_of::<VtableName>() == size * 4);`
-- Parse fn pointer types to extract `this` type (`*mut T` or `*const T`), params, and return type
-- Generate `HasVtableRegistry` impl, inventory submissions, and binding macro
-- If `va` is provided: generate `pub const` and `AddrEntry` submission. Name derived from `class` attribute: `"Palette"` → `PALETTE_VTABLE`. If no `class`, derive from struct name: `PaletteVtable` → `PALETTE_VTABLE`
-- If `va` is omitted: no `AddrEntry`, no const — vtable exists purely as a type
-
-### 2. Calling Wrappers (`bind_XxxVtable!`)
-
-The derive generates a companion macro named `bind_{VtableName}!` that creates method wrappers:
-
-```rust
-// Generated by #[derive(Vtable)] on PaletteVtable:
-#[macro_export]
-macro_rules! bind_PaletteVtable {
-    ($class:ty, $vtable_field:ident) => {
-        impl $class {
-            #[doc = "set_mode(this, mode) — called with mode=7 during hardware init"]
-            pub unsafe fn set_mode(&mut self, mode: u32) {
-                ((*self.$vtable_field).set_mode)(self as *mut Self, mode)
-            }
-            #[doc = "init(this) — called during hardware init"]
-            pub unsafe fn init(&mut self) {
-                ((*self.$vtable_field).init)(self as *mut Self)
-            }
-            #[doc = "reset(this) — called first during hardware init"]
-            pub unsafe fn reset(&mut self) {
-                ((*self.$vtable_field).reset)(self as *mut Self)
-            }
-        }
-    };
-}
-```
-
-**Usage:**
-```rust
-// In palette.rs, after struct Palette { vtable: *const PaletteVtable, ... }
-bind_PaletteVtable!(Palette, vtable);
-
-// Now you can write:
-(*pal).set_mode(7);   // instead of vcall!(pal, set_mode, 7)
-(*pal).init();
-(*pal).reset();
-```
-
-**Multiple vtables (multiple inheritance):**
-```rust
-// CGameTask has primary vtable at +0x00
-bind_CGameTaskVtable!(CGameTask, vtable);
-
-// SoundEmitter is a sub-object with its own vtable — bind on its own struct
-bind_SoundEmitterVTable!(SoundEmitter, vtable);
-```
-
-**Method signature extraction:** The proc macro parses the fn pointer type as `syn::Type::BareFn` to extract:
-- First param is `this` — if `*const T`, generates `&self`; if `*mut T`, generates `&mut self`
-- Remaining params become the wrapper's named parameters (e.g., `p0: u32`, `p1: *mut u8`)
-- Return type is preserved (default `()` if absent)
-- The wrapper calls through `self.$vtable_field` and casts `self` to the correct pointer type
-
-**Type safety:** The binding macro passes `self as *mut Self` (or `*const Self`) as the `this` argument. The `$class` type passed to the macro must match the `this` pointer type in the vtable fn signatures. If mismatched, Rust's pointer cast rules apply silently — the macro does not enforce this, but the mismatch would be visible at the invocation site.
-
-**Note on `&mut self`:** This follows the existing hand-written pattern (e.g., `Palette::reset(&mut self)`). Using `&mut self` creates a mutable reference from what is often a raw pointer, which could theoretically violate aliasing rules. This is acceptable for this project since all callers are already in `unsafe` blocks working with raw game memory, and the `vcall!` macro remains available for raw-pointer-only dispatch.
-
-### 3. Vtable Replacement (`vtable_replace!`)
-
-A declarative macro that expands to executable code for use inside `install()` functions:
-
-```rust
-pub fn install() -> Result<(), String> {
-    unsafe {
-        vtable_replace!(PaletteVtable at va::PALETTE_VTABLE {
-            slot set_mode => my_set_mode,
-            slot init => my_init,
-        })?;
-    }
-    Ok(())
-}
-```
-
-**Expanded code** (for `slot 2 => my_set_mode` — pure replace, no original saved):
-
-```rust
-{
-    let vtable_ptr = $crate::rebase::rb(va::PALETTE_VTABLE) as *mut u32;
-    let slot_count = core::mem::size_of::<PaletteVtable>() / 4;
-    $crate::vtable::patch_vtable(vtable_ptr, slot_count, |vt| {
-        // Slot 2: pure replace
-        let slot = vt.add(2);
-        *slot = my_set_mode as *const () as u32;
-    })
-}
-```
-
-**Expanded code** (for `slot 3 [originals::INIT] => my_init` — replace + save original):
-
-```rust
-{
-    let vtable_ptr = $crate::rebase::rb(va::PALETTE_VTABLE) as *mut u32;
-    let slot_count = core::mem::size_of::<PaletteVtable>() / 4;
-    $crate::vtable::patch_vtable(vtable_ptr, slot_count, |vt| {
-        // Slot 3: save original, then replace
-        let slot = vt.add(3);
-        originals::INIT.store(*slot, core::sync::atomic::Ordering::Relaxed);
-        *slot = my_init as *const () as u32;
-    })
-}
-```
-
-**Calling the original:** User defines statics in a visible scope and passes them via `[static]` syntax:
-
-```rust
-mod originals {
-    pub static INIT: core::sync::atomic::AtomicU32 =
-        core::sync::atomic::AtomicU32::new(0);
-}
-
-vtable_replace!(PaletteVtable at va::PALETTE_VTABLE {
-    slot 2 => my_set_mode,                          // no original needed
-    slot 3 [originals::INIT] => my_init,            // save original
-})?;
-
-// In the replacement:
-unsafe extern "thiscall" fn my_init(this: *mut Palette) {
-    log!("init()");
-    let orig: unsafe extern "thiscall" fn(*mut Palette) =
-        core::mem::transmute(originals::INIT.load(Ordering::Relaxed));
-    orig(this);
-}
-```
-
-The `[static_name]` syntax is optional — if omitted, no original is saved (pure replacement, no call-through). The macro does NOT generate inaccessible statics.
-
-**Slot index resolution:** Slot indices are specified explicitly in the macro call. This is compile-time, simple, and the indices are directly visible in the vtable definition above.
-
-**Size derivation:** The `size` parameter is NOT required — the macro computes it as `size_of::<VtableType>() / 4` from the vtable struct type, which already encodes the correct size via `#[vtable(size = N)]`.
-
-Revised syntax:
-```rust
-vtable_replace!(PaletteVtable at va::PALETTE_VTABLE {
-    slot 2 => my_set_mode,                         // pure replace, original discarded
-    slot 3 [originals::INIT] => my_init,           // replace + save original to static
-})?;
-```
-
-### 4. New Types in `openwa-core::registry`
-
-```rust
-/// Metadata for a single vtable slot
-pub struct VtableSlotEntry {
-    pub index: u32,
-    pub name: &'static str,
-    pub doc: &'static str,
-}
-
-/// Metadata for a vtable struct
-pub struct VtableInfo {
-    pub struct_name: &'static str,
-    pub class_name: &'static str,
-    pub ghidra_va: u32,
-    pub slot_count: u32,
-    pub slots: &'static [VtableSlotEntry],
-}
-
-impl VtableInfo {
-    pub fn slot_by_name(&self, name: &str) -> Option<&VtableSlotEntry> { ... }
-    pub fn slot_by_index(&self, index: u32) -> Option<&VtableSlotEntry> { ... }
-}
-
-/// Trait implemented by #[derive(Vtable)] structs
-pub trait HasVtableRegistry {
-    fn vtable_info() -> &'static VtableInfo;
-}
-
-/// Inventory collection wrapper
-pub struct VtableRegistration {
-    pub info: &'static VtableInfo,
-}
-inventory::collect!(VtableRegistration);
-
-/// Query API
-pub fn vtable_info_for(struct_name: &str) -> Option<&'static VtableInfo> { ... }
-pub fn all_vtable_info() -> impl Iterator<Item = &'static VtableInfo> { ... }
-```
-
-### 5. `vtable::patch_vtable` Helper
-
-Move/generalize the existing vtable patching logic from `display.rs` into a shared utility:
-
-```rust
-// openwa-core::vtable (new module)
-
-/// Temporarily makes a vtable writable, calls the patcher, restores protection.
-/// Returns Err if VirtualProtect fails.
-pub unsafe fn patch_vtable(
-    vtable_ptr: *mut u32,
-    slot_count: usize,
-    patcher: impl FnOnce(*mut u32),
-) -> Result<(), String> {
-    let size = slot_count * 4;
-    let mut old_protect = 0u32;
-    if VirtualProtect(vtable_ptr as _, size, PAGE_READWRITE, &mut old_protect) == 0 {
-        return Err("VirtualProtect failed".into());
-    }
-    patcher(vtable_ptr);
-    VirtualProtect(vtable_ptr as _, size, old_protect, &mut old_protect);
-    Ok(())
-}
-```
-
-This already exists in `display.rs` — factor it out.
-
-## File Changes
-
-| File | Change |
-|------|--------|
-| `crates/openwa-derive/src/lib.rs` | Add `#[vtable(...)]` proc macro (~150 lines) |
-| `crates/openwa-core/src/registry.rs` | Add `VtableInfo`, `VtableSlotEntry`, `HasVtableRegistry`, `VtableRegistration`, query API (~60 lines) |
-| `crates/openwa-core/src/vtable.rs` | New module: `patch_vtable` helper (factored from display.rs) |
-| `crates/openwa-core/src/macros.rs` | Add `vtable_replace!` macro (~40 lines) |
-| `crates/openwa-core/src/lib.rs` | Add `pub mod vtable;`, re-export `Vtable` derive |
-
-## Migration: PaletteVtable (first target)
-
-1. Rewrite `PaletteVtable` in `display/palette.rs` to use `#[vtable(...)]`
-2. Add `bind_PaletteVtable!(Palette, vtable)` — replaces 3 manual wrapper methods
-3. Remove the `define_addresses!` entry for `PALETTE_VTABLE_MAYBE` (now in derive attribute)
-4. Verify `vcall!(pal, set_mode, 7)` still works (struct layout identical)
-5. Run replay tests
-
-## Migration Order (after Palette)
-
-1. `InputCtrlVtable` (1 slot) — trivial
-2. `MapViewVtable` (2 slots) — trivial
-3. `SoundEmitterVTable` (12 slots, 5 known)
-4. `DisplayBaseVtable` (32 slots, all typed)
-5. `DSSoundVtable` (24 slots)
-6. `DDDisplayVtable` (38 slots)
-7. `CTaskWormVTable` (20+ slots)
-
-## Verification
-
-- `cargo build -p openwa-core` — types compile
-- `cargo test -p openwa-core` — existing tests pass
-- `cargo build -p openwa-dll --release` — DLL builds
-- `.\run-tests.ps1` — replay tests pass (no desync from layout changes)
-- Validate introspection: `vtable_info_for("PaletteVtable")` returns correct slot metadata

docs/superpowers/specs/2026-04-01-sprite-parser-design.md

@@ -1,127 +0,0 @@
-# Sprite Parser Design
-
-Port WA's `.spr` sprite loading to a clean Rust parser with WormKit hook replacements.
-
-## Goal
-
-1. A pure Rust `.spr` parser (`ParsedSprite`) in `openwa-core` — no WA dependencies, usable in tests/tooling
-2. Hook replacements for `ConstructSprite` (0x4FAA30) and `ProcessSprite` (0x4FAB80) — WA calls our code instead of its own
-
-## .spr File Format
-
-Binary format parsed by ProcessSprite (0x4FAB80):
-
-```
-Offset  Size     Field
-+0x00   4        (unused / magic)
-+0x04   4 (u32)  data_size — accumulated in global counter at 0x7A0864
-+0x08   2 (u16)  header_flags → sprite+0x14
-+0x0A   2 (u16)  palette_entry_count
-+0x0C   3 * N    palette entries (3 bytes each, RGB)
-...     varies   frame metadata (SpriteFrame, 0x0C bytes each)
-...     varies   bitmap pixel data (8-bit indexed)
-```
-
-Special flags:
-- **0x4000** in header_flags: secondary frame table present before primary frames.
-  First word after palette = secondary frame count, followed by 0x0C-byte entries.
-- **Negative frame count** (bit 15 set): scaling mode.
-  High 7 bits = scale_x, low 7 bits = scale_y. Actual frame_count set to 1.
-  Scale values stored as `(raw_value << 16) >> 5`.
-
-## ParsedSprite Type
-
-New file `crates/openwa-core/src/render/spr.rs`:
-
-```rust
-pub enum SprError {
-    TooShort,
-    InvalidData(&'static str),
-}
-
-pub struct ParsedSprite {
-    pub fps: u16,
-    pub width: u16,
-    pub height: u16,
-    pub flags: u16,
-    pub header_flags: u16,
-    pub frame_count: u16,
-    pub max_frames: u16,
-    pub scale_x: u32,           // raw 7-bit value; 0 if not scaled
-    pub scale_y: u32,           // raw 7-bit value; 0 if not scaled
-    pub is_scaled: bool,
-    pub frames: Vec<SpriteFrame>,
-    pub secondary_frames: Vec<SpriteFrame>,  // non-empty iff header_flags & 0x4000
-    pub bitmap: Vec<u8>,        // 8-bit indexed pixels, same layout as WA
-    pub palette: Vec<[u8; 3]>,  // RGB triples
-    pub data_size: u32,         // from .spr +0x04, for global counter updates
-}
-```
-
-`ParsedSprite::parse(data: &[u8]) -> Result<Self, SprError>` — pure function, no WA dependencies, no `#[cfg(target_arch)]`.
-
-## Hook Adapter
-
-In `spr.rs`, gated by `#[cfg(target_arch = "x86")]`:
-
-```rust
-pub unsafe fn populate_wa_sprite(sprite: *mut Sprite, parsed: &ParsedSprite) { ... }
-```
-
-- Copies scalar fields (fps, width, height, flags, etc.) into the WA Sprite struct
-- `wa_malloc` + `memcpy` for frame metadata, bitmap data, palette data
-- Applies scale transform: `(raw_value << 16) >> 5` for scale_x/scale_y
-- Updates 4 global counters: `G_SPRITE_DATA_BYTES`, `G_SPRITE_FRAME_COUNT`, `G_SPRITE_PIXEL_AREA`, `G_SPRITE_PALETTE_BYTES`
-
-Pixel data is copied verbatim — no format conversion needed.
-
-## Hook Replacements
-
-New file `crates/openwa-dll/src/replacements/sprite.rs`:
-
-### ConstructSprite (0x4FAA30)
-
-Convention: `__usercall` — EAX=sprite, ECX=context.
-
-Replacement:
-- Set vtable to `rb(0x66418C)`
-- Set DisplayGfx vtable at +0x34 to `rb(0x664144)`
-- Zero all other fields
-
-Trampoline: `usercall_trampoline!(regs = [eax, ecx])`.
-
-### ProcessSprite (0x4FAB80)
-
-Convention: `__usercall` — EAX=sprite, 1 stack param (raw data pointer).
-
-Replacement:
-1. Determine raw data extent (bitmap data extends to end of allocation — length comes from context)
-2. Call `ParsedSprite::parse(data)`
-3. Call `populate_wa_sprite(sprite, &parsed)`
-4. On parse error: log and panic (corrupt game data, should never happen)
-
-Trampoline: `usercall_trampoline!(reg = eax; stack_params = 1; ret_bytes = "0x4")`.
-
-## Open Question: Data Length
-
-ProcessSprite receives a raw data pointer but no explicit length. The caller (`LoadSpriteFromVfs`) allocates the buffer and knows its size. Options:
-- Parse defensively using `data_size` from the header (+0x04) to bound reads
-- Hook `LoadSpriteFromVfs` to pass length through (out of scope for now)
-- The parser can derive bounds from internal fields (palette count, frame count, bitmap offsets)
-
-Recommended: use internal fields to derive bounds. The `data_size` header field gives total size. Validate reads against it.
-
-## File Changes
-
-| File | Change |
-|---|---|
-| `crates/openwa-core/src/render/spr.rs` | New: `ParsedSprite`, `SprError`, `parse()`, `populate_wa_sprite()` |
-| `crates/openwa-core/src/render/mod.rs` | Add `pub mod spr;` |
-| `crates/openwa-dll/src/replacements/sprite.rs` | New: hook trampolines + `install()` |
-| `crates/openwa-dll/src/replacements/mod.rs` | Wire `sprite::install()` |
-
-## Verification
-
-- **Unit tests** in `openwa-core`: synthetic `.spr` payloads (single frame, multi-frame, scaled, secondary frames)
-- **Replay tests**: `.\run-tests.ps1` — all existing replays must pass byte-for-byte (global counters and sprite state must match exactly)
-- If replays show desyncs, use `trace-desync` to identify the divergent frame