Add DDGame engine architecture structs and subsystem types

Define DDGame (0x98B8), DDGameWrapper, PCLandscape, DSSound, and
OpenGLState repr(C) structs with compile-time size assertions.
Add 9 subsystem vtable addresses to address.rs. Document the
engine initialization chain and update memory map with DDGame layout.

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

crates/openwa-types/src/address.rs

@@ -26,6 +26,24 @@ pub mod va {
     pub const CGAMETASK_VTABLE: u32 = 0x0066_41F8;
     /// CGameTask secondary vtable (at object offset 0xE8)
     pub const CGAMETASK_VTABLE2: u32 = 0x0066_9CF8;
+    /// DDGameWrapper vtable
+    pub const DDGAME_WRAPPER_VTABLE: u32 = 0x0066_A30C;
+    /// GfxHandler vtable (0x19C-byte objects)
+    pub const GFX_HANDLER_VTABLE: u32 = 0x0066_B280;
+    /// DisplayGfx vtable
+    pub const DISPLAY_GFX_VTABLE: u32 = 0x0066_4144;
+    /// PCLandscape vtable
+    pub const PC_LANDSCAPE_VTABLE: u32 = 0x0066_B208;
+    /// LandscapeShader vtable
+    pub const LANDSCAPE_SHADER_VTABLE: u32 = 0x0066_B1DC;
+    /// DSSound vtable
+    pub const DS_SOUND_VTABLE: u32 = 0x0066_AF20;
+    /// TaskStateMachine vtable
+    pub const TASK_STATE_MACHINE_VTABLE: u32 = 0x0066_4118;
+    /// OpenGLCPU vtable (0x48-byte object)
+    pub const OPENGL_CPU_VTABLE: u32 = 0x0067_74C0;
+    /// WaterEffect vtable (0xBC-byte object)
+    pub const WATER_EFFECT_VTABLE: u32 = 0x0066_B268;
 
     // === CTask vtable methods (at CTask__vtable) ===
 

crates/openwa-types/src/ddgame.rs

@@ -0,0 +1,103 @@
+use crate::task::Ptr32;
+
+/// DDGame — the main game engine object.
+///
+/// This is a massive ~39KB struct (0x98B8 bytes) that owns all major subsystems:
+/// display, landscape, sound, graphics handlers, and task state machines.
+///
+/// Allocated in DDGame__Constructor (0x56E220).
+/// Vtable set via DDGameWrapper at 0x66A30C.
+///
+/// PARTIAL: Only landmark offsets are defined. The vast majority of fields
+/// are unknown. Use the offset constants below for field access.
+///
+/// Note: Ghidra decompiles DDGame constructor with DWORD-indexed offsets
+/// (param_2[0x122] etc.), but these are byte offsets in the struct below.
+/// Conversion: dword_index * 4 = byte_offset.
+#[repr(C)]
+pub struct DDGame {
+    /// 0x0000-0x0023: Header region
+    pub _header: [u8; 0x24],
+    /// 0x0024: Game state pointer
+    pub game_state: Ptr32,
+    /// 0x0028: Unknown parameter from constructor
+    pub _param_28: Ptr32,
+    /// 0x002C-0x11AF: Unknown fields
+    pub _unknown_002c: [u8; 0x1184],
+    /// 0x11B0-0x11BF: Task objects region (5 state machine pointers)
+    /// Ghidra: param[0x46C..0x47C] (dword-indexed)
+    pub task_ptrs: [Ptr32; 5],
+    /// 0x11C4-0x1217: Unknown
+    pub _unknown_11c4: [u8; 0x54],
+    /// 0x1218-0x1223: Game global / WormKit-known offsets area
+    /// Note: WormKit documents DDGame+0x488 as game_global, but that's
+    /// relative to the DDGame ptr held in DDGameWrapper[0x122].
+    /// Since DDGameWrapper[0x122] points to THIS struct at offset 0,
+    /// these WormKit offsets map directly.
+    pub _unknown_1218: [u8; 0x270],
+    /// 0x1488-0x3547: Unknown fields
+    pub _unknown_1488: [u8; 0x20C0],
+    /// 0x3548: Display mode pointer
+    pub display_mode: Ptr32,
+    /// 0x354C: Display width
+    pub display_width: u32,
+    /// 0x3550: Display param (init 0)
+    pub _display_3550: u32,
+    /// 0x3554: Display param (init 0)
+    pub _display_3554: u32,
+    /// 0x3558-0x355F: Unknown
+    pub _unknown_3558: [u8; 8],
+    /// 0x3560: Display center X (width / 2)
+    pub display_center_x: u32,
+    /// 0x3564: Display center Y (height / 2)
+    pub display_center_y: u32,
+    /// 0x3568-0x3577: Unknown
+    pub _unknown_3568: [u8; 0x10],
+    /// 0x3578: Window handle (HWND)
+    pub hwnd: Ptr32,
+    /// 0x357C-0x358C: Unknown
+    pub _unknown_357c: [u8; 0x11],
+    /// 0x358D-0x398C: Palette entries (0x100 * 4 = 1024 bytes)
+    pub palette: [u8; 0x400],
+    /// 0x398D-0x3D8F: Unknown display fields
+    pub _unknown_398d: [u8; 0x403],
+    /// 0x3D90: Graphics constant (init 0x100)
+    pub _gfx_3d90: u32,
+    /// 0x3D94: Graphics constant (init 0xFFFFFFFF)
+    pub _gfx_3d94: u32,
+    /// 0x3D98: Graphics object pointers (4 entries)
+    pub gfx_objects: [Ptr32; 4],
+    /// 0x3DA8-0x98B7: Remaining fields
+    pub _unknown_3da8: [u8; 0x5B10],
+}
+
+const _: () = assert!(core::mem::size_of::<DDGame>() == 0x98B8);
+
+/// Well-known byte offsets into DDGame, for use with raw pointer access.
+///
+/// These are sourced from WormKit, wkJellyWorm, and Ghidra decompilation.
+/// WormKit documents offsets relative to DDGameWrapper[0x122] which points
+/// to the DDGame allocation.
+pub mod offsets {
+    /// Game state pointer
+    pub const GAME_STATE: usize = 0x0024;
+
+    /// Task state machine pointers (5 entries, each Ptr32)
+    pub const TASK_PTRS: usize = 0x11B0;
+
+    /// Display mode pointer
+    pub const DISPLAY_MODE: usize = 0x3548;
+    /// Display width
+    pub const DISPLAY_WIDTH: usize = 0x354C;
+    /// Display center X
+    pub const DISPLAY_CENTER_X: usize = 0x3560;
+    /// Display center Y
+    pub const DISPLAY_CENTER_Y: usize = 0x3564;
+    /// Window handle (HWND)
+    pub const HWND: usize = 0x3578;
+    /// Palette start (0x400 bytes)
+    pub const PALETTE: usize = 0x358D;
+
+    /// Graphics object pointers (from DDDisplay__Init)
+    pub const GFX_OBJECTS: usize = 0x3D98;
+}

crates/openwa-types/src/ddgame_wrapper.rs

@@ -0,0 +1,45 @@
+use crate::task::Ptr32;
+
+/// DDGameWrapper — thin wrapper around DDGame.
+///
+/// This is the top-level object created by DDGameWrapper__Constructor (0x56DEF0).
+/// It holds a pointer to the DDGame allocation and graphics handler references.
+///
+/// Vtable: 0x66A30C
+///
+/// Note: Ghidra shows DWORD-indexed offsets (param_1[0x122] etc.).
+/// Byte offset = dword_index * 4.
+///
+/// PARTIAL: Only confirmed fields from the constructor are defined.
+#[repr(C)]
+pub struct DDGameWrapper {
+    /// 0x000: Vtable pointer (0x66A30C)
+    pub vtable: Ptr32,
+    /// 0x004-0x487: Unknown fields
+    pub _unknown_004: [u8; 0x484],
+    /// 0x488: Pointer to DDGame allocation
+    pub ddgame: Ptr32,
+    /// 0x48C: Secondary DDGame struct pointer (0x2C bytes, conditional)
+    pub ddgame_secondary: Ptr32,
+    /// 0x490-0x4BF: Unknown
+    pub _unknown_490: [u8; 0x30],
+    /// 0x4C0: Graphics handler 0 pointer (0x19C bytes, vtable 0x66B280)
+    pub gfx_handler_0: Ptr32,
+    /// 0x4C4: Graphics handler 1 pointer (optional)
+    pub gfx_handler_1: Ptr32,
+    /// 0x4C8: Graphics mode flag
+    pub gfx_mode: u32,
+    /// 0x4CC: PCLandscape object pointer
+    pub landscape: Ptr32,
+    /// 0x4D0: Constructor param_2
+    pub _param_4d0: u32,
+    /// 0x4D4: Constructor param_3
+    pub _param_4d4: u32,
+    /// 0x4D8-end: Unknown trailing fields
+    /// Size uncertain — DDGameWrapper total size not yet determined
+    pub _unknown_4d8: [u8; 0x28],
+}
+
+// DDGameWrapper total size is uncertain. This is a minimum based on known fields.
+// Remove or update this assertion when the true size is determined.
+const _: () = assert!(core::mem::size_of::<DDGameWrapper>() == 0x500);

crates/openwa-types/src/dssound.rs

@@ -0,0 +1,44 @@
+use crate::fixed::Fixed;
+use crate::task::Ptr32;
+
+/// DSSound — DirectSound audio subsystem.
+///
+/// Created by DSSound__Constructor (0x573D50).
+/// Vtable: 0x66AF20
+///
+/// Manages sound playback through DirectSound.
+/// Has 500 sound channel slots and a master volume control.
+///
+/// PARTIAL: Only constructor-confirmed fields.
+/// Ghidra uses DWORD-indexed offsets.
+#[repr(C)]
+pub struct DSSound {
+    /// 0x000: Vtable pointer (0x66AF20)
+    pub vtable: Ptr32,
+    /// 0x004: Unknown
+    pub _unknown_004: [u8; 4],
+    /// 0x008: Init field (set to 0)
+    pub _field_008: u32,
+    /// 0x00C: Init field (set to 0)
+    pub _field_00c: u32,
+    /// 0x010: Init field (set to 0)
+    pub _field_010: u32,
+    /// 0x014-0x8A3: Unknown fields
+    pub _unknown_014: [u8; 0x890],
+    /// 0x8A4: Master volume (Fixed, init 0x10000 = 1.0)
+    pub volume: Fixed,
+    /// 0x8A8-0xBB3: Unknown (includes 500-entry channel slot table)
+    pub _unknown_8a8: [u8; 0x30C],
+    /// 0xBB4: Status flag 1 (init 1)
+    pub status_1: u32,
+    /// 0xBB8: Status flag 2 (init 1)
+    pub status_2: u32,
+    /// 0xBBC: Status flag 3 (init 0)
+    pub status_3: u32,
+    /// 0xBC0-end: Unknown trailing fields
+    pub _unknown_bc0: [u8; 0x10],
+}
+
+// Total size uncertain — this is an estimate based on constructor analysis.
+// The 500 dword channel table starts around offset 0xD4+ but exact layout unclear.
+const _: () = assert!(core::mem::size_of::<DSSound>() == 0xBD0);

crates/openwa-types/src/landscape.rs

@@ -0,0 +1,61 @@
+use crate::task::Ptr32;
+
+/// PCLandscape — terrain/landscape subsystem.
+///
+/// Created by PCLandscape__Constructor (0x57ACB0).
+/// Vtable: 0x66B208
+///
+/// Manages terrain data, water effects, and level graphics.
+/// Loads Water.dir and Level.dir from `data\Gfx\`.
+/// Allocates a 384KB (0x60000) terrain buffer.
+///
+/// PARTIAL: Only constructor-confirmed fields are defined.
+/// Ghidra uses DWORD-indexed offsets (param_1[0x240] etc.).
+/// Byte offset = dword_index * 4.
+#[repr(C)]
+pub struct PCLandscape {
+    /// 0x000: Vtable pointer (0x66B208)
+    pub vtable: Ptr32,
+    /// 0x004: Parent DDGame pointer
+    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)
+    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],
+}
+
+const _: () = assert!(core::mem::size_of::<PCLandscape>() == 0xB40);

crates/openwa-types/src/lib.rs

@@ -5,4 +5,9 @@ pub mod sound;
 pub mod sprite;
 pub mod fixed;
 pub mod task;
+pub mod ddgame;
+pub mod ddgame_wrapper;
+pub mod landscape;
+pub mod dssound;
+pub mod opengl;
 pub mod address;

crates/openwa-types/src/opengl.rs

@@ -0,0 +1,33 @@
+use crate::task::Ptr32;
+
+/// OpenGLState — CPU-side OpenGL state object.
+///
+/// Created by OpenGLCPU__Constructor (0x5A0850).
+/// Vtable: 0x6774C0
+///
+/// Small object (0x48 bytes) holding OpenGL rendering state.
+/// The actual OpenGL context (HDC, HGLRC) is stored in DDDisplay
+/// fields during OpenGL__Init (0x59F000).
+#[repr(C)]
+pub struct OpenGLState {
+    /// 0x00: Vtable pointer (0x6774C0)
+    pub vtable: Ptr32,
+    /// 0x04-0x0F: Unknown
+    pub _unknown_04: [u8; 0x0C],
+    /// 0x10: Width
+    pub width: u32,
+    /// 0x14: Unknown (init 0)
+    pub _field_14: u32,
+    /// 0x18-0x23: Unknown (init 0)
+    pub _unknown_18: [u8; 0x0C],
+    /// 0x24: Height
+    pub height: u32,
+    /// 0x28-0x3F: Unknown
+    pub _unknown_28: [u8; 0x18],
+    /// 0x40: Unknown (init 0)
+    pub _field_40: u32,
+    /// 0x44: Unknown (init 0)
+    pub _field_44: u32,
+}
+
+const _: () = assert!(core::mem::size_of::<OpenGLState>() == 0x48);

docs/re-notes/engine-init.md

@@ -0,0 +1,74 @@
+# Engine Initialization Chain
+
+## Overview
+
+WA.exe initializes the engine through a chain of constructor calls that build
+the DDGame monolith and its subsystems. The top-level entry is
+`ConstructDDGameWrapper` which allocates DDGame and wires up all subsystems.
+
+## Call Chain
+
+```
+WinMain / CRT startup (0x5D8B6C)
+  └─ ConstructDDGameWrapper (0x56DEF0)
+       ├─ Allocates DDGameWrapper (vtable 0x66A30C)
+       ├─ DDGame__Constructor (0x56E220)
+       │    ├─ Allocates 0x98B8 bytes for DDGame
+       │    ├─ DDDisplay__Init (0x569D00)
+       │    │    └─ Sets display mode, dimensions, palette, HWND
+       │    ├─ GfxHandler x2 (vtable 0x66B280, 0x19C bytes each)
+       │    ├─ Task state machines x5 (vtable 0x664118)
+       │    └─ Game state pointer at DDGame+0x24
+       ├─ PCLandscape__Constructor (0x57ACB0)
+       │    ├─ vtable 0x66B208, parent = DDGame
+       │    ├─ Allocates terrain buffer (0x60000 bytes) at +0x8E8
+       │    ├─ Creates WaterEffect object (vtable 0x66B268) at +0xC8
+       │    ├─ Creates LandscapeShader (vtable 0x66B1DC) at +0x93C
+       │    └─ Loads Water.dir, Level.dir from data\Gfx\
+       ├─ DSSound__Constructor (0x573D50)
+       │    ├─ vtable 0x66AF20
+       │    ├─ Master volume = Fixed(0x10000) = 1.0 at +0x8A4
+       │    └─ 500 sound channel slots
+       └─ OpenGLCPU__Constructor (0x5A0850) [conditional]
+            ├─ vtable 0x6774C0, 0x48 bytes
+            ├─ Width at +0x10, Height at +0x24
+            └─ OpenGL__Init (0x59F000) stores HDC/HGLRC in DDDisplay
+```
+
+## DDGameWrapper Layout
+
+DDGameWrapper is a thin wrapper (~0x500 bytes) around DDGame:
+
+| Offset | Field              | Notes                              |
+|--------|--------------------|------------------------------------|
+| 0x000  | vtable             | 0x66A30C                           |
+| 0x488  | DDGame ptr         | Allocated 0x98B8-byte object       |
+| 0x48C  | DDGame secondary   | Optional 0x2C-byte struct          |
+| 0x4C0  | GfxHandler 0       | 0x19C bytes, vtable 0x66B280       |
+| 0x4C4  | GfxHandler 1       | Optional                           |
+| 0x4C8  | GfxMode            | Graphics mode flag                 |
+| 0x4CC  | PCLandscape        | Pointer to landscape subsystem     |
+
+## DDGame Key Offsets
+
+DDGame is a ~39KB (0x98B8 bytes) monolithic object. Known landmark fields:
+
+| Offset | Field              | Notes                              |
+|--------|--------------------|------------------------------------|
+| 0x0024 | game_state         | Global game state pointer          |
+| 0x0028 | param              | Constructor parameter              |
+| 0x11B0 | task_ptrs[5]       | 5 task state machine pointers      |
+| 0x3548 | display_mode       | Display mode pointer               |
+| 0x354C | display_width      | Screen width                       |
+| 0x3560 | display_center_x   | Screen center X                    |
+| 0x3564 | display_center_y   | Screen center Y                    |
+| 0x3578 | hwnd               | Window handle                      |
+| 0x358D | palette            | 256-color palette (0x400 bytes)    |
+| 0x3D98 | gfx_objects[4]     | Graphics object pointers           |
+
+## Ghidra Offset Convention
+
+Ghidra's decompiler shows DWORD-indexed offsets for struct access:
+- `param_1[0x122]` → byte offset 0x122 * 4 = **0x488**
+- `param_1[0x133]` → byte offset 0x133 * 4 = **0x4CC**
+- Always multiply DWORD index by 4 to get the true byte offset.

docs/re-notes/memory-map.md

@@ -21,14 +21,48 @@
 
 ## DDGame structure access
 
-The main game state is accessed through the DDGame pointer:
-- DDGame obtained via `ConstructDDGameWrapper` (0x56DEF0) parameter
+The main game state is a 0x98B8-byte (39KB) monolithic object allocated by
+`DDGame__Constructor` (0x56E220). It is wrapped by DDGameWrapper (0x56DEF0).
+
+### DDGameWrapper offsets (from wrapper base)
+- +0x488 → DDGame pointer (the allocated 0x98B8-byte object)
+- +0x4C0 → GfxHandler 0 (vtable 0x66B280)
+- +0x4CC → PCLandscape pointer
+
+### DDGame offsets (from DDGame base)
+- +0x0024 → Game state pointer
+- +0x0028 → Constructor param
+- +0x11B0 → Task state machine pointers (5 entries)
+- +0x3548 → Display mode
+- +0x354C → Display width
+- +0x3560 → Display center X
+- +0x3564 → Display center Y
+- +0x3578 → HWND
+- +0x358D → Palette (0x400 bytes)
+- +0x3D98 → Gfx object pointers (4 entries)
+
+### WormKit-convention offsets (DWORD-indexed)
+These offsets are from the DDGameWrapper base, as used by WormKit mods:
 - DDGame+0x08  → TurnGame object
 - DDGame+0x488 → Game global state
 - DDGame+0x4CC → PC_Landscape
 - DDGame+0x510 → Weapon table
 - DDGame+0x548 → Weapon panel
 
+## Subsystem vtables
+
+| Address    | Object          | Size   | Notes                     |
+|------------|-----------------|--------|---------------------------|
+| 0x66A30C   | DDGameWrapper   | ~0x500 | Top-level wrapper         |
+| 0x66B280   | GfxHandler      | 0x19C  | 2 instances               |
+| 0x664144   | DisplayGfx      | —      |                           |
+| 0x66B208   | PCLandscape     | 0xB40  | Terrain, water, level     |
+| 0x66B1DC   | LandscapeShader | —      | Used by PCLandscape       |
+| 0x66B268   | WaterEffect     | 0xBC   | Created by PCLandscape    |
+| 0x66AF20   | DSSound         | ~0xBD0 | DirectSound, 500 channels |
+| 0x664118   | TaskStateMachine| —      | 5 instances in DDGame     |
+| 0x6774C0   | OpenGLCPU       | 0x48   | Optional, conditional     |
+
 ## Fixed-point convention
 
 All coordinates, velocities, and physics values use 16.16 fixed-point: