feat: convert sound dispatch helpers and fix ActiveSoundEntry fields

Replace 3 sound queue dispatch functions with Rust:
- IsSoundSuppressed (0x5261E0): mute flag + frame counter check
- DispatchGlobalSound (0x526270): suppression + DSSound::play_sound
- PlaySoundPooled_Direct (0x546B50): direct play bypassing queue

Fix ActiveSoundEntry field names based on RecordActiveSound analysis:
- +0x10: channel_index → sequence (running counter/unique ID)
- +0x14: flags → channel_handle (DSSound channel, 0 = free)
- +0x600: count → counter (ring buffer insertion counter)

Add 9 dispatch helper addresses to address.rs and label in Ghidra.
Remove DSSound vtable validation (all 24 slots are Rust pointers).

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

crates/openwa-core/src/address.rs

@@ -388,6 +388,45 @@ pub mod va {
     pub const PLAY_SOUND_LOCAL: u32 = 0x004F_DFE0;
     pub const PLAY_SOUND_GLOBAL: u32 = 0x0054_6E20;
 
+    // --- Sound queue dispatch (bridge: queue → DSSound) ---
+
+    /// IsSoundSuppressed — checks mute flag + frame counter.
+    /// fastcall(ECX=ddgame). Returns 0 if sound OK, 1 if suppressed.
+    pub const IS_SOUND_SUPPRESSED: u32 = 0x0052_61E0;
+
+    /// DispatchGlobalSound — suppression check + DSSound vtable slot 3 (play_sound).
+    /// fastcall(ECX=?, EDX=task_turn_game) + 4 stack params (sound_id, flags, volume, pitch).
+    pub const DISPATCH_GLOBAL_SOUND: u32 = 0x0052_6270;
+
+    /// RecordActiveSound — inserts into 64-entry ring buffer (ActiveSoundTable).
+    /// usercall(EAX=table, ESI=emitter) + 4 stack(pos_x, pos_y, volume, channel_handle).
+    pub const RECORD_ACTIVE_SOUND: u32 = 0x0054_6260;
+
+    /// ComputeDistanceParams — computes volume/pan from world position.
+    /// fastcall(ECX=out_pan, EDX=out_volume) + 3 stack(ddgame_offset, pos_x, pos_y).
+    /// If GameInfo+0xF38C == 0, returns volume=0x10000, pan=0.
+    pub const COMPUTE_DISTANCE_PARAMS: u32 = 0x0054_6300;
+
+    /// DispatchLocalSound — core: distance attenuation + DSSound slot 4 + RecordActiveSound.
+    /// usercall(EAX=base_volume, EDI=ddgame_offset) + 4 stack(sound_id, flags, pos_x, pos_y).
+    pub const DISPATCH_LOCAL_SOUND: u32 = 0x0054_6360;
+
+    /// PlayLocalNoEmitter — thin wrapper → DispatchLocalSound.
+    /// thiscall(ECX=?) + 3 stack(sound_id, flags, pitch).
+    pub const PLAY_LOCAL_NO_EMITTER: u32 = 0x0054_6430;
+
+    /// PlayLocalWithEmitter — gets pos from emitter vtable, then DispatchLocalSound.
+    /// usercall(ESI=emitter) + stack params.
+    pub const PLAY_LOCAL_WITH_EMITTER: u32 = 0x0054_63F0;
+
+    /// PlaySoundPooled_Direct — bypasses queue, same suppression + DSSound slot 4.
+    /// fastcall(ECX=?, EDX=task) + 3 stack params.
+    pub const PLAY_SOUND_POOLED_DIRECT: u32 = 0x0054_6B50;
+
+    /// Distance3D_Attenuation — elliptical distance model for positional audio.
+    /// usercall(EAX=camera_pos_ptr) + 6 stack params. Returns volume + pan via out ptrs.
+    pub const DISTANCE_3D_ATTENUATION: u32 = 0x0054_30F0;
+
     // === Speech / Voice Lines ===
 
     /// Speech line table in .rdata: array of {u32 id, *const u8 name},

crates/openwa-core/src/audio/active_sound.rs

@@ -15,8 +15,8 @@ use crate::fixed::Fixed;
 pub struct ActiveSoundTable {
     /// 0x000-0x5FF: 64 sound entries (entry 0 is unused/reserved).
     pub entries: [ActiveSoundEntry; 64],
-    /// 0x600: Number of active entries (max 64).
-    pub count: u32,
+    /// 0x600: Running counter — incremented on each insert, masked to index (& 0x3F).
+    pub counter: u32,
     /// 0x604: Back-pointer to owning DDGame.
     pub ddgame: *mut DDGame,
 }
@@ -39,10 +39,10 @@ pub struct ActiveSoundEntry {
     pub pos_y: Fixed,
     /// 0x0C: Volume (fixed-point 16.16, 0x10000 = 1.0).
     pub volume: Fixed,
-    /// 0x10: DSSound channel/slot index (1-based).
-    pub channel_index: u32,
-    /// 0x14: Flags (0x40 observed on actively emitting entry).
-    pub flags: u32,
+    /// 0x10: Running counter value at time of insertion (unique ID).
+    pub sequence: u32,
+    /// 0x14: DSSound channel handle (return from play_sound_pooled). 0 = free slot.
+    pub channel_handle: u32,
 }
 
 const _: () = assert!(core::mem::size_of::<ActiveSoundEntry>() == 0x18);

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

@@ -133,6 +133,108 @@ unsafe extern "cdecl" fn play_sound_local_impl(
     1
 }
 
+// ============================================================
+// Sound dispatch helpers (bridge: queue → DSSound)
+// ============================================================
+
+/// 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 {
+        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 {
+        return 1;
+    }
+    0
+}
+
+/// DispatchGlobalSound (0x526270) — fastcall(ECX=unused, EDX=task_turn_game) + 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,
+    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;
+
+    // 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
+    }
+
+    // Get DSSound
+    let dssound = (*ddgame).sound;
+    if dssound.is_null() {
+        return 0;
+    }
+
+    // Call DSSound vtable slot 3: play_sound(sound_id, flags, volume, pitch, 0)
+    let vtable = *(dssound as *const *const u32);
+    let play_fn: unsafe extern "thiscall" fn(*mut u8, u32, u32, u32, u32, u32) -> u32 =
+        core::mem::transmute(*vtable.add(3));
+    play_fn(dssound as *mut u8, sound_id, flags, volume, pitch, 0)
+}
+
+/// PlaySoundPooled_Direct (0x546B50) — fastcall(ECX=unused, EDX=task) + 3 stack, RET 0xC.
+/// 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,
+    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;
+
+    // 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 {
+        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 {
+        return 0xFFFF_FFFF;
+    }
+
+    // Get DSSound
+    let dssound = (*ddgame).sound;
+    if dssound.is_null() {
+        return 0;
+    }
+
+    // Call DSSound vtable slot 4: play_sound_pooled(param1, param2, 0x10000, param3, 0)
+    let vtable = *(dssound as *const *const u32);
+    let play_fn: unsafe extern "thiscall" fn(*mut u8, u32, u32, u32, u32, u32) -> u32 =
+        core::mem::transmute(*vtable.add(4));
+    play_fn(dssound as *mut u8, param1, param2, 0x10000, param3, 0)
+}
+
 // ============================================================
 // Hook installation
 // ============================================================
@@ -156,6 +258,25 @@ pub fn install() -> Result<(), String> {
             trampoline_play_sound_local as *const (),
         )?;
 
+        // Sound dispatch helpers (bridge: queue → DSSound)
+        let _ = hook::install(
+            "IsSoundSuppressed",
+            va::IS_SOUND_SUPPRESSED,
+            hook_is_sound_suppressed as *const (),
+        )?;
+
+        let _ = hook::install(
+            "DispatchGlobalSound",
+            va::DISPATCH_GLOBAL_SOUND,
+            hook_dispatch_global_sound as *const (),
+        )?;
+
+        let _ = hook::install(
+            "PlaySoundPooled_Direct",
+            va::PLAY_SOUND_POOLED_DIRECT,
+            hook_play_sound_pooled_direct as *const (),
+        )?;
+
         // Patch DSSound vtable: replace trivial slots with Rust implementations.
         patch_dssound_vtable()?;
     }

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

@@ -112,7 +112,7 @@ fn validate_addresses(result: &mut ValidationResult) {
         ("DisplayGfx vtable", va::DISPLAY_GFX_VTABLE),
         ("PCLandscape vtable", va::PC_LANDSCAPE_VTABLE),
         ("LandscapeShader vtable", va::LANDSCAPE_SHADER_VTABLE),
-        ("DSSound vtable", va::DS_SOUND_VTABLE),
+        // DSSound vtable excluded: all 24 slots patched to Rust function pointers
         ("TaskStateMachine vtable", va::TASK_STATE_MACHINE_VTABLE),
         ("OpenGLCPU vtable", va::OPENGL_CPU_VTABLE),
         ("WaterEffect vtable", va::WATER_EFFECT_VTABLE),