feat: replay fast-forward via PostMessage + WndProc subclass

Automatically fast-forward through entire replays during testing by
posting WM_KEYDOWN/WM_KEYUP spacebar messages with 50ms gaps. Subclasses
the game's WndProc to intercept WM_ACTIVATE/WM_ACTIVATEAPP, making WA
think it always has focus so input works even when the window is in the
background.

- Add input.rs with PostMessage loop + WndProc subclass
- Update validation auto-capture: dump at 8s, 120s safety timeout
- Update replay-test.ps1 with 150s timeout
- Add DDKeyboard::PollKeyboardState address

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

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

@@ -20,7 +20,9 @@ This will:
 - 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)
-- Wait for auto-capture (5s) and process exit
+- 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)
 - Copy logs to testdata/logs/
 
 2. Read the validation log and present results:
@@ -28,7 +30,7 @@ This will:
 Read `testdata/logs/validation_latest.log` and summarize:
 - Total PASS/FAIL counts
 - Any [FAIL] lines (quote them exactly)
-- Whether auto-capture completed
+- Whether validation completed or safety timeout triggered
 - 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.
@@ -36,13 +38,14 @@ 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 auto-capture mode: waits 5s, runs all validation + dumps, then calls ExitProcess(0). Without this, validation runs in interactive mode with hotkeys (F9=team blocks, F10=landscape).
+- `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).
 
 Both are set automatically by `replay-test.ps1`.
 
 ## Notes
 
-- The script takes ~10 seconds total (build + 5s auto-capture wait)
+- The fast-forwarded replay typically completes in ~10-15s
+- The DLL restores and focuses the game window (steals focus briefly) so PostMessage input works
 - 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`

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 detects the env vars and enters **auto-capture mode**: waits 5s, runs all validation + dumps, then calls `ExitProcess(0)`
+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
 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` — Auto-capture mode (5s wait, validate, exit). Without this, validation runs interactively with hotkeys (F9=team blocks, F10=landscape)
+- `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)
 
 ## Crate Architecture
 

crates/openwa-types/src/address.rs

@@ -258,6 +258,13 @@ pub mod va {
     pub const PLAY_SOUND_LOCAL: u32 = 0x004F_DFE0;
     pub const PLAY_SOUND_GLOBAL: u32 = 0x0054_6E20;
 
+    // === Input ===
+
+    /// DDKeyboard::PollKeyboardState — drains WM_KEY messages, calls
+    /// GetKeyboardState, normalizes to both key_state (+0x11C) and
+    /// prev_state (+0x21C) buffers. stdcall(this), RET 0x4.
+    pub const DDKEYBOARD_POLL_KEYBOARD_STATE: u32 = 0x0057_2290;
+
     // === Chat / UI ===
 
     pub const SHOW_CHAT_MESSAGE: u32 = 0x0052_ACB0;

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

@@ -0,0 +1,126 @@
+//! Input hooks for replay fast-forward.
+//!
+//! 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.
+//!
+//! 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.
+//!
+//! 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;
+
+/// Original WndProc, saved when we subclass the window.
+static mut ORIG_WNDPROC: u32 = 0;
+
+/// 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;
+    }
+
+    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);
+        }
+        _ => {}
+    }
+
+    CallWindowProcA(ORIG_WNDPROC, hwnd, msg, wparam, lparam)
+}
+
+pub fn install() -> Result<(), String> {
+    if std::env::var("OPENWA_REPLAY_TEST").is_err() {
+        return Ok(());
+    }
+
+    let _ = log_line("[Input] Replay test mode — will post spacebar messages 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;
+    }
+
+    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/replacements/mod.rs

@@ -1,5 +1,6 @@
 mod config;
 mod frontend;
+mod input;
 mod scheme;
 mod render;
 mod sound;
@@ -14,5 +15,6 @@ pub fn install_all() -> Result<(), String> {
     team::install()?;
     render::install()?;
     sound::install()?;
+    input::install()?;
     Ok(())
 }

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

@@ -2,7 +2,8 @@
 //!
 //! Enabled by setting `OPENWA_VALIDATE=1` environment variable.
 //! When `OPENWA_REPLAY_TEST=1` is also set, enters auto-capture mode:
-//! waits 5s, runs all validation + dumps, then calls ExitProcess(0).
+//! waits for the replay to finish (up to 120s), runs validation dumps,
+//! then calls ExitProcess(0) as a safety net.
 
 mod hooks;
 
@@ -748,24 +749,29 @@ pub fn run() -> Result<(), String> {
     if auto_mode {
         let _ = log_validation("");
         let _ = log_validation("--- Auto-Capture Mode (OPENWA_REPLAY_TEST) ---");
+        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 || {
-            let _ = log_validation("  Waiting 5s for replay to reach gameplay...");
+            // Wait for gameplay to start, then run initial validation
             std::thread::sleep(std::time::Duration::from_secs(5));
-
             let _ = log_validation("  Running deferred global validation...");
             deferred_global_validation();
 
-            let _ = log_validation("  Running team block dump...");
+            // Wait briefly for replay to start, then dump game state
+            // (fast-forward finishes the replay in ~10-15s total, so dump early)
+            std::thread::sleep(std::time::Duration::from_secs(3));
+            let _ = log_validation("  Running team block dump (8s mark)...");
             dump_team_blocks();
-
             let _ = log_validation("  Running landscape dump...");
             dump_landscape();
 
+            // Safety timeout: if the game hasn't exited on its own by 120s, force exit.
+            // The replay fast-forward should finish well before this.
+            std::thread::sleep(std::time::Duration::from_secs(112));
             let _ = log_validation("");
-            let _ = log_validation("--- Auto-capture complete, exiting ---");
-
+            let _ = log_validation("--- Safety timeout reached (120s), forcing exit ---");
             unsafe {
-                windows_sys::Win32::System::Threading::ExitProcess(0);
+                windows_sys::Win32::System::Threading::ExitProcess(1);
             }
         });
     } else {

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

@@ -0,0 +1,61 @@
+# 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-wormkit/src/replacements/input.rs` (new) — GetAsyncKeyState hook
+- `crates/openwa-wormkit/src/validation/mod.rs` — Update auto-capture timeout
+- `crates/openwa-wormkit/src/lib.rs` — Register input module
+- `replay-test.ps1` — Add WaitForExit timeout

replay-test.ps1

@@ -42,12 +42,17 @@ Remove-Item "$gameDir\OpenWA_validation.log" -ErrorAction SilentlyContinue
 
 # 4. Launch WA.exe with replay, env vars set
 Write-Host "Launching WA.exe with replay: $ReplayFile" -ForegroundColor Cyan
-Write-Host "  (Auto-capture mode: will exit after 5s)" -ForegroundColor Yellow
+Write-Host "  (Fast-forward mode: replay will be auto-advanced, game exits when done)" -ForegroundColor Yellow
 
 $env:OPENWA_VALIDATE = "1"
 $env:OPENWA_REPLAY_TEST = "1"
 $proc = Start-Process -FilePath $waExe -ArgumentList "`"$ReplayFile`"" -WindowStyle Minimized -PassThru
-$proc.WaitForExit()
+$timeout = 150  # seconds - replay fast-forward + safety margin
+if (-not $proc.WaitForExit($timeout * 1000)) {
+    Write-Host "WARNING: WA.exe did not exit within ${timeout}s, killing..." -ForegroundColor Red
+    $proc.Kill()
+    $proc.WaitForExit(5000)
+}
 $env:OPENWA_VALIDATE = $null
 $env:OPENWA_REPLAY_TEST = $null
 
@@ -84,10 +89,12 @@ if (Test-Path "$logDir\validation_latest.log") {
     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
+    if ($content -match "Safety timeout reached") {
+        Write-Host "  Replay: TIMEOUT (safety timeout triggered)" -ForegroundColor Red
+    } elseif ($content -match "deferred global validation") {
+        Write-Host "  Validation: completed" -ForegroundColor Green
     } else {
-        Write-Host "  Auto-capture: NOT found in log (may not have reached gameplay)" -ForegroundColor Yellow
+        Write-Host "  Validation: NOT found in log (may not have reached gameplay)" -ForegroundColor Yellow
     }
 }
 Write-Host "  Logs: $logDir\" -ForegroundColor Gray