feat: add GameSession struct and DDGameWrapper__Constructor passthrough hook

Renames DDInput__Constructor_Maybe → GameEngine__InitHardware (the function
initializes all hardware subsystems; the DDInput vtable only appears in the
headless/stats-server else-branch that gave it its wrong name).

Adds:
- GameSession struct (0x120 bytes) in openwa-core with all known field offsets
mapped from decompilation of FUN_00572F50 / GameEngine__InitHardware
- G_GAME_SESSION (0x7A0884) and four new address constants
- Passthrough hook on DDGameWrapper__Constructor (0x56DEF0) that logs
wrapper and DDGame pointers once per game session start

The hook uses a naked AT&T asm trampoline to preserve EDI, which
DDGameWrapper__Constructor passes implicitly as the 9th argument to
DDGame__Constructor. A plain extern "stdcall" hook clobbered EDI via
Rust's register allocator, causing a null-pointer crash in
PCLandscape__Constructor. The trampoline tail-calls the original via
jmp (not call), leaving EDI completely untouched.

Validated: 135 PASS, 0 FAIL. OpenWA.log shows:
[GameSession] DDGameWrapper ctor: wrapper=0x03CD0C00 ddgame=0x07A669E0

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

crates/openwa-core/src/address.rs

@@ -223,6 +223,32 @@ pub mod va {
     /// usercall(EAX=base, EDX=team_idx, ESI=worm_index) → void, plain RET. 3 xrefs.
     pub const SET_ACTIVE_WORM_MAYBE: u32 = 0x0052_2500;
 
+    // === Game session ===
+
+    /// `GameEngine__InitHardware` — initializes all hardware subsystems: display,
+    /// sound, keyboard, palette, DDGameWrapper, DDNetGameWrapper, and stores
+    /// the resulting pointers into `G_GAME_SESSION`.
+    ///
+    /// `__thiscall(this=GameInfo, hwnd, param3, param4)` → 1=ok 0=fail, `RET 0xC`.
+    ///
+    /// In headless/stats mode (`GameInfo+0xF914 != 0`) creates a `GameStats` object
+    /// with the DDInput vtable instead of a real display+audio stack.
+    pub const GAME_ENGINE_INIT_HARDWARE: u32 = 0x0056_D350;
+
+    /// `GameSession__Run` — allocates the `GameSession` struct (0x120 bytes),
+    /// calls `GameEngine__InitHardware`, runs the game main loop, then calls
+    /// `GameEngine__Shutdown`. Uses ESI implicitly for the `GameInfo` config.
+    pub const GAME_SESSION_RUN: u32 = 0x0057_2F50;
+
+    /// `GameSession__Constructor` — usercall(`EAX=this`), sets vtable and
+    /// zero-inits all fields. Called with a freshly `malloc`'d 0x120-byte buffer.
+    pub const GAME_SESSION_CONSTRUCTOR: u32 = 0x0058_BFA0;
+
+    /// `GameEngine__Shutdown` — destroys all subsystems in reverse creation order
+    /// (streaming audio, DDGameWrapper, DisplayGfx, DDKeyboard, Palette).
+    /// `stdcall(param_1)` → void.
+    pub const GAME_ENGINE_SHUTDOWN: u32 = 0x0056_DCD0;
+
     // === Graphics / rendering ===
 
     pub const CONSTRUCT_DD_GAME: u32 = 0x0056_E220;

crates/openwa-core/src/game_session.rs

@@ -0,0 +1,83 @@
+/// Top-level game session context, allocated once per game run.
+///
+/// `G_GAME_SESSION` (0x7A0884) stores a pointer to this struct. Created by
+/// `GameSession__Constructor` (0x58BFA0, usercall EAX=this), populated by
+/// `GameEngine__InitHardware` (0x56D350), and destroyed by
+/// `GameEngine__Shutdown` (0x56DCD0).
+///
+/// Lifecycle:
+/// ```text
+/// GameSession__Run (0x572F50, ESI=GameInfo)
+///   ├─ alloc 0x120 bytes → GameSession__Constructor (0x58BFA0)
+///   ├─ G_GAME_SESSION ← &this
+///   ├─ GameEngine__InitHardware → fills subsystem pointers (0xA0–0xC0)
+///   ├─ game main loop (exit when exit_flag != 0)
+///   └─ GameEngine__Shutdown → destroys all subsystems
+/// ```
+///
+/// In headless/stats mode (`GameInfo+0xF914 != 0`), `display_gfx` holds a
+/// `GameStats` object with a DDInput vtable instead of a real `DisplayGfx`.
+#[repr(C)]
+pub struct GameSession {
+    /// 0x000: vtable pointer (class `GameSession`, `PTR_FUN_0066b3f8`)
+    pub vtable: *mut u8,
+    pub _unknown_004: [u8; 4],
+    /// 0x008: main window HWND, stored from `hWnd` in `GameSession__Run`
+    pub hwnd: u32,
+    pub _unknown_00c: [u8; 0x20],
+    /// 0x02C: set to 1 on init (role TBD)
+    pub flag_2c: u32,
+    pub _unknown_030: [u8; 8],
+    /// 0x038: back-pointer to the `GameInfo` config struct (ESI from `GameSession__Run`)
+    pub config_ptr: *mut u8,
+    /// 0x03C: nonzero = exit the game main loop (checked each frame in `GameSession__Run`)
+    pub exit_flag: u32,
+    /// 0x040: game-end status/result code
+    pub flag_40: u32,
+    pub _unknown_044: [u8; 0x10],
+    /// 0x054: display center X = `display_width / 2`.
+    /// Initialized to `0x80000000` by `GameSession__Constructor`, then overwritten.
+    pub screen_center_x: i32,
+    /// 0x058: display center Y = `display_height / 2`
+    pub screen_center_y: i32,
+    pub _unknown_05c: [u8; 0x14],
+    /// 0x070: cursor X at session start (from `GetCursorPos`)
+    pub cursor_initial_x: i32,
+    /// 0x074: cursor Y at session start
+    pub cursor_initial_y: i32,
+    pub _unknown_078: [u8; 8],
+    /// 0x080: cursor center X — set to `screen_center_x`, used for `SetCursorPos`
+    pub cursor_x: i32,
+    /// 0x084: cursor center Y
+    pub cursor_y: i32,
+    pub _unknown_088: [u8; 8],
+    /// 0x090: `QueryPerformanceFrequency` result low DWORD (0 if QPC unavailable)
+    pub timer_freq_lo: u32,
+    /// 0x094: high DWORD
+    pub timer_freq_hi: u32,
+    /// 0x098: QPC counter accumulator low DWORD
+    pub timer_counter_lo: u32,
+    /// 0x09C: high DWORD
+    pub timer_counter_hi: u32,
+    /// 0x0A0: `DDGameWrapper*` — the main game object wrapper (→ `DDGame` at `+0x488`)
+    pub ddgame_wrapper: *mut u8,
+    /// 0x0A4: `DDKeyboard*` — 0x33C bytes, vtable `DDKeyboard_vtable` (0x66AEC8)
+    pub keyboard: *mut u8,
+    /// 0x0A8: `DSSound*` — 0xBE0 bytes, vtable `DSSound_vtable` (0x66AF20)
+    pub sound: *mut u8,
+    /// 0x0AC: `DisplayGfx*` — 0x24E28 bytes (normal), or `GameStats*` in headless mode
+    pub display_gfx: *mut u8,
+    /// 0x0B0: `Palette*` — 0x28 bytes, vtable `Palette_vtable_Maybe`
+    pub palette: *mut u8,
+    /// 0x0B4: streaming audio object — 0x354 bytes (`FUN_0058bc10`)
+    pub streaming_audio: *mut u8,
+    /// 0x0B8: input controller — 0x1800 bytes; null if `param_4 == 0` at init
+    pub input_ctrl: *mut u8,
+    /// 0x0BC: timing object — 0x30 bytes (`FUN_0053e950`)
+    pub timer_obj: *mut u8,
+    /// 0x0C0: `DDNetGameWrapper*` — 0x2C bytes
+    pub net_game: *mut u8,
+    pub _unknown_0c4: [u8; 0x5C],
+}
+
+const _: () = assert!(core::mem::size_of::<GameSession>() == 0x120);

crates/openwa-core/src/lib.rs

@@ -23,6 +23,7 @@ pub mod game_info;
 pub mod scheme;
 pub mod speech;
 pub mod turn_order;
+pub mod game_session;
 pub mod address;
 pub mod rebase;
 pub mod wa;

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

@@ -0,0 +1,105 @@
+//! Game session lifecycle hook.
+//!
+//! Passthrough hook on `DDGameWrapper__Constructor` (0x56DEF0) that fires once
+//! per game session start, logging the `DDGameWrapper` and `DDGame` addresses.
+//!
+//! ## Calling convention notes
+//!
+//! `DDGameWrapper__Constructor` is `__stdcall` with 7 stack params, BUT it also
+//! uses `EDI` as an **implicit register param** (Ghidra: `unaff_EDI`), which it
+//! passes as the 9th argument to `DDGame__Constructor`. A regular `extern "stdcall"`
+//! hook function would clobber EDI before calling the original (the Rust compiler
+//! uses it as a scratch register), causing a null-pointer crash deep in DDGame init.
+//!
+//! The naked trampoline below avoids touching EDI entirely:
+//! 1. Swaps the caller's return address with our continuation label.
+//! 2. Tail-calls the original via `jmp` (not `call`) — EDI is unchanged.
+//! 3. After the original returns (via our continuation), calls a cdecl logger.
+//! 4. Jumps back to the real caller.
+
+use openwa_core::address::va;
+use crate::hook;
+use crate::log_line;
+
+/// Trampoline address of the original DDGameWrapper__Constructor.
+/// Set by `install()` via MinHook, read by the naked trampoline.
+static mut ORIG_VAL: u32 = 0;
+
+/// Caller's return address, saved by the naked trampoline before the tail-call
+/// to orig so we can return there after the logger runs.
+/// Non-reentrant (single-threaded game init; DDGameWrapper::Constructor is
+/// called at most once per game session).
+static mut SAVED_RET: u32 = 0;
+
+/// Called from the naked trampoline after the original constructor returns.
+/// `wrapper` = the DDGameWrapper pointer (orig's return value = `this`).
+unsafe extern "cdecl" fn on_ddgame_wrapper_created(wrapper: u32) {
+    // DDGame* lives at DDGameWrapper+0x488
+    let ddgame = *(wrapper as *const u32).add(0x488 / 4);
+    let _ = log_line(&format!(
+        "[GameSession] DDGameWrapper ctor: wrapper=0x{wrapper:08X}  ddgame=0x{ddgame:08X}"
+    ));
+}
+
+/// Naked trampoline for `DDGameWrapper__Constructor`.
+///
+/// Stack layout on entry (stdcall 7 params):
+/// ```text
+/// [esp+00] = caller_ret
+/// [esp+04] = this  (*mut DDGameWrapper)
+/// [esp+08] = display
+/// [esp+0C] = sound
+/// [esp+10] = gfx
+/// [esp+14] = palette
+/// [esp+18] = music
+/// [esp+1C] = network
+/// EDI      = implicit param (passed down to DDGame__Constructor as 9th arg)
+/// ```
+#[unsafe(naked)]
+unsafe extern "C" fn hook_ddgame_wrapper_ctor() {
+    core::arch::naked_asm!(
+        // --- Save EAX and swap return address ---
+        "pushl %eax",
+        // Stack: [esp+0]=old_eax, [esp+4]=caller_ret, [esp+8]=this, ..., [esp+20]=network
+        "movl 4(%esp), %eax",          // eax = caller_ret
+        "movl %eax, {ret}",            // save caller_ret → SAVED_RET
+        "movl $1f, %eax",              // eax = address of our continuation (AT&T: $ = immediate)
+        "movl %eax, 4(%esp)",          // replace caller_ret with continuation address
+        "popl %eax",                   // restore eax; stack: [cont, this, ..., network]
+        // Stack is now exactly: [esp+0]=continuation, [esp+4]=this, ..., [esp+1C]=network
+        // EDI is unchanged — the original function will read it directly.
+
+        // --- Tail-call to original (jmp, not call, to avoid pushing a return address) ---
+        "movl {orig}, %eax",           // eax = trampoline address (value at ORIG_VAL)
+        "jmpl *%eax",
+
+        // --- Continuation: entered when orig does its `ret 0x1C` ---
+        // At this point:
+        //   EAX = wrapper pointer (orig's return value)
+        //   ESP = caller's stack (orig's ret 0x1C popped 7 params + return addr)
+        "1:",
+        "pushl %eax",                  // save wrapper (return value)
+        "pushl %eax",                  // arg: wrapper ptr → on_ddgame_wrapper_created
+        "calll {log_fn}",
+        "addl $4, %esp",               // clean cdecl arg
+        "popl %eax",                   // restore wrapper → EAX (caller's expected return value)
+        "jmpl *{ret}",                 // jump to saved caller_ret
+
+        orig = sym ORIG_VAL,
+        ret = sym SAVED_RET,
+        log_fn = sym on_ddgame_wrapper_created,
+        options(att_syntax),
+    );
+}
+
+pub fn install() -> Result<(), String> {
+    unsafe {
+        let trampoline = hook::install(
+            "DDGameWrapper__Constructor",
+            va::CONSTRUCT_DD_GAME_WRAPPER,
+            hook_ddgame_wrapper_ctor as *const (),
+        )?;
+        ORIG_VAL = trampoline as u32;
+    }
+    Ok(())
+}

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

@@ -1,5 +1,6 @@
 mod config;
 mod frontend;
+mod game_session;
 pub(crate) mod input;
 mod scheme;
 mod render;
@@ -9,6 +10,7 @@ mod team;
 mod weapon;
 
 pub fn install_all() -> Result<(), String> {
+    game_session::install()?;
     frontend::install()?;
     scheme::install()?;
     config::install()?;