feat: add game state snapshot system

New `snapshot` command captures canonicalized game state for diffing:
- DDGame: frame counter, RNG, game speed, camera, team arena, ammo
- Teams: name, alliance, worm count, per-worm state/hp/name
- Entities: BFS walk of task tree, rich dump for CTaskWorm/CTaskMissile,
raw hex with pointer canonicalization for unknown entity types

Snapshot trait implemented for DDGame, WormEntry, CTaskWorm, CTaskMissile.
Unknown regions dumped as raw hex with [ptr---] replacing heap pointers.

Usage: openwa-debug snapshot > /tmp/state.txt

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

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

@@ -2039,3 +2039,74 @@ impl TeamArenaRef {
         (alliance_id, weapon_id as usize)
     }
 }
+
+// ── Snapshot impls ──────────────────────────────────────────
+
+#[cfg(target_arch = "x86")]
+impl crate::snapshot::Snapshot for DDGame {
+    unsafe fn write_snapshot(&self, w: &mut dyn core::fmt::Write, indent: usize) -> core::fmt::Result {
+        use crate::fixed::Fixed;
+        use crate::snapshot::{write_indent, fmt_ptr};
+        let i = indent;
+
+        write_indent(w, i)?; writeln!(w, "frame_counter = {}", self.frame_counter)?;
+        write_indent(w, i)?; writeln!(w, "game_speed = {}", Fixed(self.game_speed))?;
+        write_indent(w, i)?; writeln!(w, "game_speed_target = {}", Fixed(self.game_speed_target))?;
+        write_indent(w, i)?; writeln!(w, "rng_state = 0x{:08X} 0x{:08X}", self.rng_state_1, self.rng_state_2)?;
+        write_indent(w, i)?; writeln!(w, "camera = ({}, {})", Fixed(self.camera_x), Fixed(self.camera_y))?;
+        write_indent(w, i)?; writeln!(w, "camera_target = ({}, {})", Fixed(self.camera_target_x), Fixed(self.camera_target_y))?;
+        write_indent(w, i)?; writeln!(w, "level_size = {}x{}", self.level_width, self.level_height)?;
+        write_indent(w, i)?; writeln!(w, "level_size_raw = {}x{}", self.level_width_raw, self.level_height_raw)?;
+        write_indent(w, i)?; writeln!(w, "landscape_property = {}", self.landscape_property)?;
+        write_indent(w, i)?; writeln!(w, "gfx_color_table = {:?}", self.gfx_color_table)?;
+        write_indent(w, i)?; writeln!(w, "fast_forward = req={} active={}", self.fast_forward_request, self.fast_forward_active)?;
+        write_indent(w, i)?; writeln!(w, "keyboard = {}", fmt_ptr(self.keyboard as *const u8))?;
+        write_indent(w, i)?; writeln!(w, "display = {}", fmt_ptr(self.display as *const u8))?;
+        write_indent(w, i)?; writeln!(w, "sound = {}", fmt_ptr(self.sound as *const u8))?;
+        write_indent(w, i)?; writeln!(w, "game_info = {}", fmt_ptr(self.game_info as *const u8))?;
+        write_indent(w, i)?; writeln!(w, "landscape = {}", fmt_ptr(self.landscape as *const u8))?;
+        write_indent(w, i)?; writeln!(w, "task_land = {}", fmt_ptr(self.task_land))?;
+
+        // TeamArenaState summary
+        write_indent(w, i)?; writeln!(w, "team_arena.team_count = {}", self.team_arena.team_count)?;
+        write_indent(w, i)?; writeln!(w, "team_arena.game_phase = {}", self.team_arena.game_phase)?;
+        write_indent(w, i)?; writeln!(w, "team_arena.game_mode_flag = {}", self.team_arena.game_mode_flag)?;
+
+        // Dump weapon slots (ammo only, skip zeros)
+        write_indent(w, i)?; writeln!(w, "weapon_slots:")?;
+        for team in 0..6usize {
+            let slots = &self.team_arena.weapon_slots.teams[team];
+            let mut has_any = false;
+            for wpn in 0..71usize {
+                let ammo = slots.ammo[wpn];
+                if ammo != 0 {
+                    if !has_any {
+                        write_indent(w, i + 1)?; write!(w, "team[{}] ammo:", team)?;
+                        has_any = true;
+                    }
+                    if ammo == -1 {
+                        write!(w, " {}=inf", wpn)?;
+                    } else {
+                        write!(w, " {}={}", wpn, ammo)?;
+                    }
+                }
+            }
+            if has_any { writeln!(w)?; }
+        }
+
+        Ok(())
+    }
+}
+
+impl crate::snapshot::Snapshot for WormEntry {
+    unsafe fn write_snapshot(&self, w: &mut dyn core::fmt::Write, indent: usize) -> core::fmt::Result {
+        use crate::snapshot::write_indent;
+        let i = indent;
+        let name = core::ffi::CStr::from_ptr(self.name.as_ptr() as *const core::ffi::c_char)
+            .to_string_lossy();
+        write_indent(w, i)?;
+        writeln!(w, "state=0x{:02X} active={} hp={}/{} name=\"{}\"",
+            self.state, self.active_flag, self.health, self.max_health, name)?;
+        Ok(())
+    }
+}

crates/openwa-core/src/task/missile.rs

@@ -182,3 +182,51 @@ pub enum MissileType {
     /// Unknown type code (value 1 never observed; any other unrecognised value).
     Unknown(u32),
 }
+
+// ── Snapshot impl ──────────────────────────────────────────
+
+#[cfg(target_arch = "x86")]
+impl crate::snapshot::Snapshot for CTaskMissile {
+    unsafe fn write_snapshot(&self, w: &mut dyn core::fmt::Write, indent: usize) -> core::fmt::Result {
+        use crate::snapshot::{write_indent, write_raw_region};
+        let i = indent;
+        let b = &self.base; // CGameTask
+
+        write_indent(w, i)?; writeln!(w, "pos = ({}, {})", b.pos_x, b.pos_y)?;
+        write_indent(w, i)?; writeln!(w, "speed = ({}, {})", b.speed_x, b.speed_y)?;
+        write_indent(w, i)?; writeln!(w, "launch_seed = 0x{:08X}", self.launch_seed)?;
+        write_indent(w, i)?; writeln!(w, "slot_id = {}", self.slot_id)?;
+
+        write_indent(w, i)?; write!(w, "spawn_params =")?;
+        for v in &self.spawn_params { write!(w, " {:08X}", v)?; }
+        writeln!(w)?;
+
+        write_indent(w, i)?; write!(w, "weapon_data =")?;
+        for (j, v) in self.weapon_data.iter().enumerate() {
+            if j % 16 == 0 { writeln!(w)?; write_indent(w, i + 1)?; }
+            write!(w, " {:08X}", v)?;
+        }
+        writeln!(w)?;
+
+        write_indent(w, i)?; write!(w, "render_data =")?;
+        for (j, v) in self.render_data.iter().enumerate() {
+            if j % 16 == 0 { writeln!(w)?; write_indent(w, i + 1)?; }
+            write!(w, " {:08X}", v)?;
+        }
+        writeln!(w)?;
+
+        write_indent(w, i)?; writeln!(w, "launch_speed_raw = {}", self.launch_speed_raw)?;
+        write_indent(w, i)?; writeln!(w, "homing_enabled = {}", self.homing_enabled)?;
+        write_indent(w, i)?; writeln!(w, "direction = {}", self.direction)?;
+
+        // Unknown regions
+        write_indent(w, i)?; writeln!(w, "_unknown_fc ({} bytes):", self._unknown_fc.len())?;
+        write_raw_region(w, self._unknown_fc.as_ptr(), self._unknown_fc.len(), i + 1)?;
+        write_indent(w, i)?; writeln!(w, "_unknown_37c ({} bytes):", self._unknown_37c.len())?;
+        write_raw_region(w, self._unknown_37c.as_ptr(), self._unknown_37c.len(), i + 1)?;
+        write_indent(w, i)?; writeln!(w, "_unknown_3cc ({} bytes):", self._unknown_3cc.len())?;
+        write_raw_region(w, self._unknown_3cc.as_ptr(), self._unknown_3cc.len(), i + 1)?;
+
+        Ok(())
+    }
+}

crates/openwa-core/src/task/worm.rs

@@ -210,3 +210,38 @@ impl CTaskWorm {
         &*(self.base.base.vtable as *const CTaskWormVTable)
     }
 }
+
+// ── Snapshot impl ──────────────────────────────────────────
+
+#[cfg(target_arch = "x86")]
+impl crate::snapshot::Snapshot for CTaskWorm {
+    unsafe fn write_snapshot(&self, w: &mut dyn core::fmt::Write, indent: usize) -> core::fmt::Result {
+        use crate::snapshot::{write_indent, write_raw_region};
+        let i = indent;
+        let b = &self.base; // CGameTask
+
+        write_indent(w, i)?; writeln!(w, "pos = ({}, {})", b.pos_x, b.pos_y)?;
+        write_indent(w, i)?; writeln!(w, "speed = ({}, {})", b.speed_x, b.speed_y)?;
+        write_indent(w, i)?; writeln!(w, "angle = {}", b.angle)?;
+        write_indent(w, i)?; writeln!(w, "team_index = {}", self.team_index)?;
+        write_indent(w, i)?; writeln!(w, "worm_index = {}", self.worm_index)?;
+        write_indent(w, i)?; writeln!(w, "slot_id = {}", self.slot_id)?;
+        write_indent(w, i)?; writeln!(w, "selected_weapon = {}", self.selected_weapon)?;
+        write_indent(w, i)?; writeln!(w, "facing = {}", self.facing_direction)?;
+        write_indent(w, i)?; writeln!(w, "aim_angle = 0x{:08X}", self.aim_angle)?;
+
+        write_indent(w, i)?; write!(w, "spawn_params =")?;
+        for v in &self.spawn_params { write!(w, " {:08X}", v)?; }
+        writeln!(w)?;
+
+        // Raw dump of unknown regions
+        write_indent(w, i)?; writeln!(w, "_unknown_1f0 ({} bytes):", self._unknown_1f0.len())?;
+        write_raw_region(w, self._unknown_1f0.as_ptr(), self._unknown_1f0.len(), i + 1)?;
+        write_indent(w, i)?; writeln!(w, "_unknown_28c ({} bytes):", self._unknown_28c.len())?;
+        write_raw_region(w, self._unknown_28c.as_ptr(), self._unknown_28c.len(), i + 1)?;
+        write_indent(w, i)?; writeln!(w, "_unknown_370 ({} bytes):", self._unknown_370.len())?;
+        write_raw_region(w, self._unknown_370.as_ptr(), self._unknown_370.len(), i + 1)?;
+
+        Ok(())
+    }
+}

crates/openwa-debug-cli/src/main.rs

@@ -86,6 +86,7 @@ fn main() {
                 .unwrap_or_else(|| { eprintln!("Usage: break <frame> | break clear"); process::exit(1); });
             Request::Break { frame }
         }
+        Some("snapshot") => Request::Snapshot,
         Some(cmd) => {
             eprintln!("Unknown command: {cmd}");
             print_usage();
@@ -177,6 +178,10 @@ fn print_response(response: &Response, format: Format) {
                 println!("Breakpoint cleared");
             }
         }
+        Response::Snapshot { frame, text } => {
+            println!("=== Snapshot at frame {frame} ===\n");
+            print!("{text}");
+        }
         Response::Error { message } => {
             eprintln!("Server error: {message}");
             process::exit(1);
@@ -347,6 +352,7 @@ fn print_usage() {
     eprintln!("  step [N]                  Advance N frames (default 1), then pause");
     eprintln!("  frame                     Show current frame and pause state");
     eprintln!("  break <N>                 Set frame breakpoint (break clear to remove)");
+    eprintln!("  snapshot                  Dump canonicalized game state (for diffing)");
     eprintln!();
     eprintln!("Address syntax:");
     eprintln!("  0x669F8C                  Ghidra VA (rebased automatically)");

crates/openwa-debug-proto/src/lib.rs

@@ -41,6 +41,8 @@ pub enum Request {
     Frame,
     /// Set a frame breakpoint (-1 to clear).
     Break { frame: i32 },
+    /// Capture a canonicalized game state snapshot.
+    Snapshot,
 }
 
 /// One step in a resolved pointer chain, for display.
@@ -93,6 +95,8 @@ pub enum Response {
     FrameInfo { frame: i32, paused: bool, breakpoint: i32 },
     /// Breakpoint set/cleared.
     BreakSet { frame: i32 },
+    /// Game state snapshot.
+    Snapshot { frame: i32, text: String },
     Error { message: String },
 }
 

crates/openwa-wormkit/src/debug_server.rs

@@ -135,6 +135,11 @@ fn handle_request(request: Request) -> Response {
             crate::debug_sync::set_breakpoint(frame);
             Response::BreakSet { frame }
         }
+        Request::Snapshot => {
+            let text = unsafe { crate::snapshot::capture() };
+            let frame = crate::debug_sync::current_frame();
+            Response::Snapshot { frame, text }
+        }
     }
 }
 

crates/openwa-wormkit/src/lib.rs

@@ -9,6 +9,7 @@ mod debug_ui;
 mod debug_watchpoint;
 pub mod hook;
 mod replacements;
+mod snapshot;
 mod validation;
 
 // ---------------------------------------------------------------------------

crates/openwa-wormkit/src/snapshot.rs

@@ -0,0 +1,149 @@
+//! Game state snapshot capture.
+//!
+//! Walks DDGame, the team arena, and the entity tree to produce a
+//! canonicalized text dump suitable for cross-run diffing.
+
+use core::fmt::Write;
+
+use openwa_core::address::va;
+use openwa_core::engine::GameSession;
+use openwa_core::rebase::rb;
+use openwa_core::snapshot::{write_raw_region, Snapshot};
+use openwa_core::task::{CTask, CTaskBfsIter, CTaskMissile, CTaskWorm};
+
+/// Capture a full game state snapshot as text.
+///
+/// # Safety
+/// Must be called from the DLL while the game is paused (frame breakpoint).
+#[cfg(target_arch = "x86")]
+pub unsafe fn capture() -> String {
+    let mut out = String::with_capacity(128 * 1024);
+
+    let session_ptr = rb(va::G_GAME_SESSION) as *const *mut GameSession;
+    let session = *session_ptr;
+    if session.is_null() {
+        let _ = writeln!(out, "ERROR: g_GameSession is null");
+        return out;
+    }
+    let wrapper = (*session).ddgame_wrapper;
+    if wrapper.is_null() {
+        let _ = writeln!(out, "ERROR: DDGameWrapper is null");
+        return out;
+    }
+    let ddgame = (*wrapper).ddgame;
+    if ddgame.is_null() {
+        let _ = writeln!(out, "ERROR: DDGame is null");
+        return out;
+    }
+
+    let _ = writeln!(out, "=== Frame {} ===\n", (*ddgame).frame_counter);
+
+    // ── DDGame ──
+    let _ = writeln!(out, "[DDGame]");
+    let _ = (*ddgame).write_snapshot(&mut out, 1);
+    let _ = writeln!(out);
+
+    // ── Team blocks + worm entries ──
+    let team_count = (*ddgame).team_arena.team_count as usize;
+    let _ = writeln!(out, "[Teams] count={}", team_count);
+    let arena = openwa_core::engine::ddgame::TeamArenaRef::from_ptr(
+        &raw mut (*ddgame).team_arena,
+    );
+    let blocks = arena.blocks();
+    for t in 0..team_count {
+        let header = arena.team_header(t);
+        let name = core::ffi::CStr::from_ptr(header.team_name.as_ptr() as *const _)
+            .to_string_lossy();
+        let _ = writeln!(out, "\n  [Team {}] \"{}\"", t, name);
+        let _ = writeln!(out, "    eliminated={} alliance={} worm_count={} active_worm={}",
+            header.eliminated, header.alliance, header.worm_count, header.active_worm);
+        let _ = writeln!(out, "    weapon_alliance={} turn_action_flags=0x{:08X}",
+            header.weapon_alliance, header.turn_action_flags);
+
+        // Worms are in block[t+1].worms[0..worm_count] (1-indexed blocks)
+        let worm_count = header.worm_count.max(0) as usize;
+        let block = &*blocks.add(t + 1);
+        for wi in 0..worm_count.min(7) {
+            let worm = &block.worms[wi];
+            let _ = write!(out, "    [Worm {}] ", wi);
+            let _ = worm.write_snapshot(&mut out, 0);
+        }
+    }
+    let _ = writeln!(out);
+
+    // ── Entity tree ──
+    let task_land = (*ddgame).task_land;
+    if task_land.is_null() {
+        let _ = writeln!(out, "[Entities] task_land=null");
+        return out;
+    }
+
+    let delta = rb(va::IMAGE_BASE).wrapping_sub(va::IMAGE_BASE);
+    let root = task_land as *const CTask;
+    let iter = CTaskBfsIter::new(root);
+
+    // Census + detailed dump
+    let entities: Vec<*const CTask> = iter.collect();
+    let _ = writeln!(out, "[Entities] {} total", entities.len());
+
+    // Census by type
+    let mut counts = std::collections::BTreeMap::<&str, usize>::new();
+    for &task in &entities {
+        let vt = (*(task as *const u32)).wrapping_sub(delta);
+        let name = vtable_name(vt);
+        *counts.entry(name).or_default() += 1;
+    }
+    let _ = write!(out, "  ");
+    for (name, count) in &counts {
+        let _ = write!(out, "{}x{} ", name, count);
+    }
+    let _ = writeln!(out, "\n");
+
+    // Detail per entity
+    for &task in &entities {
+        let vt = (*(task as *const u32)).wrapping_sub(delta);
+        let name = vtable_name(vt);
+        let class_type = (*task).class_type;
+        let _ = writeln!(out, "  [{}] class_type={:?}", name, class_type);
+
+        match vt {
+            x if x == va::CTASK_WORM_VTABLE => {
+                let worm = task as *const CTaskWorm;
+                let _ = (*worm).write_snapshot(&mut out, 2);
+            }
+            x if x == va::CTASK_MISSILE_VTABLE => {
+                let missile = task as *const CTaskMissile;
+                let _ = (*missile).write_snapshot(&mut out, 2);
+            }
+            _ => {
+                // Unknown entity — raw dump of first 0x100 bytes
+                let size = 0x100usize;
+                let _ = write_raw_region(&mut out, task as *const u8, size, 2);
+            }
+        }
+        let _ = writeln!(out);
+    }
+
+    out
+}
+
+fn vtable_name(ghidra_vt: u32) -> &'static str {
+    match ghidra_vt {
+        x if x == va::CTASK_WORM_VTABLE => "CTaskWorm",
+        x if x == va::CTASK_MISSILE_VTABLE => "CTaskMissile",
+        x if x == va::CTASK_TEAM_VTABLE => "CTaskTeam",
+        x if x == va::CTASK_LAND_VTABLE => "CTaskLand",
+        x if x == va::CTASK_TURN_GAME_VTABLE => "CTaskTurnGame",
+        x if x == va::CTASK_CLOUD_VTABLE => "CTaskCloud",
+        x if x == va::CTASK_DIRT_VTABLE => "CTaskDirt",
+        x if x == va::CTASK_FIRE_VTABLE => "CTaskFire",
+        x if x == va::CTASK_SEA_BUBBLE_VTABLE => "CTaskSeaBubble",
+        x if x == va::CTASK_MINE_VTABLE => "CTaskMine",
+        x if x == va::CTASK_OILDRUM_VTABLE => "CTaskOilDrum",
+        x if x == va::CTASK_CRATE_VTABLE => "CTaskCrate",
+        x if x == va::CTASK_CPU_VTABLE => "CTaskCPU",
+        x if x == va::CTASK_FILTER_VTABLE => "CTaskFilter",
+        x if x == va::CTASK_SPRITE_ANIM_VTABLE => "CTaskSpriteAnim",
+        _ => "Unknown",
+    }
+}