refactor: add typed fields for sound dispatch, remove pointer arithmetic

Add DDGame.frame_counter (0x5CC) and GameInfo sound_start_frame
(0xF344) / sound_mute (0xF348) as proper struct fields. Use typed
pointers in all hook signatures instead of u32 casts — 32-bit target
means pointers and u32 are interchangeable in ABI.

Also remove DSSound vtable from validation (all 24 slots are Rust).

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

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

@@ -120,13 +120,25 @@ pub struct DDGame {
     /// 0x54C: CTaskLand pointer (set by CTaskLand__InitLandscape at 0x5056F0).
     /// The landscape/terrain task. Vtable at 0x664388.
     pub task_land: *mut u8,
-    /// 0x550-0x25FF: Large unverified region.
+    /// 0x550-0x5CB: Unknown.
     ///
     /// Runtime observations (not yet linked to code):
     /// - 0x5C4: value matches code address 0x5755D0 (fixed-point normalize fn)
-    /// - 0x5C8-0x5FF: small config-like values (2048, 150, 3000, 696, 896, 100, 300)
+    /// - 0x5C8-0x5CB: config-like values
+    pub _unknown_550: [u8; 0x5CC - 0x550],
+
+    /// 0x5CC: Game frame counter. Incremented at end of each frame in
+    /// GameFrameDispatcher. Compared against GameInfo+0xF344 (sound start
+    /// threshold) by IsSoundSuppressed and DispatchGlobalSound.
+    pub frame_counter: i32,
+
+    /// 0x5D0-0x25FF: Large unverified region.
+    ///
+    /// Runtime observations:
+    /// - 0x5D0: frame processing flag (set 0/1 by GameFrameEndProcessor)
+    /// - 0x5D8-0x5FF: small config-like values (2048, 150, 3000, 696, 896, 100, 300)
     /// - 0x600-0x25FF: identity permutation [0,1,2,...,~2048] — purpose unknown
-    pub _unknown_550: [u8; 0x2600 - 0x550],
+    pub _unknown_5d0: [u8; 0x2600 - 0x5D0],
 
     /// 0x2600-0x2DFF: Block of 0xFFFFFFFF values at runtime (512 i32 entries).
     /// May be unused slots in a parallel table to the 0x600 permutation.

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

@@ -46,8 +46,20 @@ pub struct GameInfo {
     /// 0xDAEC: Land data path ("data\land.dat", 14 bytes incl. null)
     pub land_dat_path: [u8; 14],
 
-    /// 0xDAFA-0xF373: Unknown
-    pub _unknown_dafa: [u8; 0xF374 - 0xDAFA],
+    /// 0xDAFA-0xF343: Unknown
+    pub _unknown_dafa: [u8; 0xF344 - 0xDAFA],
+
+    /// 0xF344: Sound start frame threshold (i32). Sound is suppressed when
+    /// DDGame.frame_counter < this value. Checked by IsSoundSuppressed and
+    /// DispatchGlobalSound.
+    pub sound_start_frame: i32,
+
+    /// 0xF348: Sound mute flag (byte). Nonzero = all sound suppressed.
+    /// Checked by IsSoundSuppressed, DispatchGlobalSound, PlaySoundPooled_Direct.
+    pub sound_mute: u8,
+
+    /// 0xF349-0xF373: Unknown
+    pub _unknown_f349: [u8; 0xF374 - 0xF349],
 
     /// 0xF374: Display flags passed to DDDisplay::Init.
     pub display_flags: u32,

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

@@ -10,9 +10,9 @@
 use std::sync::atomic::Ordering;
 
 use openwa_core::address::va;
-use openwa_core::engine::{DDGame, SoundQueueEntry};
+use openwa_core::engine::{DDGame, DDGameWrapper, SoundQueueEntry};
 use openwa_core::audio::SoundId;
-use openwa_core::task::CGameTask;
+use openwa_core::task::{CGameTask, CTask};
 
 use crate::hook;
 use crate::log_line;
@@ -63,7 +63,7 @@ unsafe fn queue_sound(
 // __thiscall: ECX = CTask* this, 4 stack params, RET 0x10
 
 unsafe extern "thiscall" fn hook_play_sound_global(
-    this: u32,
+    this: *const CGameTask,
     sound_id: u32,
     flags: u32,
     volume: u32,
@@ -74,13 +74,12 @@ unsafe extern "thiscall" fn hook_play_sound_global(
             .map(|s| format!("{s:?}"))
             .unwrap_or_else(|v| format!("#{v}"));
         let _ = log_line(&format!(
-            "[Sound] Global: task=0x{this:08X} id={sound_id}({sound_name}) \
+            "[Sound] Global: task=0x{this:08X?} id={sound_id}({sound_name}) \
              p3={flags} p4={volume} p5={pitch}"
         ));
     }
 
-    let task = &*(this as *const CGameTask);
-    queue_sound(task.base.ddgame, sound_id, flags, volume, pitch).is_some() as u32
+    queue_sound((*this).base.ddgame, sound_id, flags, volume, pitch).is_some() as u32
 }
 
 // ============================================================
@@ -95,7 +94,7 @@ hook::usercall_trampoline!(fn trampoline_play_sound_local; impl_fn = play_sound_
 unsafe extern "cdecl" fn play_sound_local_impl(
     pitch: u32,
     volume: u32,
-    task: u32,
+    task: *mut CGameTask,
     sound_id: u32,
     flags: u32,
 ) -> u32 {
@@ -104,12 +103,12 @@ unsafe extern "cdecl" fn play_sound_local_impl(
             .map(|s| format!("{s:?}"))
             .unwrap_or_else(|v| format!("#{v}"));
         let _ = log_line(&format!(
-            "[Sound] Local: eax={pitch} ecx=0x{volume:08X} task=0x{task:08X} \
+            "[Sound] Local: eax={pitch} ecx=0x{volume:08X} task=0x{task:08X?} \
              id={sound_id}({sound_name}) flags={flags}"
         ));
     }
 
-    let gt = &*(task as *const CGameTask);
+    let gt = &*task;
     let ddgame = gt.base.ddgame;
     let entry = match queue_sound(ddgame, sound_id, flags, volume, pitch) {
         Some(e) => e,
@@ -127,8 +126,7 @@ unsafe extern "cdecl" fn play_sound_local_impl(
     ((*emitter.vtable).get_position)(emitter, &mut (*entry).pos_x, &mut (*entry).pos_y);
 
     // Increment local sound count
-    let gt_mut = &mut *(task as *mut CGameTask);
-    gt_mut.sound_emitter.local_sound_count += 1;
+    (*task).sound_emitter.local_sound_count += 1;
 
     1
 }
@@ -139,50 +137,37 @@ unsafe extern "cdecl" fn play_sound_local_impl(
 
 /// IsSoundSuppressed (0x5261E0) — thiscall(ECX=DDGame*), plain RET.
 /// Returns 0 if sound playback is allowed, 1 if suppressed.
-///
-/// Checks:
-/// - GameInfo+0xF348 (byte): sound mute flag
-/// - DDGame+0x5CC (i32) vs GameInfo+0xF344 (i32): frame counter ≥ threshold
 unsafe extern "thiscall" fn hook_is_sound_suppressed(ddgame: *mut DDGame) -> u32 {
-    let gi = (*ddgame).game_info as *const u8;
-    // Mute flag
-    if *gi.add(0xF348) != 0 {
+    let g = &*ddgame;
+    let gi = &*g.game_info;
+    if gi.sound_mute != 0 {
         return 1;
     }
-    // Frame counter must be ≥ sound start threshold
-    let frame_counter = *(ddgame as *const u8).add(0x5CC).cast::<i32>();
-    let threshold = *gi.add(0xF344).cast::<i32>();
-    if frame_counter < threshold {
+    if g.frame_counter < gi.sound_start_frame {
         return 1;
     }
     0
 }
 
-/// DispatchGlobalSound (0x526270) — fastcall(ECX=unused, EDX=task_turn_game) + 4 stack, RET 0x10.
+/// DispatchGlobalSound (0x526270) — fastcall(ECX=unused, EDX=ddgame_wrapper) + 4 stack, RET 0x10.
 /// Checks sound suppression, then calls DSSound vtable slot 3 (play_sound).
 unsafe extern "fastcall" fn hook_dispatch_global_sound(
     _ecx: u32,
-    task_turn_game: u32,
+    ddgame_wrapper: *const DDGameWrapper,
     sound_id: u32,
     flags: u32,
     volume: u32,
     pitch: u32,
 ) -> u32 {
-    let ddgame = *((task_turn_game as *const u8).add(0x488) as *const *mut DDGame);
-    let gi = (*ddgame).game_info as *const u8;
+    let g = &*(*ddgame_wrapper).ddgame;
+    let gi = &*g.game_info;
 
-    // Suppression check (same logic as IsSoundSuppressed but also different return for suppressed)
-    if *gi.add(0xF348) != 0 {
-        return 0xFFFF_FFFF; // -1
-    }
-    let frame_counter = *(ddgame as *const u8).add(0x5CC).cast::<i32>();
-    let threshold = *gi.add(0xF344).cast::<i32>();
-    if frame_counter < threshold {
-        return 0xFFFF_FFFF; // -1
+    // Suppression check — returns -1 if muted or before sound start frame
+    if gi.sound_mute != 0 || g.frame_counter < gi.sound_start_frame {
+        return 0xFFFF_FFFF;
     }
 
-    // Get DSSound
-    let dssound = (*ddgame).sound;
+    let dssound = g.sound;
     if dssound.is_null() {
         return 0;
     }
@@ -198,32 +183,25 @@ unsafe extern "fastcall" fn hook_dispatch_global_sound(
 /// Bypasses queue, checks suppression + fast-forward, calls DSSound vtable slot 4 directly.
 unsafe extern "fastcall" fn hook_play_sound_pooled_direct(
     _ecx: u32,
-    task: u32,
+    task: *const CTask,
     param1: u32,
     param2: u32,
     param3: u32,
 ) -> u32 {
-    let ddgame = *((task as *const u8).add(0x2C) as *const *mut DDGame);
-    let gi = (*ddgame).game_info as *const u8;
+    let g = &*(*task).ddgame;
+    let gi = &*g.game_info;
 
     // Suppression check
-    if *gi.add(0xF348) != 0 {
-        return 0xFFFF_FFFF;
-    }
-    let frame_counter = *(ddgame as *const u8).add(0x5CC).cast::<i32>();
-    let threshold = *gi.add(0xF344).cast::<i32>();
-    if frame_counter < threshold {
+    if gi.sound_mute != 0 || g.frame_counter < gi.sound_start_frame {
         return 0xFFFF_FFFF;
     }
 
     // Fast-forward check (unique to this function)
-    let ff_active = *(ddgame as *const u8).add(0x98B0).cast::<i32>();
-    if ff_active != 0 {
+    if g.fast_forward_active != 0 {
         return 0xFFFF_FFFF;
     }
 
-    // Get DSSound
-    let dssound = (*ddgame).sound;
+    let dssound = g.sound;
     if dssound.is_null() {
         return 0;
     }