feat: add runtime-validated PCLandscape struct, landscape dump via F10 hotkey

Rewrote PCLandscape struct with fields verified against live game memory:
crater sprites, collision bitmap, dirty rect queue, 6 terrain layers,
level/theme paths, visible bounds, GfxHandlers. Added DirtyRect struct
and vtable_slots module. Added 5 new landscape function addresses.
Validator now dumps full PCLandscape state on F10 or after 15s delay.

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

crates/openwa-types/src/address.rs

@@ -171,9 +171,18 @@ pub mod va {
     // === Landscape ===
 
     pub const CONSTRUCT_PC_LANDSCAPE: u32 = 0x0057_ACB0;
+    pub const DESTRUCT_PC_LANDSCAPE: u32 = 0x0057_B540;
     pub const CONSTRUCT_SPRITE_REGION: u32 = 0x0057_DB20;
     pub const REDRAW_LAND_REGION: u32 = 0x0057_CC10;
     pub const WRITE_LAND_RAW: u32 = 0x0057_C300;
+    /// Applies explosion crater to terrain — destroys pixels + collision (vtable slot 2).
+    pub const PC_LANDSCAPE_APPLY_EXPLOSION: u32 = 0x0057_C820;
+    /// Draws 8px checkered borders at landscape edges (vtable slot 6).
+    pub const PC_LANDSCAPE_DRAW_BORDERS: u32 = 0x0057_D7F0;
+    /// Redraws a single terrain row (vtable slot 8).
+    pub const PC_LANDSCAPE_REDRAW_ROW: u32 = 0x0057_CF60;
+    /// Clips and merges dirty rectangles for terrain redraw.
+    pub const PC_LANDSCAPE_CLIP_AND_MERGE: u32 = 0x0057_D2B0;
 
     // === Sound ===
 

crates/openwa-types/src/landscape.rs

@@ -1,61 +1,121 @@
 use crate::task::Ptr32;
 
-/// PCLandscape — terrain/landscape subsystem.
+/// PCLandscape — terrain/landscape subsystem (0xB40 bytes).
 ///
-/// Created by PCLandscape__Constructor (0x57ACB0).
-/// Vtable: 0x66B208
+/// Created by `PCLandscape__Constructor` (0x57ACB0). Vtable: 0x66B208 (32 slots).
 ///
-/// Manages terrain data, water effects, and level graphics.
-/// Loads Water.dir and Level.dir from `data\Gfx\`.
-/// Allocates a 384KB (0x60000) terrain buffer.
+/// Manages terrain pixel data (8-bit indexed/paletted), collision bitmap,
+/// water effects, and level graphics. Loads `Water.dir` and `Level.dir`.
 ///
-/// PARTIAL: Only constructor-confirmed fields are defined.
-/// Ghidra uses DWORD-indexed offsets (param_1[0x240] etc.).
-/// Byte offset = dword_index * 4.
+/// ## Rendering pipeline
+/// - Terrain is stored as multiple pixel layers (DisplayGfx objects)
+/// - Collision uses a 1-bit-per-pixel packed bitmap at +0x0D0
+/// - Dirty rects queued via `RedrawLandRegion` (up to 256, 8 bytes each)
+/// - `DrawLandscape` (0x5A2790) blits landscape pixels to framebuffer
+///   (memcpy for opaque, per-pixel color-key for transparent)
+/// - `WriteLandRaw` (0x57C300) modifies terrain across all layers + collision
+///
+/// ## Key dimensions (stored in DDGame, set by constructor)
+/// - DDGame+0x77C0: level width
+/// - DDGame+0x77C4: level height
+/// - DDGame+0x77C8: width × height (total pixels)
+///
+/// Ghidra uses DWORD-indexed offsets (param_1[N] = byte offset N*4).
 #[repr(C)]
 pub struct PCLandscape {
     /// 0x000: Vtable pointer (0x66B208)
     pub vtable: Ptr32,
-    /// 0x004: Parent DDGame pointer
+    /// 0x004: Parent DDGame pointer (param_1[1])
     pub ddgame: Ptr32,
-    /// 0x008-0x0C7: Unknown
-    pub _unknown_008: [u8; 0xC0],
-    /// 0x0C8: Water effect object pointer (0xBC bytes, vtable 0x66B268)
-    pub water_effect: Ptr32,
-    /// 0x0CC-0x8E7: Unknown fields (terrain metadata, dimensions, etc.)
-    pub _unknown_0cc: [u8; 0x81C],
-    /// 0x8E8: Terrain buffer pointer (0x60000 bytes allocated)
-    pub terrain_buffer: Ptr32,
-    /// 0x8EC-0x8EF: Buffer size (0x60000)
-    pub _terrain_size: [u8; 4],
-    /// 0x8F0-0x90F: Unknown
-    pub _unknown_8f0: [u8; 0x20],
-    /// 0x910-0x913: Terrain handler pointer
-    pub terrain_handler: Ptr32,
-    /// 0x914: Initialized flag (set to 1)
+    /// 0x008-0x0CB: Pre-rendered crater sprites for 15 explosion sizes.
+    /// param_1[2..17]: crater image ptrs, param_1[18..33]: secondary ptrs.
+    /// Indexed by `explosion_size * 15 / 100`.
+    pub crater_sprites: [Ptr32; 16],
+    pub crater_sprites_secondary: [Ptr32; 16],
+    /// 0x088-0x0CB: Unknown
+    pub _unknown_088: [u8; 0x44],
+    /// 0x0CC: Resource handle (param_1[0x33])
+    pub resource_handle: Ptr32,
+    /// 0x0D0: Collision bitmap pointer — 1 bit per pixel, packed into DWORDs.
+    /// Width = (level_width + 7) / 8 rounded to 4-byte alignment.
+    pub collision_bitmap: Ptr32,
+    /// 0x0D4: Dirty rect array — 256 entries, each 8 bytes (x1,y1,x2,y2 as u16).
+    /// Queued by `RedrawLandRegion`, flushed during frame render.
+    pub dirty_rects: [DirtyRect; 256],
+    /// 0x8D4: Number of dirty rects queued (max 256, overflows call flush)
+    pub dirty_rect_count: u32,
+    /// 0x8D8: Dirty flag — set to 1 when any rect is queued
+    pub dirty_flag: u8,
+    /// 0x8D9-0x8EB: Unknown
+    pub _unknown_8d9: [u8; 0x13],
+    /// 0x8EC: Unknown (zero at runtime)
+    pub _unknown_8ec: u32,
+    /// 0x8F0: Unknown (0x9B at runtime — small integer, not pointer)
+    pub _unknown_8f0: u32,
+    /// 0x8F4: Unknown (zero at runtime)
+    pub _unknown_8f4: u32,
+    /// 0x8F8-0x8FF: Unknown
+    pub _unknown_8f8: [u8; 8],
+    /// 0x900: Unknown (NOT DDGame — runtime value 0x13300048 doesn't match DDGame ptr)
+    pub _unknown_900: Ptr32,
+    /// 0x904: Initialized flag (param_1[0x241], set to 1)
     pub initialized: u32,
-    /// 0x918-0x92F: Terrain directory path pointers
-    pub _dir_paths: [u8; 0x18],
-    /// 0x930: Splash buffer pointer (0x4C bytes)
-    pub splash_buffer: Ptr32,
-    /// 0x934: Terrain data pointer
-    pub terrain_data: Ptr32,
-    /// 0x938: Palette pointer
-    pub palette: Ptr32,
-    /// 0x93C: Shader object pointer (vtable 0x66B1DC)
-    pub shader: Ptr32,
-    /// 0x940-0x947: Surface texture buffer pointers
-    pub surface_textures: [Ptr32; 2],
-    /// 0x948-0x94B: Unknown
-    pub _unknown_948: [u8; 4],
-    /// 0x94C-0xB33: Unknown
-    pub _unknown_94c: [u8; 0x1E8],
-    /// 0xB34: Water .dir file handle
-    pub water_dir_handle: Ptr32,
-    /// 0xB38: Level .dir file handle
-    pub level_dir_handle: Ptr32,
-    /// 0xB3C-0xB3F: Trailing padding
-    pub _unknown_b3c: [u8; 4],
+    /// 0x908: Terrain layer 0 — DisplayGfx* (collision visual / background)
+    pub layer_0: Ptr32,
+    /// 0x90C: Terrain layer 1 — DisplayGfx*
+    pub layer_1: Ptr32,
+    /// 0x910: Terrain layer 2 — DisplayGfx* (main terrain image).
+    /// Pixel data at `*(layer_2 + 8)`, width at `*(layer_2 + 0x14)`,
+    /// height at `*(layer_2 + 0x18)`, stride at `*(layer_2 + 0x10)`.
+    pub layer_terrain: Ptr32,
+    /// 0x914: Terrain layer 3 — DisplayGfx* (edge/shading layer)
+    pub layer_edges: Ptr32,
+    /// 0x918-0x91B: Unknown
+    pub _unknown_918: [u8; 4],
+    /// 0x91C: Terrain layer 4 — DisplayGfx* (shadow/overlay)
+    pub layer_shadow: Ptr32,
+    /// 0x920: Terrain layer 5 — DisplayGfx*
+    pub layer_5: Ptr32,
+    /// 0x924: Level directory path (char buffer, ~0x100 bytes)
+    pub level_dir_path: [u8; 0x100],
+    /// 0xA24: Theme/data directory path (char buffer, 0x100 bytes)
+    pub theme_dir_path: [u8; 0x100],
+    /// 0xB24-0xB2F: Visible bounds (left, top, right, bottom)
+    pub visible_left: u32,
+    pub visible_top: u32,
+    pub visible_right: u32,
+    pub visible_bottom: u32,
+    /// 0xB34: GfxHandler for Level.dir (param_1[0x2CD])
+    pub level_gfx_handler: Ptr32,
+    /// 0xB38: GfxHandler for Water.dir (param_1[0x2CE])
+    pub water_gfx_handler: Ptr32,
+    /// 0xB3C: Remaining control flag
+    pub _unknown_b3c: u32,
 }
 
 const _: () = assert!(core::mem::size_of::<PCLandscape>() == 0xB40);
+
+/// A dirty rectangle entry in the PCLandscape dirty rect queue.
+/// Coordinates are in landscape pixel space.
+#[repr(C)]
+#[derive(Clone, Copy)]
+pub struct DirtyRect {
+    pub x1: u16,
+    pub y1: u16,
+    pub x2: u16,
+    pub y2: u16,
+}
+
+const _: () = assert!(core::mem::size_of::<DirtyRect>() == 8);
+
+/// PCLandscape vtable slot indices (32 entries at 0x66B208).
+pub mod vtable_slots {
+    /// Slot 0: Destructor (0x57B540)
+    pub const DESTRUCTOR: usize = 0;
+    /// Slot 2: Apply explosion crater (0x57C820) — terrain destruction
+    pub const APPLY_EXPLOSION: usize = 2;
+    /// Slot 6: Draw borders — 8px checkered borders at landscape edges (0x57D7F0)
+    pub const DRAW_BORDERS: usize = 6;
+    /// Slot 8: Redraw single row (0x57CF60)
+    pub const REDRAW_ROW: usize = 8;
+}

crates/openwa-validator/src/lib.rs

@@ -617,6 +617,158 @@ fn dump_team_blocks() {
     }
 }
 
+// ---------------------------------------------------------------------------
+// PCLandscape dump (for landscape struct verification)
+// ---------------------------------------------------------------------------
+
+fn dump_landscape() {
+    use openwa_types::landscape::PCLandscape;
+
+    let dump_num = DUMP_COUNTER.fetch_add(1, Ordering::Relaxed);
+    let _ = log_line("");
+    let _ = log_line(&format!("--- PCLandscape Dump #{} ---", dump_num));
+
+    unsafe {
+        let session_ptr = read_u32(rb(va::G_GAME_SESSION));
+        if session_ptr == 0 {
+            let _ = log_line("  No game session — skipping.");
+            return;
+        }
+
+        let wrapper_addr = read_u32(session_ptr + 0xA0);
+        if wrapper_addr == 0 {
+            let _ = log_line("  No DDGameWrapper — need to start a game first.");
+            return;
+        }
+
+        let landscape_ptr = read_u32(wrapper_addr + 0x4CC);
+        if landscape_ptr == 0 {
+            let _ = log_line("  PCLandscape is NULL — no level loaded.");
+            return;
+        }
+
+        let land = &*(landscape_ptr as *const PCLandscape);
+        let _ = log_line(&format!("  PCLandscape @ 0x{:08X}", landscape_ptr));
+
+        // Vtable validation
+        let expected_vt = rb(va::PC_LANDSCAPE_VTABLE);
+        let vt_ok = land.vtable == expected_vt;
+        let _ = log_line(&format!("  vtable: 0x{:08X} (expected 0x{:08X}) {}",
+            land.vtable, expected_vt, if vt_ok { "OK" } else { "MISMATCH" }));
+
+        // DDGame pointer
+        let _ = log_line(&format!("  ddgame: 0x{:08X}", land.ddgame));
+        let _ = log_line(&format!("  _unknown_900: 0x{:08X}", land._unknown_900));
+
+        // Collision bitmap
+        let _ = log_line(&format!("  collision_bitmap: 0x{:08X}", land.collision_bitmap));
+
+        // Initialized flag
+        let _ = log_line(&format!("  initialized: {}", land.initialized));
+
+        // Crater sprites — count non-null
+        let primary_count = land.crater_sprites.iter().filter(|&&p| p != 0).count();
+        let secondary_count = land.crater_sprites_secondary.iter().filter(|&&p| p != 0).count();
+        let _ = log_line(&format!("  crater_sprites: {}/16 non-null, secondary: {}/16 non-null",
+            primary_count, secondary_count));
+
+        // Terrain layers
+        let _ = log_line(&format!("  layer_0: 0x{:08X}", land.layer_0));
+        let _ = log_line(&format!("  layer_1: 0x{:08X}", land.layer_1));
+        let _ = log_line(&format!("  layer_terrain: 0x{:08X}", land.layer_terrain));
+        let _ = log_line(&format!("  layer_edges: 0x{:08X}", land.layer_edges));
+        let _ = log_line(&format!("  layer_shadow: 0x{:08X}", land.layer_shadow));
+        let _ = log_line(&format!("  layer_5: 0x{:08X}", land.layer_5));
+
+        // If layer_terrain is valid, read DisplayGfx fields
+        if land.layer_terrain != 0 {
+            let dgfx = land.layer_terrain;
+            let pixel_data = read_u32(dgfx + 0x08);
+            let stride = read_u32(dgfx + 0x10);
+            let width = read_u32(dgfx + 0x14);
+            let height = read_u32(dgfx + 0x18);
+            let _ = log_line(&format!("  layer_terrain DisplayGfx: pixels=0x{:08X} stride={} width={} height={}",
+                pixel_data, stride, width, height));
+        }
+
+        // Dirty rects
+        let _ = log_line(&format!("  dirty_rect_count: {}", land.dirty_rect_count));
+        let _ = log_line(&format!("  dirty_flag: {}", land.dirty_flag));
+        if land.dirty_rect_count > 0 && land.dirty_rect_count <= 256 {
+            for i in 0..land.dirty_rect_count.min(5) as usize {
+                let r = &land.dirty_rects[i];
+                let _ = log_line(&format!("    rect[{}]: ({},{})..({},{})",
+                    i, r.x1, r.y1, r.x2, r.y2));
+            }
+            if land.dirty_rect_count > 5 {
+                let _ = log_line(&format!("    ... and {} more", land.dirty_rect_count - 5));
+            }
+        }
+
+        // Unknown fields around palette area
+        let _ = log_line(&format!("  _unknown_8ec: 0x{:08X}", land._unknown_8ec));
+        let _ = log_line(&format!("  _unknown_8f0: 0x{:08X}", land._unknown_8f0));
+        let _ = log_line(&format!("  _unknown_8f4: 0x{:08X}", land._unknown_8f4));
+
+        // Resource handle
+        let _ = log_line(&format!("  resource_handle: 0x{:08X}", land.resource_handle));
+
+        // GfxHandlers
+        let _ = log_line(&format!("  level_gfx_handler: 0x{:08X}", land.level_gfx_handler));
+        let _ = log_line(&format!("  water_gfx_handler: 0x{:08X}", land.water_gfx_handler));
+
+        // Visible bounds
+        let _ = log_line(&format!("  visible_bounds: left={} top={} right={} bottom={}",
+            land.visible_left, land.visible_top, land.visible_right, land.visible_bottom));
+
+        // Path buffers — read as C strings
+        let level_path = std::ffi::CStr::from_ptr(land.level_dir_path.as_ptr() as *const i8);
+        let theme_path = std::ffi::CStr::from_ptr(land.theme_dir_path.as_ptr() as *const i8);
+        let _ = log_line(&format!("  level_dir_path: {:?}", level_path));
+        let _ = log_line(&format!("  theme_dir_path: {:?}", theme_path));
+
+        // DDGame level dimensions (from DDGame, not PCLandscape)
+        let ddgame_ptr = land.ddgame;
+        if ddgame_ptr != 0 {
+            let level_w = read_u32(ddgame_ptr + 0x77C0);
+            let level_h = read_u32(ddgame_ptr + 0x77C4);
+            let level_total = read_u32(ddgame_ptr + 0x77C8);
+            let _ = log_line(&format!("  DDGame level dims: {}x{} (total={})",
+                level_w, level_h, level_total));
+        }
+
+        // Vtable slot dump (first 10 entries)
+        let _ = log_line("  Vtable slots:");
+        let vt_addr = land.vtable;
+        for slot in 0..10u32 {
+            let entry = read_u32(vt_addr + slot * 4);
+            let in_text = is_in_text(entry);
+            let _ = log_line(&format!("    [{}]: 0x{:08X} {}",
+                slot, entry, if in_text { "" } else { "(NOT .text)" }));
+        }
+
+        let _ = log_line(&format!("  _unknown_b3c: 0x{:08X}", land._unknown_b3c));
+
+        // Hex dump of unknown regions for discovery
+        let _ = log_line("  _unknown_088 (0x44 bytes):");
+        let _ = log_hex_dump(&land._unknown_088);
+        let _ = log_line("  _unknown_8d9 (0x13 bytes):");
+        let _ = log_hex_dump(&land._unknown_8d9);
+        let _ = log_line("  _unknown_8f8 (8 bytes):");
+        let _ = log_hex_dump(&land._unknown_8f8);
+        let _ = log_line("  _unknown_918 (4 bytes):");
+        let _ = log_hex_dump(&land._unknown_918);
+    }
+}
+
+fn log_hex_dump(data: &[u8]) {
+    for chunk in data.chunks(16) {
+        let hex: String = chunk.iter().map(|b| format!("{:02X}", b)).collect::<Vec<_>>().join(" ");
+        let ascii: String = chunk.iter().map(|&b| if (0x20..0x7F).contains(&b) { b as char } else { '.' }).collect();
+        let _ = log_line(&format!("    {} | {}", hex, ascii));
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Main validation entry point
 // ---------------------------------------------------------------------------
@@ -678,16 +830,27 @@ fn run_validation() -> Result<(), Box<dyn std::error::Error>> {
     });
     let _ = log_line("  Team block dump thread started (30s delay).");
 
-    // 9. Hotkey listener — F9 triggers a team block dump on demand
+    // 8b. Landscape dump — wait 15s (landscape exists at menu too)
+    std::thread::spawn(move || {
+        std::thread::sleep(std::time::Duration::from_secs(15));
+        dump_landscape();
+    });
+    let _ = log_line("  Landscape dump thread started (15s delay).");
+
+    // 9. Hotkey listener — F9 = team blocks, F10 = landscape
     std::thread::spawn(|| {
         const VK_F9: i32 = 0x78;
-        let _ = log_line("  Hotkey listener started (press F9 to dump team blocks).");
+        const VK_F10: i32 = 0x79;
+        let _ = log_line("  Hotkey listener started (F9=team blocks, F10=landscape).");
         loop {
             std::thread::sleep(std::time::Duration::from_millis(100));
-            let state = unsafe { GetAsyncKeyState(VK_F9) };
-            // Bit 0 = key was pressed since last call
-            if state & 1 != 0 {
-                dump_team_blocks();
+            unsafe {
+                if GetAsyncKeyState(VK_F9) & 1 != 0 {
+                    dump_team_blocks();
+                }
+                if GetAsyncKeyState(VK_F10) & 1 != 0 {
+                    dump_landscape();
+                }
             }
         }
     });