feat: replace PostMessage replay fast-forward with DDGame+0x98B0 hook

Hook TurnManager_ProcessFrame to set DDGame.fast_forward_active=1 each
frame, enabling 50x speed processing (same mechanism as spacebar).
Add fast_forward_active field to DDGame struct. Auto-restore minimized
window via FindWindowA+ShowWindow at 2s.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.claude/skills/replay-test/SKILL.md

@@ -19,10 +19,10 @@ This will:
 - Build the unified openwa-wormkit DLL (includes validation)
 - Deploy wkOpenWA.dll to the WA game directory
 - Set `OPENWA_VALIDATE=1` and `OPENWA_REPLAY_TEST=1` env vars
-- Launch WA.exe with the default replay file (testdata/replays/bots.WAgame)
-- Fast-forward through the entire replay via PostMessage (spacebar down/up with 50ms gaps)
-- The DLL calls SetForegroundWindow to ensure WA processes keyboard messages
-- Game exits naturally when replay finishes (150s safety timeout)
+- Launch WA.exe minimized with the default replay file (testdata/replays/bots.WAgame)
+- The DLL restores the window after 2s via FindWindowA + ShowWindow(SW_RESTORE)
+- Fast-forward through the entire replay by setting DDGame+0x98B0 (50 frames per render cycle)
+- Validation runs at the 5s mark, game exits when replay finishes (120s safety timeout)
 - Copy logs to testdata/logs/
 
 2. Read the validation log and present results:
@@ -38,14 +38,15 @@ Read `testdata/logs/validation_latest.log` and summarize:
 ## Environment Variables
 
 - `OPENWA_VALIDATE=1` — Enables the validation module (struct checks, vtable validation, memory dumps). Without this, only the replacement hooks run.
-- `OPENWA_REPLAY_TEST=1` — Enables fast-forward mode: posts WM_KEYDOWN/WM_KEYUP messages to advance the replay one turn per press. Runs validation dumps at 8s. Safety timeout at 120s forces ExitProcess(1). Without this, validation runs in interactive mode with hotkeys (F9=team blocks, F10=landscape).
+- `OPENWA_REPLAY_TEST=1` — Enables fast-forward mode: hooks TurnManager_ProcessFrame and sets DDGame+0x98B0=1 each frame, causing the game engine to process up to 50 frames per render cycle. The DLL auto-restores the window at 2s, runs validation at 5s, and has a 120s safety timeout. Without this, validation runs in interactive mode with hotkeys (F9=team blocks, F10=landscape).
 
 Both are set automatically by `replay-test.ps1`.
 
 ## Notes
 
-- The fast-forwarded replay typically completes in ~10-15s
-- The DLL restores and focuses the game window (steals focus briefly) so PostMessage input works
+- The fast-forwarded replay typically completes in ~15-30s
+- The DLL restores the minimized window automatically (steals focus briefly)
 - There is only one DLL now: `wkOpenWA.dll` (unified wormkit + validator)
 - The old `wkOpenWAValidator.dll` is automatically removed by the script
-- Replay file can be changed by editing the script invocation: `powershell -File replay-test.ps1 path\to\other.WAgame`
+- Replay file can be changed: `powershell -File replay-test.ps1 path\to\other.WAgame`
+- Occasional crashes may occur during fast-forward (null vtable calls from 50x speed processing); retry if this happens

CLAUDE.md

@@ -55,7 +55,7 @@ powershell -ExecutionPolicy Bypass -File replay-test.ps1
 
 How it works:
 1. `replay-test.ps1` builds the unified DLL, deploys to game dir, sets `OPENWA_VALIDATE=1` and `OPENWA_REPLAY_TEST=1`, launches `WA.exe` minimized with a replay file
-2. The DLL posts WM_KEYDOWN/WM_KEYUP spacebar messages (50ms gaps) to fast-forward the replay, calls SetForegroundWindow so input works even when launched minimized. Validation dumps run at 8s. The replay typically finishes in ~10-15s
+2. The DLL restores the window after 2s via FindWindowA + ShowWindow(SW_RESTORE), then hooks TurnManager_ProcessFrame and sets DDGame+0x98B0=1 each frame to enable 50x fast-forward (same mechanism as spacebar during replay). Validation runs at 5s. The replay typically finishes in ~15-30s
 3. Script copies logs to `testdata/logs/` and prints a PASS/FAIL summary
 
 Key paths:
@@ -66,7 +66,7 @@ Key paths:
 
 Environment variables:
 - `OPENWA_VALIDATE=1` — Enable validation module (struct checks, vtable validation, memory dumps)
-- `OPENWA_REPLAY_TEST=1` — Fast-forward mode: posts spacebar messages to advance replay, runs validation dumps at 8s, 120s safety timeout. Without this, validation runs interactively with hotkeys (F9=team blocks, F10=landscape)
+- `OPENWA_REPLAY_TEST=1` — Fast-forward mode: hooks TurnManager_ProcessFrame and sets DDGame+0x98B0=1 each frame (50x speed). Restores window at 2s, runs validation at 5s, 120s safety timeout. Without this, validation runs interactively with hotkeys (F9=team blocks, F10=landscape)
 
 ## Crate Architecture
 

crates/openwa-types/src/address.rs

@@ -428,6 +428,9 @@ pub mod va {
 
     pub const LOBBY_HOST_COMMANDS: u32 = 0x004B_9B00;
     pub const LOBBY_CLIENT_COMMANDS: u32 = 0x004A_ABB0;
+    /// Allocates space in a packet queue and writes the packet type + data.
+    /// __usercall: EAX = queue pointer, ECX = data size. Stack: packet_type, data_ptr.
+    /// Returns 1 on success, 0 if queue full. RET 0x8.
     pub const SEND_GAME_PACKET_WRAPPED: u32 = 0x0054_1130;
     pub const LOBBY_DISPLAY_MESSAGE: u32 = 0x0049_3CB0;
     pub const LOBBY_SEND_GREENTEXT: u32 = 0x004A_A990;
@@ -575,12 +578,17 @@ pub mod va {
         /// Offset to weapon panel pointer
         pub const WEAPON_PANEL: u32 = 0x548;
 
-        // --- Replay state ---
-
         /// Deferred hurry flag. Set to 1 during replay instead of sending network
         /// packet. GameFrameEndProcessor (0x531960) reads this and converts it to
         /// a local Hurry message (TaskMessage 0x17 = 23).
         pub const DEFERRED_HURRY_FLAG: u32 = 0x7E41;
+    }
+
+    // === GameInfo struct offsets ===
+    // These are offsets from the GameInfo pointer at DDGame+0x24 (also called
+    // "game_state" in some code). Access pattern: *(DDGame+0x24) + offset.
+
+    pub mod game_info_offsets {
         /// Replay state flag A — checked by TurnGame_HurryHandler and FrameFinish.
         /// Both DB08 and DB0A must be non-zero for replay-mode hurry path.
         pub const REPLAY_STATE_FLAG_A: u32 = 0xDB08;

crates/openwa-types/src/ddgame.rs

@@ -102,12 +102,24 @@ pub struct DDGame {
     /// 0x8150: Scale factor used by DrawCrosshairLine (multiplied by 0x140000).
     pub crosshair_scale: i32,
 
-    /// 0x8154-0x98B7: Remaining fields
+    /// 0x8154-0x98AF: Remaining fields
     ///
     /// Known landmarks:
     /// - 0x8CBC-0x8CF0: 4x 0x10-byte entries (zeroed at +0, +4)
     /// - 0x9850-0x9884: 4x 0x10-byte entries (zeroed at +0, +4)
-    pub _unknown_8154: [u8; 0x98B8 - 0x8154],
+    /// - 0x98A4: checkpoint active flag
+    /// - 0x98AC: fast-forward request flag
+    pub _unknown_8154: [u8; 0x98B0 - 0x8154],
+
+    /// 0x98B0: Fast-forward active flag.
+    /// When set to 1, FUN_005307A0 processes up to 50 game frames per render
+    /// cycle. Sound is suppressed and rendering is skipped. Cleared at turn
+    /// boundaries (FUN_00534540, FUN_0055BDD0), so must be re-set continuously.
+    /// This is the same flag toggled by spacebar (key 0x35) during replay.
+    pub fast_forward_active: u32,
+
+    /// 0x98B4-0x98B7: Unknown
+    pub _unknown_98b4: [u8; 0x98B8 - 0x98B4],
 }
 
 const _: () = assert!(core::mem::size_of::<DDGame>() == 0x98B8);
@@ -177,6 +189,10 @@ pub mod offsets {
     /// Scale factor used by DrawCrosshairLine (multiplied by 0x140000).
     pub const CROSSHAIR_SCALE: usize = 0x8150;
 
+    // === Fast-forward (DDGame + 0x98B0) ===
+    /// Fast-forward active flag (u32, 1 = active).
+    pub const FAST_FORWARD_ACTIVE: usize = 0x98B0;
+
     // === Sound queue (DDGame + 0x7F00) ===
     /// Sound enabled flag (i32, nonzero = enabled).
     pub const SOUND_ENABLED: usize = 0x0008;

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

@@ -1,53 +1,67 @@
-//! Input hooks for replay fast-forward.
+//! Replay fast-forward via DDGame+0x98B0.
 //!
-//! When `OPENWA_REPLAY_TEST=1`, posts WM_KEYDOWN/WM_KEYUP messages for
-//! spacebar to the game's window, advancing the replay one turn per press.
+//! When `OPENWA_REPLAY_TEST=1`, hooks TurnManager_ProcessFrame (0x55FDA0)
+//! and sets DDGame+0x98B0 (fast-forward active flag) each frame.
 //!
-//! The key-down and key-up must land in SEPARATE game frames so the game
-//! sees a stable "pressed" state for at least one frame before release.
-//! WA runs at 50fps (~20ms/frame), so we use 50ms gaps between down/up.
+//! When this flag is set, FUN_005307A0 processes up to 50 game frames per
+//! render cycle. Sound is suppressed (FUN_00546B50) and rendering is skipped
+//! (FUN_00529F30). The flag gets cleared at turn boundaries (FUN_00534540,
+//! FUN_0055BDD0), so we re-set it every frame.
 //!
-//! To work without stealing focus, we subclass the game's WndProc to
-//! intercept WM_ACTIVATE/WM_ACTIVATEAPP and make WA think it always has
-//! focus. This allows PostMessage input to work even when the window is
-//! in the background.
-//!
-//! Activation is delayed ~3s after DLL load to let WA reach gameplay.
-
-use crate::log_line;
-
-const VK_SPACE: u32 = 0x20;
-const WM_KEYDOWN: u32 = 0x0100;
-const WM_KEYUP: u32 = 0x0101;
-const WM_ACTIVATE: u32 = 0x0006;
-const WM_ACTIVATEAPP: u32 = 0x001C;
-const WA_ACTIVE: u32 = 1;
-const GWL_WNDPROC: i32 = -4;
-const SW_RESTORE: i32 = 9;
+//! This is the same mechanism triggered by key 0x35 (spacebar) during replay.
 
-/// Original WndProc, saved when we subclass the window.
-static mut ORIG_WNDPROC: u32 = 0;
+use std::sync::atomic::{AtomicU32, Ordering};
 
-/// Our WndProc wrapper: intercepts deactivation messages so WA thinks
-/// it always has focus, then forwards everything to the original.
-unsafe extern "system" fn hook_wndproc(hwnd: u32, msg: u32, wparam: u32, lparam: u32) -> u32 {
-    extern "system" {
-        fn CallWindowProcA(lpPrevWndFunc: u32, hWnd: u32, msg: u32, wParam: u32, lParam: u32) -> u32;
+use crate::hook;
+use crate::log_line;
+use openwa_lib::rebase::rb;
+use openwa_types::address::va;
+use openwa_types::ddgame::DDGame;
+
+/// Trampoline to the original TurnManager_ProcessFrame.
+static ORIG_TURN_MANAGER: AtomicU32 = AtomicU32::new(0);
+
+/// Get the DDGame pointer (session+0xA0 → DDGameWrapper+0x488).
+#[inline]
+unsafe fn get_ddgame() -> *mut DDGame {
+    let session = *(rb(va::G_GAME_SESSION) as *const u32);
+    if session == 0 {
+        return core::ptr::null_mut();
+    }
+    let wrapper = *((session + 0xA0) as *const u32);
+    if wrapper == 0 {
+        return core::ptr::null_mut();
     }
+    *((wrapper + 0x488) as *const *mut DDGame)
+}
 
-    match msg {
-        WM_ACTIVATE => {
-            // Always tell WA it's being activated (WA_ACTIVE=1)
-            return CallWindowProcA(ORIG_WNDPROC, hwnd, msg, WA_ACTIVE, lparam);
-        }
-        WM_ACTIVATEAPP => {
-            // Always tell WA the app is being activated (wParam=TRUE)
-            return CallWindowProcA(ORIG_WNDPROC, hwnd, msg, 1, lparam);
-        }
-        _ => {}
+/// Hook for TurnManager_ProcessFrame (stdcall, 1 param = TurnGame*).
+///
+/// Called every frame from TurnGame_HandleMessage case 2 (FrameFinish).
+/// Sets DDGame.fast_forward_active = 1 to enable multi-frame processing.
+unsafe extern "stdcall" fn hook_turn_manager(turngame: u32) {
+    static DIAG_COUNT: AtomicU32 = AtomicU32::new(0);
+
+    // Call original first
+    let orig: unsafe extern "stdcall" fn(u32) =
+        core::mem::transmute(ORIG_TURN_MANAGER.load(Ordering::Relaxed));
+    orig(turngame);
+
+    let ddgame = get_ddgame();
+    if ddgame.is_null() {
+        return;
     }
 
-    CallWindowProcA(ORIG_WNDPROC, hwnd, msg, wparam, lparam)
+    // Set fast-forward active flag
+    (*ddgame).fast_forward_active = 1;
+
+    let diag = DIAG_COUNT.fetch_add(1, Ordering::Relaxed);
+    if diag == 0 {
+        let _ = log_line(&format!(
+            "[Input] Fast-forward active (DDGame=0x{:08X})",
+            ddgame as u32
+        ));
+    }
 }
 
 pub fn install() -> Result<(), String> {
@@ -55,72 +69,16 @@ pub fn install() -> Result<(), String> {
         return Ok(());
     }
 
-    let _ = log_line("[Input] Replay test mode — will post spacebar messages for fast-forward");
+    let _ = log_line("[Input] Replay test mode — hooking TurnManager_ProcessFrame for fast-forward");
 
-    extern "system" {
-        fn FindWindowA(lpClassName: *const u8, lpWindowName: *const u8) -> u32;
-        fn PostMessageA(hWnd: u32, msg: u32, wParam: u32, lParam: u32) -> i32;
-        fn SetForegroundWindow(hWnd: u32) -> i32;
-        fn ShowWindow(hWnd: u32, nCmdShow: i32) -> i32;
-        fn SetWindowLongA(hWnd: u32, nIndex: i32, dwNewLong: u32) -> u32;
+    unsafe {
+        let trampoline = hook::install(
+            "TurnManager_ProcessFrame",
+            va::TURN_MANAGER_PROCESS_FRAME,
+            hook_turn_manager as *const (),
+        )?;
+        ORIG_TURN_MANAGER.store(trampoline as u32, Ordering::Relaxed);
     }
 
-    std::thread::spawn(move || {
-        let _ = log_line("[Input] Waiting 1s before enabling fast-forward...");
-        std::thread::sleep(std::time::Duration::from_secs(1));
-
-        // Find the WA game window
-        let hwnd = unsafe { FindWindowA(std::ptr::null(), b"Worms Armageddon\0".as_ptr()) };
-        if hwnd == 0 {
-            let _ = log_line("[Input] ERROR: Could not find game window");
-            return;
-        }
-        let _ = log_line(&format!("[Input] Found game window: HWND=0x{:08X}", hwnd));
-
-        // Subclass the WndProc to intercept deactivation messages
-        unsafe {
-            ORIG_WNDPROC = SetWindowLongA(hwnd, GWL_WNDPROC, hook_wndproc as *const () as u32);
-            if ORIG_WNDPROC == 0 {
-                let _ = log_line("[Input] ERROR: SetWindowLongA failed");
-                return;
-            }
-        }
-        let _ = log_line("[Input] WndProc subclassed — WA will think it always has focus");
-
-        // Restore and focus window once to kick things off
-        unsafe {
-            ShowWindow(hwnd, SW_RESTORE);
-            SetForegroundWindow(hwnd);
-        }
-        let _ = log_line("[Input] Fast-forward enabled — posting spacebar messages");
-
-        // lParam encodes scan code (0x39 for space) and repeat count
-        let down_lparam: u32 = 0x0039_0001; // scan=0x39, repeat=1, bit30=0 (first press)
-        let up_lparam: u32 = 0xC039_0001; // scan=0x39, repeat=1, bit30+31 set (release)
-
-        loop {
-            unsafe {
-                // Send key DOWN — must be processed in its own frame
-                let r = PostMessageA(hwnd, WM_KEYDOWN, VK_SPACE, down_lparam);
-                if r == 0 {
-                    let _ = log_line("[Input] PostMessage failed — window closed");
-                    break;
-                }
-            }
-            // Wait >1 frame (50ms > 20ms/frame) so game processes key-down
-            std::thread::sleep(std::time::Duration::from_millis(50));
-
-            unsafe {
-                // Send key UP — processed in a subsequent frame
-                let r = PostMessageA(hwnd, WM_KEYUP, VK_SPACE, up_lparam);
-                if r == 0 {
-                    break;
-                }
-            }
-            // Wait for the release to be processed before next press
-            std::thread::sleep(std::time::Duration::from_millis(50));
-        }
-    });
-
     Ok(())
 }

crates/openwa-wormkit/src/validation/mod.rs

@@ -752,8 +752,24 @@ pub fn run() -> Result<(), String> {
         let _ = log_validation("  Replay fast-forward active — game will exit when replay finishes.");
         let _ = log_validation("  Safety timeout: 120s (will force exit if replay hangs).");
         std::thread::spawn(move || {
+            // Restore minimized window so the replay can start.
+            // WA.exe won't begin replay playback until the window is visible.
+            std::thread::sleep(std::time::Duration::from_secs(2));
+            unsafe {
+                let hwnd = windows_sys::Win32::UI::WindowsAndMessaging::FindWindowA(
+                    core::ptr::null::<u8>(),
+                    b"Worms Armageddon\0".as_ptr(),
+                );
+                if !hwnd.is_null() {
+                    windows_sys::Win32::UI::WindowsAndMessaging::ShowWindow(hwnd, 9); // SW_RESTORE
+                    let _ = log_validation("  Window restored (SW_RESTORE).");
+                } else {
+                    let _ = log_validation("  WARNING: Could not find WA window to restore.");
+                }
+            }
+
             // Wait for gameplay to start, then run initial validation
-            std::thread::sleep(std::time::Duration::from_secs(5));
+            std::thread::sleep(std::time::Duration::from_secs(3));
             let _ = log_validation("  Running deferred global validation...");
             deferred_global_validation();