feat: add CTaskFire and CTaskTurnGame structs with runtime validation

- CTaskFire (0xD8 bytes, class_type=0x18): spawn coords, timer, burn_rate,
spread_counter, lifetime, slot_index fields
- CTaskTurnGame (0x2E0 bytes): 15 named fields covering timers (turn_timer
+0x18C, idle_timer +0x184, retreat_timer +0x178), team tracking
(current_team, current_worm, arena_team, arena_worm), and frame counters
(active_worm_frames, retreat_frames, _timer_scale); all offsets runtime-
validated via offset_of! checks (15 PASS)
- dump_turngame(): finds TurnGame via vtable scan + SharedDataTable, dumps
known fields and full 0x2E0-byte raw region via dump_region
- dump_region refactored from DDGame-specific to generic *const u8 base
- replay-test.ps1: fix launcher invocation (pass $waExe explicitly so
replay file is forwarded as a WA.exe arg, not misinterpreted as exe path)
- Debug UI inspector sections for CTaskFire and CTaskTurnGame

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

crates/openwa-core/src/task.rs

@@ -611,6 +611,107 @@ pub struct CTaskFire {
 
 const _: () = assert!(core::mem::size_of::<CTaskFire>() == 0xD8);
 
+/// Root turn-controller task — one instance per game, parent of the entire entity tree.
+///
+/// Every worm, team, projectile, and environment task is a child (direct or indirect)
+/// of this node.  `CTaskTurnGame` drives the turn loop: it processes 50 game frames
+/// per second via `CTaskTurnGame__TurnManager_ProcessFrame` (0x55FDA0), which is
+/// called from HandleMessage case 2 (FrameFinish).
+///
+/// Inheritance: CTask → CTaskTeam → CTaskTurnGame.  Class type 6.
+/// Constructor: `CTaskTurnGame__Constructor` (0x55B2B1).
+/// vtable: `CTaskTurnGame__vtable` (0x00669F70), 20 slots.
+/// Total size: 0x2E0 bytes.
+///
+/// Key vtable slots:
+///   [0] 0x55B5E0 — task-tree state snapshot serialiser
+///   [1] 0x55B540 — destructor / Free
+///   [2] 0x55DC00 — HandleMessage (30+ message types)
+///   [3] 0x5612E0 — HUD data query (responds to msg 0x7D3)
+///
+/// All timers decrement by 20 ms per frame (= 1000 ms / 50 fps).
+#[repr(C)]
+pub struct CTaskTurnGame {
+    /// 0x00-0x2F: CTask base (vtable, parent, children, shared_data, ddgame, …)
+    pub base: CTask,
+    /// 0x30-0xDB: CTaskTeam base region (opaque — includes secondary interface pointer
+    /// at +0x30, team position/physics fields, and per-team bookkeeping).
+    pub _ctaskteam: [u8; 0xAC],
+
+    // ---- CTaskTurnGame-specific fields (0xDC onwards) ----
+
+    pub _unknown_dc: u32,
+    pub _unknown_e0: u32,
+    /// 0xE4: turn-seed: ~(DDGame+0x45EC % 9000), used for random initialisation.
+    pub _turn_seed: u32,
+    /// 0xE8: number of teams in this game (copy of DDGame+0x44C).
+    pub num_teams: u32,
+    pub _unknown_ec: [u8; 0x1C],
+    /// 0x108: "worm active" flag — non-zero while the current worm is shooting or
+    /// moving.  While non-zero, `turn_timer` is paused.
+    /// A copy is also written to DDGame+0x7234 at construction.
+    pub worm_active: u32,
+    pub _unknown_10c: [u8; 0x20],
+    /// 0x12C: active team index, **1-based** (0 = no active team).
+    /// Used to index per-team sound tables in DDGame (stride 0xF0 at DDGame+0x774C).
+    pub current_team: u32,
+    /// 0x130: active worm index within the current team, **0-based** (stride 0x9C).
+    pub current_worm: u32,
+    /// 0x134: arena team index used for TeamArenaState lookups.
+    pub arena_team: u32,
+    /// 0x138: arena worm index used for TeamArenaState lookups.
+    pub arena_worm: u32,
+    pub _unknown_13c: u32,
+    /// 0x140: set to 1 at construction; role unclear.
+    pub _init_140: u32,
+    pub _unknown_144: u32,
+    pub _unknown_148: u32,
+    /// 0x14C: set to 1 at construction and reset by turn-flow restart; role unclear.
+    pub _init_14c: u32,
+    /// 0x150: set to 1 when the active worm's firing phase ends and retreat begins.
+    pub turn_ended: u32,
+    /// 0x154: set to 1 when the scheme turn time is 0 (no time limit).
+    pub no_time_limit: u32,
+    pub _unknown_158: [u8; 0x14],
+    /// 0x16C: set to 1 once the "5 seconds left" warning sound has played.
+    pub warning_sound_played: u32,
+    pub _unknown_170: u32,
+    /// 0x174: set while a worm is transitioning out of a special state (e.g. landing
+    /// after a fly animation); cleared once settled.
+    pub _worm_state_transition: u32,
+    /// 0x178: retreat-phase countdown (ms).  Initialised from `retreat_time_max` when
+    /// firing ends; decrements 20 ms/frame.  Dispatches message 0x35 at zero.
+    pub retreat_timer: i32,
+    /// 0x17C: initial retreat duration (ms) loaded from the scheme at turn start.
+    pub retreat_time_max: i32,
+    /// 0x180: last tick when the displayed "seconds remaining" value was updated.
+    pub last_second_tick: u32,
+    /// 0x184: idle-phase timer (ms).  Initialised to `scheme_turn_time × 1000`.
+    /// Decrements 20 ms/frame **only while `worm_active == 0`** (timer pauses when
+    /// the worm is moving/shooting).  When it reaches zero, sudden-death is triggered.
+    /// This is NOT the per-turn HUD countdown — see `turn_timer` at +0x18C instead.
+    pub idle_timer: i32,
+    /// 0x188: smoothed display copy of `turn_timer`; tracks it at ≤ 0xCCC ms/frame
+    /// to avoid visual jumping on the HUD.
+    pub turn_timer_display: i32,
+    /// 0x18C: per-turn countdown timer (ms) — this is what the HUD shows.
+    /// Decrements 20 ms/frame every game frame.  When it reaches zero,
+    /// `FUN_0055f4f0` fires (turn ends / retreat begins).
+    pub turn_timer: i32,
+    pub _unknown_190: [u8; 0x8],
+    /// 0x198: turn-timer visual pulse intensity (Fixed 16.16); grows as time runs low.
+    pub timer_flash: u32,
+    pub _unknown_19c: [u8; 0x138],
+    /// 0x2D4: frame count accumulated while this team held the active worm.
+    pub active_worm_frames: u32,
+    /// 0x2D8: frame count accumulated during the retreat phase.
+    pub retreat_frames: u32,
+    /// 0x2DC: timer scale factor derived from scheme (2, 3, or 4; default 4).
+    pub _timer_scale: u32,
+}
+
+const _: () = assert!(core::mem::size_of::<CTaskTurnGame>() == 0x2E0);
+
 // ============================================================
 // Derived task overlays — for accessing task-specific fields
 // beyond or within CGameTask that differ per task type.

crates/openwa-debugui/src/app.rs

@@ -3,7 +3,7 @@ use openwa_core::address::va;
 use openwa_core::ddgame::DDGame;
 use openwa_core::ddgame_wrapper::DDGameWrapper;
 use openwa_core::rebase::rb;
-use openwa_core::task::{CTask, CTaskCloud, CTaskFire, CTaskMine, CTaskOilDrum, CTaskWorm};
+use openwa_core::task::{CTask, CTaskCloud, CTaskFire, CTaskMine, CTaskOilDrum, CTaskTurnGame, CTaskWorm};
 
 use crate::log;
 
@@ -460,6 +460,30 @@ impl DebugApp {
                     });
             }
 
+            // --- CTaskTurnGame-specific fields ---
+            if name == "CTaskTurnGame" {
+                let tg = addr as *const CTaskTurnGame;
+                egui::CollapsingHeader::new("CTaskTurnGame")
+                    .default_open(true)
+                    .show(ui, |ui| {
+                        egui::Grid::new("tg_grid").striped(true).show(ui, |ui| {
+                            ui.label("current_team");  ui.label(format!("{}", (*tg).current_team));                           ui.end_row();
+                            ui.label("current_worm");  ui.label(format!("{}", (*tg).current_worm));                           ui.end_row();
+                            ui.label("arena_team");    ui.label(format!("{}", (*tg).arena_team));                             ui.end_row();
+                            ui.label("arena_worm");    ui.label(format!("{}", (*tg).arena_worm));                             ui.end_row();
+                            ui.label("worm_active");   ui.label(format!("{}", (*tg).worm_active != 0));                       ui.end_row();
+                            ui.label("turn_ended");    ui.label(format!("{}", (*tg).turn_ended != 0));                        ui.end_row();
+                            ui.label("no_time_lim");   ui.label(format!("{}", (*tg).no_time_limit != 0));                     ui.end_row();
+                            ui.label("turn_timer");    ui.label(format!("{:.1}s", (*tg).turn_timer as f32 / 1000.0));         ui.end_row();
+                            ui.label("retreat");       ui.label(format!("{:.1}s", (*tg).retreat_timer as f32 / 1000.0));      ui.end_row();
+                            ui.label("idle_timer");    ui.label(format!("{:.1}s", (*tg).idle_timer as f32 / 1000.0));         ui.end_row();
+                            ui.label("num_teams");     ui.label(format!("{}", (*tg).num_teams));                              ui.end_row();
+                            ui.label("active_frm");    ui.label(format!("{}", (*tg).active_worm_frames));                     ui.end_row();
+                            ui.label("retreat_frm");   ui.label(format!("{}", (*tg).retreat_frames));                         ui.end_row();
+                        });
+                    });
+            }
+
             // --- CTaskFire-specific fields ---
             if name == "CTaskFire" {
                 let fire = addr as *const CTaskFire;

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

@@ -51,16 +51,28 @@ pub unsafe fn can_read(ptr: u32, size: u32) -> bool {
     ptr >= 0x10000 && IsBadReadPtr(ptr as *const u8, size) == 0
 }
 
-/// Dump a region of DDGame as DWORDs with classification.
+/// Dump a memory region as DWORDs with automatic classification.
 ///
-/// Classifies each non-zero DWORD as vtable (.rdata), code (.text), data,
-/// heap object (dereferences to check for vtable), small integer, or raw value.
-pub unsafe fn dump_region(ddgame: *mut DDGame, offset: usize, size: usize, label: &str) {
-    let base_ptr = ddgame as *const u8;
+/// Each non-zero DWORD is classified as:
+/// - `[VTABLE]`  — points into .rdata (likely a vtable or function pointer table);
+///   also dereferences `vt[0]` if readable
+/// - `[CODE]`    — points into .text
+/// - `[DATA]`    — points into .data/.bss
+/// - `[OBJECT]`  — heap pointer whose first DWORD is a vtable; prints vtable address
+/// - `[ptr]`     — any other readable heap pointer; prints the dereferenced DWORD
+/// - `[small=N]` — value < 0x10000 (integer / enum / flag)
+/// - `[value]`   — anything else
+///
+/// # Parameters
+/// - `base_ptr`: start of the object to dump (e.g. `turngame as *const u8`)
+/// - `offset`: byte offset within `base_ptr` to start the dump
+/// - `size`: number of bytes to dump (must be a multiple of 4)
+/// - `struct_name`: used as the prefix in log lines (e.g. `"CTaskTurnGame"`)
+pub unsafe fn dump_region(base_ptr: *const u8, offset: usize, size: usize, struct_name: &str) {
     let wa_base = rb(va::IMAGE_BASE);
     let delta = wa_base.wrapping_sub(va::IMAGE_BASE);
 
-    let _ = log_line(&format!("\n=== DDGame+0x{:04X}..0x{:04X}: {} ===", offset, offset + size, label));
+    let _ = log_line(&format!("\n=== {}+0x{:04X}..0x{:04X} ===", struct_name, offset, offset + size));
 
     let dword_count = size / 4;
     for i in 0..dword_count {

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

@@ -1,6 +1,6 @@
 mod config;
 mod frontend;
-mod input;
+pub(crate) mod input;
 mod scheme;
 mod render;
 mod sound;

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

@@ -11,7 +11,7 @@ use std::sync::atomic::{AtomicU32, Ordering};
 
 use openwa_core::rebase::rb;
 use openwa_core::address::va;
-use openwa_core::task::{CTask, CGameTask, SharedDataTable};
+use openwa_core::task::{CTask, CGameTask, CTaskTurnGame, SharedDataTable};
 use openwa_core::ddgame::DDGame;
 use openwa_core::ddgame_wrapper::DDGameWrapper;
 
@@ -296,6 +296,24 @@ fn validate_struct_offsets(result: &mut ValidationResult) {
     check_offset!(result, DDGameWrapper, _field_4c0, 0x4C0);
     check_offset!(result, DDGameWrapper, landscape, 0x4CC);
     check_offset!(result, DDGameWrapper, display, 0x4D0);
+
+    let _ = log_validation("");
+    let _ = log_validation("  CTaskTurnGame:");
+    check_offset!(result, CTaskTurnGame, worm_active,        0x108);
+    check_offset!(result, CTaskTurnGame, current_team,       0x12C);
+    check_offset!(result, CTaskTurnGame, current_worm,       0x130);
+    check_offset!(result, CTaskTurnGame, arena_team,         0x134);
+    check_offset!(result, CTaskTurnGame, arena_worm,         0x138);
+    check_offset!(result, CTaskTurnGame, turn_ended,         0x150);
+    check_offset!(result, CTaskTurnGame, no_time_limit,      0x154);
+    check_offset!(result, CTaskTurnGame, retreat_timer,      0x178);
+    check_offset!(result, CTaskTurnGame, retreat_time_max,   0x17C);
+    check_offset!(result, CTaskTurnGame, idle_timer,         0x184);
+    check_offset!(result, CTaskTurnGame, turn_timer_display, 0x188);
+    check_offset!(result, CTaskTurnGame, turn_timer,         0x18C);
+    check_offset!(result, CTaskTurnGame, active_worm_frames, 0x2D4);
+    check_offset!(result, CTaskTurnGame, retreat_frames,     0x2D8);
+    check_offset!(result, CTaskTurnGame, _timer_scale,       0x2DC);
 }
 
 // ---------------------------------------------------------------------------
@@ -920,6 +938,83 @@ fn dump_worm_tasks() {
     }
 }
 
+// ---------------------------------------------------------------------------
+// CTaskTurnGame dump
+// ---------------------------------------------------------------------------
+
+fn dump_turngame() {
+    use openwa_core::task::CTaskTurnGame;
+    use crate::replacements::input::dump_region;
+
+    let _ = log_validation("");
+    let _ = log_validation("--- CTaskTurnGame Dump ---");
+
+    unsafe {
+        let session_ptr = read_u32(rb(va::G_GAME_SESSION));
+        if session_ptr == 0 { let _ = log_validation("  No game session — skipping."); return; }
+        let wrapper_addr = read_u32(session_ptr + 0xA0);
+        if wrapper_addr == 0 { let _ = log_validation("  No DDGameWrapper."); return; }
+        let ddgame_ptr = read_u32(wrapper_addr + 0x488);
+        if ddgame_ptr == 0 { let _ = log_validation("  No DDGame."); return; }
+
+        // Find CTaskTurnGame via the shared_data entity table.
+        let task_land_ptr = read_u32(ddgame_ptr + 0x54C);
+        if task_land_ptr == 0 { let _ = log_validation("  CTaskLand NULL — skipping."); return; }
+        let task_land = task_land_ptr as *const openwa_core::task::CTask;
+        let shared_data_ptr = (*task_land).shared_data;
+        if shared_data_ptr.is_null() { let _ = log_validation("  shared_data NULL."); return; }
+
+        let table = SharedDataTable::from_ptr(shared_data_ptr);
+        let expected_vt = rb(va::CTASK_TURN_GAME_VTABLE);
+        let mut tg_ptr: u32 = 0;
+        for node in table.iter() {
+            let entity = (*node).entity;
+            if entity.is_null() { continue; }
+            if !is_in_rdata(read_u32(entity as u32)) { continue; }
+            if read_u32(entity as u32) == expected_vt {
+                tg_ptr = entity as u32;
+                break;
+            }
+        }
+
+        if tg_ptr == 0 {
+            let _ = log_validation("  CTaskTurnGame not found in entity table.");
+            return;
+        }
+
+        let _ = log_validation(&format!("  CTaskTurnGame @ 0x{:08X}", tg_ptr));
+
+        // Print known named fields for cross-validation.
+        let tg = &*(tg_ptr as *const CTaskTurnGame);
+        let _ = log_validation("  Known fields:");
+        let _ = log_validation(&format!("    +0x108 worm_active        = {}", tg.worm_active));
+        let _ = log_validation(&format!("    +0x12C current_team       = {} (1-based, 0=none)", tg.current_team));
+        let _ = log_validation(&format!("    +0x130 current_worm       = {} (0-based)", tg.current_worm));
+        let _ = log_validation(&format!("    +0x134 arena_team         = {}", tg.arena_team));
+        let _ = log_validation(&format!("    +0x138 arena_worm         = {}", tg.arena_worm));
+        let _ = log_validation(&format!("    +0x150 turn_ended         = {}", tg.turn_ended));
+        let _ = log_validation(&format!("    +0x154 no_time_limit      = {}", tg.no_time_limit));
+        let _ = log_validation(&format!("    +0x178 retreat_timer      = {} ms", tg.retreat_timer));
+        let _ = log_validation(&format!("    +0x17C retreat_time_max   = {} ms", tg.retreat_time_max));
+        let _ = log_validation(&format!("    +0x184 idle_timer         = {} ms", tg.idle_timer));
+        let _ = log_validation(&format!("    +0x188 turn_timer_display = {} ms", tg.turn_timer_display));
+        let _ = log_validation(&format!("    +0x18C turn_timer         = {} ms", tg.turn_timer));
+        let _ = log_validation(&format!("    +0x2D4 active_worm_frames = {}", tg.active_worm_frames));
+        let _ = log_validation(&format!("    +0x2D8 retreat_frames     = {}", tg.retreat_frames));
+        let _ = log_validation(&format!("    +0x2DC _timer_scale       = {}", tg._timer_scale));
+
+        // Full memory dump — classify every DWORD to discover unknown fields.
+        // Dump in chunks to keep log lines manageable.
+        let base = tg_ptr as *const u8;
+        dump_region(base, 0x00, 0x30, "CTaskTurnGame"); // CTask base
+        dump_region(base, 0x30, 0xAC, "CTaskTurnGame"); // CTaskTeam region
+        dump_region(base, 0xDC, 0x80, "CTaskTurnGame"); // 0xDC..0x15B
+        dump_region(base, 0x15C, 0x80, "CTaskTurnGame"); // 0x15C..0x1DB
+        dump_region(base, 0x1DC, 0x80, "CTaskTurnGame"); // 0x1DC..0x25B
+        dump_region(base, 0x25C, 0x84, "CTaskTurnGame"); // 0x25C..0x2DF
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Public entry point — called from wormkit's run()
 // ---------------------------------------------------------------------------
@@ -986,6 +1081,8 @@ pub fn run() -> Result<(), String> {
             dump_entity_census();
             let _ = log_validation("  Running worm entity dump (5s mark)...");
             dump_worm_tasks();
+            let _ = log_validation("  Running TurnGame dump (5s mark)...");
+            dump_turngame();
 
             // Wait briefly for replay to start, then dump game state
             // (fast-forward finishes the replay in ~10-15s total, so dump early)

replay-test.ps1

@@ -51,7 +51,7 @@ $env:OPENWA_REPLAY_TEST = "1"
 $env:OPENWA_WA_PATH     = $waExe
 
 # The launcher blocks until WA.exe exits, so run it as a background job for timeout support.
-$proc = Start-Process -FilePath $launcher -ArgumentList "--minimized `"$ReplayFile`"" -PassThru
+$proc = Start-Process -FilePath $launcher -ArgumentList "--minimized `"$waExe`" `"$ReplayFile`"" -PassThru
 $timeout = 150  # seconds
 if (-not $proc.WaitForExit($timeout * 1000)) {
     Write-Host "WARNING: launcher did not exit within ${timeout}s, killing..." -ForegroundColor Red