feat: upgrade debug tools with registry, typed reflection, and symbolic addresses

Wire the address registry, field registries, typed vtables, and live
object tracker into all debug tools:

- Watchpoint stack traces now show symbolicated function names via
format_va() instead of raw hex addresses
- Validation auto-discovers vtables from the registry and validates
all named slots from #[vtable(...)] structs
- New ValueKind enum + FieldFormatter trait for typed field formatting:
scalars as decimal, Fixed as float, pointers resolved via registry,
CString as quoted strings. Extensible via inventory::submit!
- Snapshot fallback uses FieldRegistry for entity types without
hand-coded Snapshot impls (CTaskTeam, CTaskMine, etc.)
- New debug CLI commands: inspect (typed struct read), objects (list
tracked live objects)
- Symbolic address expressions: ddgame, ddgame+field_name,
ddgame->field_name work in all CLI commands
- New protocol messages: Inspect, ListObjects, ResolveAlias, ResolveField
- #[field(kind = "CString")] attribute for string fields in FieldRegistry

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

crates/openwa-core/src/field_format.rs

@@ -0,0 +1,188 @@
+//! Extensible field value formatting for debug tools.
+//!
+//! Provides a [`FieldFormatter`] trait and a top-level [`format_field`] function
+//! that writes human-readable field values to any `fmt::Write` target.
+//!
+//! Default formatters handle scalars, Fixed, pointers, and booleans.
+//! Custom formatters (e.g., for game-specific enums) can be registered via
+//! `inventory::submit!` from any crate.
+
+use core::fmt;
+
+use crate::registry::{FieldEntry, ValueKind};
+
+/// Context passed to formatters (avoids bloating the trait signature).
+pub struct FormatContext {
+    /// ASLR delta for pointer resolution (runtime_base - 0x400000).
+    pub delta: u32,
+}
+
+/// Trait for formatting field values.
+///
+/// Implementations are registered via `inventory::submit!` and dispatched
+/// by [`format_field`] based on `ValueKind`.
+///
+/// Writes to `&mut dyn fmt::Write` — no allocations required.
+pub trait FieldFormatter: Send + Sync + 'static {
+    /// Which `ValueKind`(s) this formatter handles.
+    fn handles(&self) -> &[ValueKind];
+
+    /// Format `data` (the raw bytes of the field) into `w`.
+    fn format_field(
+        &self,
+        w: &mut dyn fmt::Write,
+        data: &[u8],
+        field: &FieldEntry,
+        ctx: &FormatContext,
+    ) -> fmt::Result;
+}
+
+// Inventory collection for custom formatters.
+inventory::collect!(Box<dyn FieldFormatter>);
+
+/// Write a formatted field value to any `fmt::Write` target.
+///
+/// Dispatches to registered custom formatters first, then falls back to
+/// built-in defaults based on `field.kind`.
+pub fn format_field(
+    w: &mut dyn fmt::Write,
+    data: &[u8],
+    field: &FieldEntry,
+    ctx: &FormatContext,
+) -> fmt::Result {
+    // Check custom formatters first
+    for formatter in inventory::iter::<Box<dyn FieldFormatter>> {
+        if formatter.handles().contains(&field.kind) {
+            return formatter.format_field(w, data, field, ctx);
+        }
+    }
+
+    // Built-in defaults
+    match field.kind {
+        ValueKind::U8 if data.len() >= 1 => {
+            write!(w, "{}", data[0])
+        }
+        ValueKind::I8 if data.len() >= 1 => {
+            write!(w, "{}", data[0] as i8)
+        }
+        ValueKind::U16 if data.len() >= 2 => {
+            let v = u16::from_le_bytes([data[0], data[1]]);
+            write!(w, "{}", v)
+        }
+        ValueKind::I16 if data.len() >= 2 => {
+            let v = i16::from_le_bytes([data[0], data[1]]);
+            write!(w, "{}", v)
+        }
+        ValueKind::U32 if data.len() >= 4 => {
+            let v = u32::from_le_bytes([data[0], data[1], data[2], data[3]]);
+            if v > 0xFFFF {
+                write!(w, "0x{:08X}", v)
+            } else {
+                write!(w, "{}", v)
+            }
+        }
+        ValueKind::I32 if data.len() >= 4 => {
+            let v = i32::from_le_bytes([data[0], data[1], data[2], data[3]]);
+            write!(w, "{}", v)
+        }
+        ValueKind::Bool if data.len() >= 1 => match data[0] {
+            0 => write!(w, "false"),
+            1 => write!(w, "true"),
+            v => write!(w, "??(0x{:02X})", v),
+        },
+        ValueKind::Fixed if data.len() >= 4 => {
+            let raw = i32::from_le_bytes([data[0], data[1], data[2], data[3]]);
+            let f = crate::fixed::Fixed(raw);
+            write!(w, "{:.4} (0x{:08X})", f.to_f32(), raw as u32)
+        }
+        ValueKind::Pointer if data.len() >= 4 => {
+            let v = u32::from_le_bytes([data[0], data[1], data[2], data[3]]);
+            if v == 0 {
+                write!(w, "null")
+            } else {
+                format_pointer(w, v, ctx.delta)
+            }
+        }
+        ValueKind::Enum if data.len() >= 4 => {
+            // Default enum formatting — just show the numeric value.
+            // Custom formatters can override for specific enums.
+            let v = u32::from_le_bytes([data[0], data[1], data[2], data[3]]);
+            write!(w, "enum({})", v)
+        }
+        ValueKind::CString => {
+            let nul = data.iter().position(|&b| b == 0).unwrap_or(data.len());
+            let s = core::str::from_utf8(&data[..nul]).unwrap_or("<invalid utf8>");
+            write!(w, "\"{}\"", s)
+        }
+        ValueKind::Struct => {
+            write!(w, "<struct {} bytes>", data.len())
+        }
+        // Raw fallback: hex dump
+        _ => format_raw_hex(w, data),
+    }
+}
+
+/// Format a pointer value using the registry for symbolication.
+fn format_pointer(w: &mut dyn fmt::Write, value: u32, delta: u32) -> fmt::Result {
+    let ghidra = value.wrapping_sub(delta);
+
+    // Try static registry lookup
+    if let Some(resolved) = crate::registry::lookup_va(ghidra) {
+        if resolved.offset == 0 {
+            return write!(w, "0x{:08X} ({})", value, resolved.entry.name);
+        } else {
+            return write!(
+                w,
+                "0x{:08X} ({}+0x{:X})",
+                value, resolved.entry.name, resolved.offset
+            );
+        }
+    }
+
+    // Try live object identification
+    #[cfg(target_os = "windows")]
+    if let Some(live) = crate::registry::identify_live_pointer(value) {
+        if let Some(field) = live.field {
+            return write!(
+                w,
+                "0x{:08X} ({}+0x{:X} .{})",
+                value, live.object.class_name, live.offset, field.name
+            );
+        } else {
+            return write!(
+                w,
+                "0x{:08X} ({}+0x{:X})",
+                value, live.object.class_name, live.offset
+            );
+        }
+    }
+
+    // Try vtable-based class detection
+    #[cfg(target_os = "windows")]
+    if unsafe { crate::mem::can_read(value, 4) } {
+        let first_dword = unsafe { *(value as *const u32) };
+        let vtable_ghidra = first_dword.wrapping_sub(delta);
+        if let Some(class) = crate::registry::vtable_class_name(vtable_ghidra) {
+            return write!(w, "0x{:08X} ({}*)", value, class);
+        }
+    }
+
+    // Bare hex
+    write!(w, "0x{:08X}", value)
+}
+
+/// Format raw bytes as hex.
+fn format_raw_hex(w: &mut dyn fmt::Write, data: &[u8]) -> fmt::Result {
+    for (i, byte) in data.iter().enumerate() {
+        if i > 0 {
+            write!(w, " ")?;
+        }
+        write!(w, "{:02X}", byte)?;
+        // Truncate long arrays
+        if i >= 15 && data.len() > 16 {
+            write!(w, " ... ({} bytes)", data.len())?;
+            break;
+        }
+    }
+    Ok(())
+}

crates/openwa-core/src/lib.rs

@@ -43,6 +43,7 @@ pub mod log;
 pub mod mem;
 pub mod rebase;
 pub mod snapshot;
+pub mod field_format;
 pub mod task;
 pub mod vtable;
 pub mod wa;

crates/openwa-core/src/registry.rs

@@ -179,6 +179,34 @@ pub fn entry_count() -> usize {
 
 // --- Struct field registry types (for Phase 4 #[derive(FieldRegistry)]) ---
 
+/// Describes the semantic type of a struct field for display formatting.
+///
+/// Inferred automatically by `#[derive(FieldRegistry)]` from the Rust type.
+/// Use `#[field(kind = "Fixed")]` to override when auto-inference is wrong.
+/// Falls back to `Raw` for unrecognized types.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ValueKind {
+    U8,
+    U16,
+    U32,
+    I8,
+    I16,
+    I32,
+    Bool,
+    /// 16.16 fixed-point (`Fixed` newtype).
+    Fixed,
+    /// Any pointer (`*mut T`, `*const T`).
+    Pointer,
+    /// Enum type (e.g., `ClassType`).
+    Enum,
+    /// Embedded struct with its own FieldRegistry.
+    Struct,
+    /// Null-terminated C string in a fixed-size byte array.
+    CString,
+    /// Fallback for arrays, unknown types, etc.
+    Raw,
+}
+
 /// A known field within a struct.
 #[derive(Debug, Clone, Copy)]
 pub struct FieldEntry {
@@ -188,6 +216,8 @@ pub struct FieldEntry {
     pub name: &'static str,
     /// Field size in bytes.
     pub size: u32,
+    /// Semantic type for formatting.
+    pub kind: ValueKind,
     /// Brief description.
     pub doc: &'static str,
 }
@@ -558,9 +588,9 @@ mod tests {
         static FIELDS: StructFields = StructFields {
             struct_name: "TestStruct",
             fields: &[
-                FieldEntry { offset: 0x00, name: "vtable", size: 4, doc: "" },
-                FieldEntry { offset: 0x10, name: "health", size: 4, doc: "" },
-                FieldEntry { offset: 0x20, name: "name", size: 16, doc: "" },
+                FieldEntry { offset: 0x00, name: "vtable", size: 4, kind: ValueKind::Pointer, doc: "" },
+                FieldEntry { offset: 0x10, name: "health", size: 4, kind: ValueKind::U32, doc: "" },
+                FieldEntry { offset: 0x20, name: "name", size: 16, kind: ValueKind::Raw, doc: "" },
             ],
         };
 

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

@@ -152,8 +152,10 @@ pub struct CTaskWorm {
     /// 0x28C–0x2EF: Unknown
     pub _unknown_28c: [u8; 0x64],
     /// 0x2F0: Worm name, null-terminated (max 17 chars, from spawn init_data+3)
+    #[field(kind = "CString")]
     pub worm_name: [u8; 0x11],
     /// 0x301: Country / team name from scheme, null-terminated (max 17 chars)
+    #[field(kind = "CString")]
     pub country_name: [u8; 0x11],
     /// 0x312–0x333: Unknown (rope string, state history, etc.)
     pub _unknown_312: [u8; 0x334 - 0x312],

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

@@ -62,7 +62,7 @@ fn main() {
                 eprintln!("  Hint: quote the argument: read \"0x7A0884->0xA0->0x0\"");
                 process::exit(1);
             }
-            let expr = parse_address_expr(addr_str);
+            let expr = resolve_address_expr(addr_str, port);
             let len = positional.get(2)
                 .map(|s| parse_u32(s))
                 .unwrap_or(256);
@@ -73,6 +73,24 @@ fn main() {
                     Request::ReadChain { addr, chain, len, absolute },
             }
         }
+        Some("inspect") => {
+            let class_name = positional.get(1).unwrap_or_else(|| {
+                eprintln!("Usage: inspect <class_name> <addr>");
+                process::exit(1);
+            }).clone();
+            let addr_str = positional.get(2).unwrap_or_else(|| {
+                eprintln!("Usage: inspect <class_name> <addr>");
+                process::exit(1);
+            });
+            let expr = resolve_address_expr(addr_str, port);
+            match expr {
+                AddressExpr::Simple { addr, absolute } =>
+                    Request::Inspect { class_name, addr, chain: vec![], absolute },
+                AddressExpr::Chain { addr, chain, absolute } =>
+                    Request::Inspect { class_name, addr, chain, absolute },
+            }
+        }
+        Some("objects") => Request::ListObjects,
         Some("suspend") => Request::Suspend,
         Some("resume") => Request::Resume,
         Some("step") => {
@@ -182,6 +200,37 @@ fn print_response(response: &Response, format: Format) {
             println!("=== Snapshot at frame {frame} ===\n");
             print!("{text}");
         }
+        Response::InspectResult { class_name, ghidra_addr, runtime_addr, fields } => {
+            println!(
+                "{} at ghidra:0x{:08X} (runtime:0x{:08X})\n",
+                class_name, ghidra_addr, runtime_addr
+            );
+            for f in fields {
+                println!(
+                    "  +0x{:04X}  {:<20} [{:>2}]  {}",
+                    f.offset, f.name, f.size, f.display
+                );
+            }
+        }
+        Response::ObjectList { objects } => {
+            if objects.is_empty() {
+                println!("No tracked objects");
+            } else {
+                println!("Tracked objects ({}):\n", objects.len());
+                for obj in objects {
+                    println!(
+                        "  {:<20} runtime:0x{:08X}  size:0x{:X}  fields:{}",
+                        obj.class_name, obj.runtime_addr, obj.size, obj.field_count
+                    );
+                }
+            }
+        }
+        Response::AliasResult(alias) => {
+            println!("{} at runtime:0x{:08X}", alias.class_name, alias.runtime_addr);
+        }
+        Response::FieldResult(field) => {
+            println!("offset:0x{:X} size:{}", field.offset, field.size);
+        }
         Response::Error { message } => {
             eprintln!("Server error: {message}");
             process::exit(1);
@@ -258,64 +307,42 @@ enum AddressExpr {
     Chain { addr: u32, chain: Vec<u32>, absolute: bool },
 }
 
-/// Parse an address expression.
-///
-/// Syntax:
-///   0x669F8C              — Ghidra VA
-///   abs:0x7FFF0000        — absolute runtime address
-///   0x669F8C+0x10         — Ghidra VA + hex offset
-///   0x669F8C[0x10]        — same as +0x10 (bracket notation)
-///   0x7A0884->0xA0->0x2C  — pointer chain (deref at each ->)
-///   abs:0x7FFF0000->4->0  — absolute + chain
-///
-/// Chain semantics: read DWORD at addr, add first offset, read DWORD, add
-/// second offset, ... display memory at final address.
-fn parse_address_expr(s: &str) -> AddressExpr {
-    let (s, absolute) = if let Some(rest) = s.strip_prefix("abs:") {
-        (rest, true)
-    } else {
-        (s.as_ref(), false)
-    };
-
-    // Check for chain syntax: contains "->"
-    if s.contains("->") {
-        let parts: Vec<&str> = s.split("->").collect();
-        let base = parse_addr_with_offset(parts[0]);
-        let chain: Vec<u32> = parts[1..].iter().map(|p| parse_compound_offset(p)).collect();
-        return AddressExpr::Chain { addr: base, chain, absolute };
-    }
-
-    // Simple address with optional offset
-    AddressExpr::Simple { addr: parse_addr_with_offset(s), absolute }
-}
-
-/// Parse a single address token, possibly with +offset or [offset].
-fn parse_addr_with_offset(s: &str) -> u32 {
-    let (base_str, offset) = split_compound(s);
-    parse_hex(base_str).wrapping_add(offset)
-}
-
-/// Parse a chain offset segment, possibly with +offset or [offset].
-/// E.g. "0x488+0x10" → 0x498, "0xA0[4]" → 0xA4, "0x510" → 0x510.
-fn parse_compound_offset(s: &str) -> u32 {
-    let (base_str, offset) = split_compound(s);
-    parse_u32(base_str).wrapping_add(offset)
-}
-
-/// Split a string on '+' or '[' into (base, offset). Returns (s, 0) if no compound.
-fn split_compound(s: &str) -> (&str, u32) {
+/// Split a string on '+' or '[' into (base, offset_str). Returns (s, None) if no compound.
+fn split_compound(s: &str) -> (&str, Option<&str>) {
     if let Some(pos) = s.find('+') {
-        let (base, off) = s.split_at(pos);
-        (base, parse_u32(&off[1..]))
+        let base = &s[..pos];
+        let off = &s[pos + 1..];
+        (base, Some(off))
     } else if let Some(pos) = s.find('[') {
         let base = &s[..pos];
         let off_str = s[pos + 1..].trim_end_matches(']');
-        (base, parse_u32(off_str))
+        (base, Some(off_str))
     } else {
-        (s, 0u32)
+        (s, None)
     }
 }
 
+/// Resolve an offset string — could be numeric or a field name.
+fn resolve_offset(s: &str, class: &Option<String>, port: u16) -> u32 {
+    if looks_like_hex(s) {
+        return parse_u32(s);
+    }
+
+    // Try as field name
+    if let Some(cls) = class {
+        match send_request(port, &Request::ResolveField {
+            class_name: cls.clone(),
+            field_name: s.to_string(),
+        }) {
+            Ok(Response::FieldResult(f)) => return f.offset,
+            _ => {}
+        }
+    }
+
+    // Fall back to numeric parse (will exit on error)
+    parse_u32(s)
+}
+
 fn parse_hex(s: &str) -> u32 {
     let s = s.strip_prefix("0x").or_else(|| s.strip_prefix("0X")).unwrap_or(s);
     u32::from_str_radix(s, 16).unwrap_or_else(|_| {
@@ -340,6 +367,143 @@ fn parse_u32(s: &str) -> u32 {
     }
 }
 
+/// A resolved chain segment — either a normal "deref then offset" step,
+/// or a field-name step where the offset should be applied BEFORE the deref.
+enum ChainSegment {
+    /// Normal hex offset: protocol uses it directly (deref current, add offset).
+    HexOffset(u32),
+    /// Field offset: needs to be folded into the previous address/step
+    /// (add offset to current, THEN deref).
+    FieldOffset(u32),
+}
+
+/// Resolve a symbolic address expression via the debug server.
+///
+/// The underlying chain protocol semantics: each step is "deref current addr,
+/// then add offset." For hex chains like `0x7A0884->0xA0->0x2C`, this works
+/// directly — the offset is added after the deref.
+///
+/// For field-name chains like `ddgame->task_land`, the user intent is "go to
+/// the task_land field (offset 0x54C) and follow that pointer." We translate
+/// this by folding the field offset into the PREVIOUS address/step:
+///
+///   `ddgame->task_land`  → base=ddgame+0x54C, chain=[0]
+///   `wrapper->ddgame->rng_state` → base=wrapper+ddgame_off, chain=[rng_state_off]
+fn resolve_address_expr(s: &str, port: u16) -> AddressExpr {
+    let (s, absolute) = if let Some(rest) = s.strip_prefix("abs:") {
+        (rest, true)
+    } else {
+        (s.as_ref(), false)
+    };
+
+    // Split on "->" for chain syntax
+    let parts: Vec<&str> = if s.contains("->") {
+        s.split("->").collect()
+    } else {
+        vec![s]
+    };
+
+    // Resolve the base (first part)
+    let base_part = parts[0];
+    let (base_addr, base_absolute, mut current_class) = resolve_base(base_part, absolute, port);
+
+    if parts.len() == 1 {
+        return AddressExpr::Simple { addr: base_addr, absolute: base_absolute };
+    }
+
+    // Resolve each chain segment, tracking whether it's a field name or hex.
+    let mut segments: Vec<ChainSegment> = Vec::new();
+    for part in &parts[1..] {
+        segments.push(resolve_chain_segment_typed(part, &current_class, port));
+        current_class = None;
+    }
+
+    // Convert to protocol chain format.
+    // HexOffset segments pass through directly (deref then add offset).
+    // FieldOffset segments get folded into the previous position (add offset,
+    // then deref via a [0] chain entry).
+    let mut final_base = base_addr;
+    let mut chain: Vec<u32> = Vec::new();
+
+    for seg in &segments {
+        match seg {
+            ChainSegment::HexOffset(offset) => {
+                chain.push(*offset);
+            }
+            ChainSegment::FieldOffset(offset) => {
+                // Fold into previous: add to base or previous chain entry
+                if chain.is_empty() {
+                    final_base = final_base.wrapping_add(*offset);
+                } else {
+                    let last = chain.last_mut().unwrap();
+                    *last = last.wrapping_add(*offset);
+                }
+                chain.push(0); // deref with no extra offset
+            }
+        }
+    }
+
+    AddressExpr::Chain { addr: final_base, chain, absolute: base_absolute }
+}
+
+/// Resolve the base address part — could be a hex literal, a named alias, or alias+offset.
+fn resolve_base(s: &str, absolute: bool, port: u16) -> (u32, bool, Option<String>) {
+    let (base_str, offset_str) = split_compound(s);
+
+    // If it looks like hex (starts with digit or 0x), parse directly
+    if looks_like_hex(base_str) {
+        let extra = offset_str.map(|o| parse_u32(o)).unwrap_or(0);
+        return (parse_hex(base_str).wrapping_add(extra), absolute, None);
+    }
+
+    // Try resolving as a named alias
+    match send_request(port, &Request::ResolveAlias { name: base_str.to_string() }) {
+        Ok(Response::AliasResult(alias)) => {
+            // Resolved! Use runtime address (absolute)
+            let class = Some(alias.class_name);
+            let extra = offset_str.map(|o| resolve_offset(o, &class, port)).unwrap_or(0);
+            (alias.runtime_addr.wrapping_add(extra), true, class)
+        }
+        _ => {
+            // Fall back to hex parse (will error if not valid hex)
+            let extra = offset_str.map(|o| parse_u32(o)).unwrap_or(0);
+            (parse_hex(base_str).wrapping_add(extra), absolute, None)
+        }
+    }
+}
+
+/// Resolve a chain segment, returning whether it was a field name or hex offset.
+fn resolve_chain_segment_typed(s: &str, current_class: &Option<String>, port: u16) -> ChainSegment {
+    let (base_str, offset_str) = split_compound(s);
+    let extra = offset_str.map(|o| resolve_offset(o, current_class, port)).unwrap_or(0);
+
+    // If it looks like hex, parse directly — standard chain semantics
+    if looks_like_hex(base_str) {
+        return ChainSegment::HexOffset(parse_u32(base_str).wrapping_add(extra));
+    }
+
+    // Try resolving as a field name if we know the current class
+    if let Some(class) = current_class {
+        match send_request(port, &Request::ResolveField {
+            class_name: class.clone(),
+            field_name: base_str.to_string(),
+        }) {
+            Ok(Response::FieldResult(f)) => {
+                return ChainSegment::FieldOffset(f.offset.wrapping_add(extra));
+            }
+            _ => {}
+        }
+    }
+
+    // Fall back to numeric parse — treat as hex semantics
+    ChainSegment::HexOffset(parse_u32(base_str).wrapping_add(extra))
+}
+
+/// Check if a string looks like a hex number (starts with 0x or a digit).
+fn looks_like_hex(s: &str) -> bool {
+    s.starts_with("0x") || s.starts_with("0X") || s.chars().next().map_or(false, |c| c.is_ascii_digit())
+}
+
 fn print_usage() {
     eprintln!("Usage: openwa-debug <command> [args...] [--port N] [--format hex|raw]");
     eprintln!();
@@ -347,6 +511,8 @@ fn print_usage() {
     eprintln!("  ping                      Check if server is running");
     eprintln!("  help                      List server commands");
     eprintln!("  read <addr> [len]         Read memory at address (default len=256)");
+    eprintln!("  inspect <class> <addr>    Typed struct inspection (named fields)");
+    eprintln!("  objects                   List tracked live objects");
     eprintln!("  suspend                   Pause game at next frame boundary");
     eprintln!("  resume                    Resume game");
     eprintln!("  step [N]                  Advance N frames (default 1), then pause");
@@ -360,6 +526,9 @@ fn print_usage() {
     eprintln!("  0x669F8C+0x10             Address + hex offset");
     eprintln!("  0x669F8C[16]              Address + decimal offset (bracket notation)");
     eprintln!("  0x7A0884->0xA0->0x2C      Pointer chain (deref at each ->)");
+    eprintln!("  ddgame                    Named alias (resolved via server)");
+    eprintln!("  ddgame->rng_state         Field name chain (deref + field lookup)");
+    eprintln!("  ddgame+rng_state          Named offset (no deref, just offset)");
     eprintln!();
     eprintln!("Options:");
     eprintln!("  --port <N>                Server port (default: 19840)");

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

@@ -21,6 +21,44 @@ pub struct PointerInfo {
     pub detail: Option<String>,
 }
 
+// --- Typed inspection types ---
+
+/// A formatted field value from a struct inspection.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct FieldValue {
+    pub offset: u32,
+    pub name: String,
+    pub size: u32,
+    /// Raw hex representation.
+    pub hex: String,
+    /// Human-readable formatted value.
+    pub display: String,
+}
+
+/// A tracked live object in the DLL.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct LiveObjectInfo {
+    pub runtime_addr: u32,
+    pub ghidra_addr: u32,
+    pub size: u32,
+    pub class_name: String,
+    pub field_count: u32,
+}
+
+/// Result of resolving a named alias (e.g., "ddgame") to an address.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ResolvedAlias {
+    pub runtime_addr: u32,
+    pub class_name: String,
+}
+
+/// Result of resolving a field name to its offset.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ResolvedField {
+    pub offset: u32,
+    pub size: u32,
+}
+
 // --- Protocol messages ---
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -43,6 +81,14 @@ pub enum Request {
     Break { frame: i32 },
     /// Capture a canonicalized game state snapshot.
     Snapshot,
+    /// Typed struct inspection: read all named fields at an address.
+    Inspect { class_name: String, addr: u32, chain: Vec<u32>, absolute: bool },
+    /// List all tracked live objects.
+    ListObjects,
+    /// Resolve a named alias (e.g., "ddgame") to a runtime address.
+    ResolveAlias { name: String },
+    /// Resolve a field name to its offset within a struct.
+    ResolveField { class_name: String, field_name: String },
 }
 
 /// One step in a resolved pointer chain, for display.
@@ -97,6 +143,19 @@ pub enum Response {
     BreakSet { frame: i32 },
     /// Game state snapshot.
     Snapshot { frame: i32, text: String },
+    /// Typed struct inspection result.
+    InspectResult {
+        class_name: String,
+        ghidra_addr: u32,
+        runtime_addr: u32,
+        fields: Vec<FieldValue>,
+    },
+    /// List of tracked live objects.
+    ObjectList { objects: Vec<LiveObjectInfo> },
+    /// Resolved named alias.
+    AliasResult(ResolvedAlias),
+    /// Resolved field offset.
+    FieldResult(ResolvedField),
     Error { message: String },
 }
 

crates/openwa-derive/src/lib.rs

@@ -533,7 +533,7 @@ fn to_screaming_snake(name: &str) -> String {
 /// field (excluding `_unknown*` and `_pad*` prefixes). Offsets and sizes
 /// are computed at compile time via `core::mem::offset_of!()` and
 /// `core::mem::size_of::<Type>()`.
-#[proc_macro_derive(FieldRegistry)]
+#[proc_macro_derive(FieldRegistry, attributes(field))]
 pub fn derive_field_registry(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as DeriveInput);
     let struct_name = &input.ident;
@@ -573,11 +573,16 @@ pub fn derive_field_registry(input: TokenStream) -> TokenStream {
         let doc = extract_doc_comment(&field.attrs);
         let field_ty = &field.ty;
 
+        // Determine ValueKind: check for #[field(kind = "...")] override, else infer
+        let kind = parse_field_kind_attr(&field.attrs)
+            .unwrap_or_else(|| infer_value_kind(field_ty));
+
         entries.push(quote! {
             openwa_core::registry::FieldEntry {
                 offset: core::mem::offset_of!(#struct_name, #field_ident) as u32,
                 name: #field_name,
                 size: core::mem::size_of::<#field_ty>() as u32,
+                kind: #kind,
                 doc: #doc,
             }
         });
@@ -643,3 +648,57 @@ fn extract_doc_comment(attrs: &[syn::Attribute]) -> String {
     }
     doc
 }
+
+/// Parse an explicit `#[field(kind = "Fixed")]` attribute override.
+fn parse_field_kind_attr(attrs: &[syn::Attribute]) -> Option<proc_macro2::TokenStream> {
+    for attr in attrs {
+        if !attr.path().is_ident("field") {
+            continue;
+        }
+        let mut kind_str = None;
+        let _ = attr.parse_nested_meta(|meta| {
+            if meta.path.is_ident("kind") {
+                let value = meta.value()?;
+                let lit: Lit = value.parse()?;
+                if let Lit::Str(s) = lit {
+                    kind_str = Some(s.value());
+                }
+            }
+            Ok(())
+        });
+        if let Some(k) = kind_str {
+            return Some(value_kind_token(&k));
+        }
+    }
+    None
+}
+
+/// Infer `ValueKind` from a field's Rust type.
+fn infer_value_kind(ty: &syn::Type) -> proc_macro2::TokenStream {
+    match ty {
+        syn::Type::Ptr(_) => value_kind_token("Pointer"),
+        syn::Type::Array(_) => value_kind_token("Raw"),
+        syn::Type::Path(tp) => {
+            let last = tp.path.segments.last().map(|s| s.ident.to_string());
+            match last.as_deref() {
+                Some("u8") => value_kind_token("U8"),
+                Some("u16") => value_kind_token("U16"),
+                Some("u32") => value_kind_token("U32"),
+                Some("i8") => value_kind_token("I8"),
+                Some("i16") => value_kind_token("I16"),
+                Some("i32") => value_kind_token("I32"),
+                Some("bool") => value_kind_token("Bool"),
+                Some("Fixed") => value_kind_token("Fixed"),
+                Some("ClassType") => value_kind_token("Enum"),
+                _ => value_kind_token("Raw"),
+            }
+        }
+        _ => value_kind_token("Raw"),
+    }
+}
+
+/// Produce a `openwa_core::registry::ValueKind::Variant` token stream.
+fn value_kind_token(variant: &str) -> proc_macro2::TokenStream {
+    let ident = quote::format_ident!("{}", variant);
+    quote! { openwa_core::registry::ValueKind::#ident }
+}

crates/openwa-wormkit/src/debug_server.rs

@@ -140,6 +140,14 @@ fn handle_request(request: Request) -> Response {
             let frame = crate::debug_sync::current_frame();
             Response::Snapshot { frame, text }
         }
+        Request::Inspect { class_name, addr, chain, absolute } => {
+            handle_inspect(&class_name, addr, &chain, absolute)
+        }
+        Request::ListObjects => handle_list_objects(),
+        Request::ResolveAlias { name } => handle_resolve_alias(&name),
+        Request::ResolveField { class_name, field_name } => {
+            handle_resolve_field(&class_name, &field_name)
+        }
     }
 }
 
@@ -199,6 +207,174 @@ fn handle_read(addr: u32, len: u32, absolute: bool) -> Response {
     }
 }
 
+fn handle_inspect(class_name: &str, addr: u32, chain: &[u32], absolute: bool) -> Response {
+    use openwa_core::field_format::{self, FormatContext};
+    use openwa_core::registry;
+
+    let fields = match registry::struct_fields_for(class_name) {
+        Some(f) => f,
+        None => {
+            return Response::Error {
+                message: format!("No FieldRegistry for '{}'", class_name),
+            };
+        }
+    };
+
+    // Resolve address (possibly through a chain)
+    let (_, runtime_addr, delta) = if chain.is_empty() {
+        resolve_addr(addr, absolute)
+    } else {
+        // Walk chain first
+        let (_, mut current, delta) = resolve_addr(addr, absolute);
+        for &offset in chain {
+            unsafe {
+                if !mem::can_read(current, 4) {
+                    return Response::Error {
+                        message: format!(
+                            "Chain broke: cannot read at runtime:0x{:08X}",
+                            current
+                        ),
+                    };
+                }
+                let value = *(current as *const u32);
+                if value == 0 {
+                    return Response::Error {
+                        message: format!("Chain broke: NULL at runtime:0x{:08X}", current),
+                    };
+                }
+                current = value.wrapping_add(offset);
+            }
+        }
+        (current.wrapping_sub(delta), current, delta)
+    };
+
+    let ghidra_addr = runtime_addr.wrapping_sub(delta);
+    let ctx = FormatContext { delta };
+
+    let mut result_fields = Vec::new();
+    for field in fields.fields {
+        unsafe {
+            let field_ptr = (runtime_addr + field.offset) as *const u8;
+            let size = field.size as usize;
+
+            if !mem::can_read(runtime_addr + field.offset, field.size) {
+                result_fields.push(FieldValue {
+                    offset: field.offset,
+                    name: field.name.to_string(),
+                    size: field.size,
+                    hex: "<unreadable>".into(),
+                    display: "<unreadable>".into(),
+                });
+                continue;
+            }
+
+            let data = core::slice::from_raw_parts(field_ptr, size);
+
+            // Hex representation
+            let hex = data
+                .iter()
+                .map(|b| format!("{:02X}", b))
+                .collect::<Vec<_>>()
+                .join(" ");
+
+            // Formatted display
+            let mut display = String::new();
+            let _ = field_format::format_field(&mut display, data, field, &ctx);
+
+            result_fields.push(FieldValue {
+                offset: field.offset,
+                name: field.name.to_string(),
+                size: field.size,
+                hex,
+                display,
+            });
+        }
+    }
+
+    Response::InspectResult {
+        class_name: class_name.to_string(),
+        ghidra_addr,
+        runtime_addr,
+        fields: result_fields,
+    }
+}
+
+fn handle_list_objects() -> Response {
+    use openwa_core::registry;
+
+    let wa_base = rb(va::IMAGE_BASE);
+    let wa_end = wa_base + 0x300000; // approximate WA image end
+    let delta = wa_base.wrapping_sub(va::IMAGE_BASE);
+    let objects = registry::live_objects()
+        .into_iter()
+        .map(|obj| {
+            // ghidra_addr is only meaningful for image-mapped objects, not heap
+            let ghidra = if obj.ptr >= wa_base && obj.ptr < wa_end {
+                obj.ptr.wrapping_sub(delta)
+            } else {
+                0
+            };
+            LiveObjectInfo {
+                runtime_addr: obj.ptr,
+                ghidra_addr: ghidra,
+                size: obj.size,
+                class_name: obj.class_name.to_string(),
+                field_count: obj.fields.map_or(0, |f| f.fields.len() as u32),
+            }
+        })
+        .collect();
+
+    Response::ObjectList { objects }
+}
+
+fn handle_resolve_alias(name: &str) -> Response {
+    use openwa_core::registry;
+
+    let name_lower = name.to_lowercase();
+    for obj in registry::live_objects() {
+        if obj.class_name.to_lowercase() == name_lower {
+            return Response::AliasResult(ResolvedAlias {
+                runtime_addr: obj.ptr,
+                class_name: obj.class_name.to_string(),
+            });
+        }
+    }
+
+    Response::Error {
+        message: format!("No tracked object matching '{}'", name),
+    }
+}
+
+fn handle_resolve_field(class_name: &str, field_name: &str) -> Response {
+    use openwa_core::registry;
+
+    // Search the class and its CTask inheritance chain for a field by name.
+    // Mirrors the inheritance chain in registry::field_at_inherited.
+    const CTASK_CHAIN: &[&str] = &["CGameTask", "CTask"];
+
+    let search_chain: Vec<&str> = std::iter::once(class_name)
+        .chain(CTASK_CHAIN.iter().copied())
+        .collect();
+
+    for &name in &search_chain {
+        if let Some(fields) = registry::struct_fields_for(name) {
+            for field in fields.fields {
+                if field.name == field_name {
+                    return Response::FieldResult(ResolvedField {
+                        offset: field.offset,
+                        size: field.size,
+                    });
+                }
+            }
+        }
+    }
+
+    Response::Error {
+        message: format!("No field '{}' in '{}' (searched: {})", field_name, class_name,
+            search_chain.join(" -> ")),
+    }
+}
+
 fn handle_read_chain(addr: u32, chain: &[u32], len: u32, absolute: bool) -> Response {
     if len == 0 || len > MAX_READ_SIZE {
         return Response::Error {

crates/openwa-wormkit/src/debug_watchpoint.rs

@@ -126,9 +126,8 @@ unsafe extern "system" fn veh_handler(info: *mut EXCEPTION_POINTERS) -> i32 {
                     let ghidra_eip = eip.wrapping_sub(delta);
 
                     // Walk EBP chain for stack trace
-                    let mut trace = heapless::String::<512>::new();
+                    let mut trace = String::new();
                     let mut ebp = ctx.Ebp;
-                    let _esp = ctx.Esp;
                     for depth in 0..12 {
                         // Validate EBP: must be in plausible stack range, aligned,
                         // and above ESP (stack grows down)
@@ -144,18 +143,13 @@ unsafe extern "system" fn veh_handler(info: *mut EXCEPTION_POINTERS) -> i32 {
                         let ghidra_ret = ret_addr.wrapping_sub(delta);
                         let in_wa = ret_addr >= wa_base && ret_addr < wa_base + 0x300000;
                         if depth > 0 {
-                            let _ = core::fmt::Write::write_str(&mut trace, "<-");
+                            trace.push_str("<-");
                         }
                         if in_wa {
-                            let _ = core::fmt::Write::write_fmt(
-                                &mut trace,
-                                format_args!("{:08X}", ghidra_ret),
-                            );
+                            trace.push_str(&openwa_core::registry::format_va(ghidra_ret));
                         } else {
-                            let _ = core::fmt::Write::write_fmt(
-                                &mut trace,
-                                format_args!("r:{:08X}", ret_addr),
-                            );
+                            use core::fmt::Write;
+                            let _ = write!(trace, "r:{:08X}", ret_addr);
                         }
                         // EBP must increase (frames go up the stack)
                         if next_ebp <= ebp {
@@ -165,8 +159,8 @@ unsafe extern "system" fn veh_handler(info: *mut EXCEPTION_POINTERS) -> i32 {
                     }
 
                     let _ = log_line(&format!(
-                        "[Watchpoint] {} = 0x{:08X}  eip=0x{:08X} stack=[{}]",
-                        name, val, ghidra_eip, trace,
+                        "[Watchpoint] {} = 0x{:08X}  eip={} stack=[{}]",
+                        name, val, openwa_core::registry::format_va(ghidra_eip), trace,
                     ));
                 }
             }

crates/openwa-wormkit/src/snapshot.rs

@@ -7,7 +7,9 @@ use core::fmt::Write;
 
 use openwa_core::address::va;
 use openwa_core::engine::GameSession;
+use openwa_core::field_format::{self, FormatContext};
 use openwa_core::rebase::rb;
+use openwa_core::registry::StructFields;
 use openwa_core::snapshot::{hash_pointer_targets, write_raw_region, Snapshot};
 use openwa_core::task::{CTask, CTaskBfsIter, CTaskMissile, CTaskWorm};
 
@@ -144,9 +146,17 @@ pub unsafe fn capture() -> String {
                 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);
+                // Try FieldRegistry-based dump for known types
+                let class = vtable_name(vt);
+                if class != "Unknown" {
+                    if let Some(fields) = openwa_core::registry::struct_fields_for(class) {
+                        let _ = write_registry_fields(&mut out, task as *const u8, fields, delta, 2);
+                    } else {
+                        let _ = write_raw_region(&mut out, task as *const u8, 0x100, 2);
+                    }
+                } else {
+                    let _ = write_raw_region(&mut out, task as *const u8, 0x100, 2);
+                }
             }
         }
         let _ = writeln!(out);
@@ -158,3 +168,34 @@ pub unsafe fn capture() -> String {
 fn vtable_name(ghidra_vt: u32) -> &'static str {
     openwa_core::registry::vtable_class_name(ghidra_vt).unwrap_or("Unknown")
 }
+
+/// Write struct fields using FieldRegistry metadata and the format_field system.
+///
+/// Produces output like:
+/// ```text
+///     +0x0000  vtable           [4]  0x0066A30C (DDGameWrapper vtable)
+///     +0x0004  parent           [4]  null
+/// ```
+unsafe fn write_registry_fields(
+    w: &mut dyn Write,
+    base: *const u8,
+    fields: &StructFields,
+    delta: u32,
+    indent: usize,
+) -> core::fmt::Result {
+    let ctx = FormatContext { delta };
+    let pad = "  ".repeat(indent);
+    for field in fields.fields {
+        let addr = base as u32 + field.offset;
+        write!(w, "{}+0x{:04X}  {:<16} [{:>2}]  ", pad, field.offset, field.name, field.size)?;
+        if openwa_core::mem::can_read(addr, field.size) {
+            let ptr = base.add(field.offset as usize);
+            let data = core::slice::from_raw_parts(ptr, field.size as usize);
+            field_format::format_field(w, data, field, &ctx)?;
+        } else {
+            write!(w, "<unreadable>")?;
+        }
+        writeln!(w)?;
+    }
+    Ok(())
+}

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

@@ -108,28 +108,23 @@ fn validate_addresses(result: &mut ValidationResult) {
     let _ = log_validation("");
     let _ = log_validation("--- Address Validation ---");
 
-    let vtables: &[(&str, u32)] = &[
-        ("CTask vtable", va::CTASK_VTABLE),
-        ("CGameTask vtable", va::CGAMETASK_VTABLE),
-        (
-            "CGameTask SoundEmitter vtable",
-            va::CGAMETASK_SOUND_EMITTER_VT,
-        ),
-        ("DDGameWrapper vtable", va::DDGAME_WRAPPER_VTABLE),
-        ("GfxHandler vtable", va::GFX_DIR_VTABLE),
-        ("DisplayGfx vtable", va::DISPLAY_GFX_VTABLE),
-        ("PCLandscape vtable", va::PC_LANDSCAPE_VTABLE),
-        ("LandscapeShader vtable", va::LANDSCAPE_SHADER_VTABLE),
-        // DSSound vtable excluded: all 24 slots patched to Rust function pointers
-        ("BitGrid vtable", va::TASK_STATE_MACHINE_VTABLE),
-        ("OpenGLCPU vtable", va::OPENGL_CPU_VTABLE),
-        ("WaterEffect vtable", va::WATER_EFFECT_VTABLE),
-    ];
+    // Auto-discover all registered vtables from the address registry
+    let vtables: Vec<(&str, u32)> = openwa_core::registry::entries_by_kind(
+        openwa_core::registry::AddrKind::Vtable,
+    )
+    .map(|e| {
+        let name = e.class_name.map_or(e.name, |c| c);
+        (name, e.va)
+    })
+    .collect();
 
     let _ = log_validation("");
-    let _ = log_validation("  Vtable location checks (.rdata range):");
-    for (name, ghidra_addr) in vtables {
-        let addr = rb(*ghidra_addr);
+    let _ = log_validation(&format!(
+        "  Vtable location checks (.rdata range) — {} registered vtables:",
+        vtables.len()
+    ));
+    for &(name, ghidra_addr) in &vtables {
+        let addr = rb(ghidra_addr);
         let in_rdata = is_in_rdata(addr);
         result.check(
             &format!("{} location", name),
@@ -149,8 +144,8 @@ fn validate_addresses(result: &mut ValidationResult) {
 
     let _ = log_validation("");
     let _ = log_validation("  Vtable first-entry checks (should point to .text):");
-    for (name, ghidra_addr) in vtables {
-        let addr = rb(*ghidra_addr);
+    for &(name, ghidra_addr) in &vtables {
+        let addr = rb(ghidra_addr);
         unsafe {
             let first_entry = read_u32(addr);
             let in_text = is_in_text(first_entry);
@@ -262,6 +257,49 @@ fn validate_addresses(result: &mut ValidationResult) {
     }
 }
 
+// ---------------------------------------------------------------------------
+// Typed vtable slot validation (from #[vtable(...)] metadata)
+// ---------------------------------------------------------------------------
+
+fn validate_typed_vtable_slots(result: &mut ValidationResult) {
+    let _ = log_validation("");
+    let _ = log_validation("--- Typed Vtable Slot Validation (#[vtable(...)]) ---");
+
+    let mut vtable_count = 0;
+    let mut slot_count = 0;
+
+    for info in openwa_core::registry::all_vtable_info() {
+        if info.ghidra_va == 0 {
+            continue;
+        }
+        vtable_count += 1;
+        let vt_runtime = rb(info.ghidra_va);
+
+        for slot in info.slots {
+            slot_count += 1;
+            unsafe {
+                let slot_addr = vt_runtime + slot.index * 4;
+                let actual = read_u32(slot_addr);
+                let in_text = is_in_text(actual);
+                result.check(
+                    &format!("{}::{} [slot {}]", info.class_name, slot.name, slot.index),
+                    in_text,
+                    &format!(
+                        "0x{:08X} {}",
+                        actual,
+                        if in_text { "in .text" } else { "NOT in .text — hooked or corrupt?" }
+                    ),
+                );
+            }
+        }
+    }
+
+    let _ = log_validation(&format!(
+        "  Checked {} named slots across {} typed vtables",
+        slot_count, vtable_count
+    ));
+}
+
 // ---------------------------------------------------------------------------
 // Struct offset validation
 // ---------------------------------------------------------------------------
@@ -1686,6 +1724,7 @@ pub fn run() -> Result<(), String> {
     let mut result = ValidationResult::new();
 
     validate_addresses(&mut result);
+    validate_typed_vtable_slots(&mut result);
     validate_struct_offsets(&mut result);
 
     let _ = log_validation("");