refactor: typed vtables, port PaletteContext__Init and GameStateStream__Init

Replace raw vtable dispatch with typed vtable calls in game_state_init:
- Add bind_DSSoundVtable! macro, enabling _raw method wrappers
- Create PCLandscapeVtable (slots 0,1,2,6,8,18) with bind macro
- Replace 7 manual vtable dispatches (DisplayGfx, DSSound, PCLandscape)

Port two WA functions to Rust:
- PaletteContext__Init (0x5411A0): free stack initializer
- GameStateStream__Init (0x4FB490): sub-buffer array constructor
- Remove call_usercall_eax naked asm bridge (no longer needed)

Rename DSSound::set_volume_params → set_frequency_scale (it adjusts
pitch, not volume). Rename status_1/status_2 → freq_scale_divisor/
freq_scale_multiplier. Update Ghidra accordingly.

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

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

@@ -89,8 +89,8 @@ pub struct DSSoundVtable {
     pub destructor: fn(this: *mut DSSound, flags: u8) -> *mut DSSound,
     /// update_channels — iterates 8 descs, releases finished buffers
     pub update_channels: fn(this: *mut DSSound),
-    /// set_volume_params — sets status_1/2, adjusts channel volumes
-    pub set_volume_params: fn(this: *mut DSSound, status: u32, value: i32),
+    /// set_frequency_scale — sets pitch scaling factors, adjusts active channel frequencies
+    pub set_frequency_scale: fn(this: *mut DSSound, divisor: u32, multiplier: i32),
     /// play_sound — wrapper around core play. RET 0x14 = 5 stack params.
     pub play_sound: fn(
         this: *mut DSSound,
@@ -184,10 +184,10 @@ pub struct DSSound {
     pub buffer_pool_used_count: u32,
     /// 0xBB0: Total bytes loaded (incremented by load_wav)
     pub total_bytes_loaded: u32,
-    /// 0xBB4: Status flag 1 (init 1, used by set_volume_params)
-    pub status_1: u32,
-    /// 0xBB8: Status flag 2 (init 1, used by set_volume_params)
-    pub status_2: u32,
+    /// 0xBB4: Frequency scale divisor (init 1, used by set_frequency_scale)
+    pub freq_scale_divisor: u32,
+    /// 0xBB8: Frequency scale multiplier (init 1, used by set_frequency_scale)
+    pub freq_scale_multiplier: u32,
     /// 0xBBC: Init success flag — set to 1 when DirectSoundCreate +
     /// init_buffers + IDirectSoundBuffer::Play all succeed.
     pub init_success: u32,
@@ -197,6 +197,8 @@ pub struct DSSound {
 
 const _: () = assert!(core::mem::size_of::<DSSound>() == 0xBE0);
 
+bind_DSSoundVtable!(DSSound, vtable);
+
 // ── Trivial vtable method implementations ─────────────────────────────────
 
 // ── Rust vtable method implementations ────────────────────────────────────
@@ -310,18 +312,22 @@ pub unsafe extern "thiscall" fn set_master_volume(this: *mut DSSound, new_volume
     1
 }
 
-/// Slot 2: set_volume_params — sets frequency scaling params and adjusts active channels.
-/// `param1` is the divisor (status_1), `param2` is the multiplier (status_2).
-/// For each playing channel: new_freq = channel_freq * param2 / param1, clamped to 200000.
-pub unsafe extern "thiscall" fn set_volume_params(this: *mut DSSound, param1: u32, param2: i32) {
+/// Slot 2: set_frequency_scale — sets pitch scaling factors and adjusts active channel frequencies.
+/// `divisor` is the frequency divisor, `multiplier` is the frequency multiplier.
+/// For each playing channel: new_freq = channel_freq * multiplier / divisor, clamped to 200000.
+pub unsafe extern "thiscall" fn set_frequency_scale(
+    this: *mut DSSound,
+    divisor: u32,
+    multiplier: i32,
+) {
     let snd = &mut *this;
 
     // No change → early return.
-    if snd.status_1 == param1 && snd.status_2 == param2 as u32 {
+    if snd.freq_scale_divisor == divisor && snd.freq_scale_multiplier == multiplier as u32 {
         return;
     }
-    snd.status_1 = param1;
-    snd.status_2 = param2 as u32;
+    snd.freq_scale_divisor = divisor;
+    snd.freq_scale_multiplier = multiplier as u32;
 
     for desc in &snd.channel_descs {
         let Some(buf) = desc.buffer() else { continue };
@@ -334,11 +340,11 @@ pub unsafe extern "thiscall" fn set_volume_params(this: *mut DSSound, param1: u3
             continue;
         }
 
-        // Compute adjusted frequency: channel_freq * param2 / param1.
-        if param1 == 0 {
+        // Compute adjusted frequency: channel_freq * multiplier / divisor.
+        if divisor == 0 {
             continue;
         }
-        let freq = (desc.channel_freq.0 as i64 * param2 as i64 / param1 as i64) as i32;
+        let freq = (desc.channel_freq.0 as i64 * multiplier as i64 / divisor as i64) as i32;
         let freq = freq.min(200_000);
 
         let _ = buf.SetFrequency(freq as u32);
@@ -542,9 +548,10 @@ unsafe fn core_play_sound(
     desc.ds_buffer = core::mem::transmute_copy(&new_buf);
     core::mem::forget(new_buf);
 
-    // Compute actual playback frequency: channel_freq * status_2 / status_1.
-    let freq = if snd.status_1 != 0 {
-        let f = (channel_freq as i64 * snd.status_2 as i64 / snd.status_1 as i64) as i32;
+    // Compute actual playback frequency: channel_freq * multiplier / divisor.
+    let freq = if snd.freq_scale_divisor != 0 {
+        let f = (channel_freq as i64 * snd.freq_scale_multiplier as i64
+            / snd.freq_scale_divisor as i64) as i32;
         f.min(200_000)
     } else {
         channel_freq
@@ -965,9 +972,9 @@ impl DSSound {
         }
         snd.buffer_pool_free_count = 64;
 
-        // Status flags
-        snd.status_1 = 1;
-        snd.status_2 = 1;
+        // Frequency scaling (1:1 = no scaling)
+        snd.freq_scale_divisor = 1;
+        snd.freq_scale_multiplier = 1;
         // init_success stays 0 until COM init succeeds
 
         snd

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

@@ -14,7 +14,7 @@ pub use dssound::{
     destructor as dssound_destructor, is_channel_finished, is_slot_loaded, load_wav,
     noop as dssound_noop, play_sound, play_sound_pooled, release_finished,
     returns_0 as dssound_returns_0, returns_1 as dssound_returns_1, set_channel_volume,
-    set_master_volume, set_pan, set_volume_params, stop_channel,
+    set_frequency_scale, set_master_volume, set_pan, stop_channel,
     sub_destructor as dssound_sub_destructor, update_channels,
 };
 pub use dssound::{ChannelDescriptor, DSSound, DSSoundVtable};

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

@@ -11,6 +11,7 @@ use crate::engine::game_info::GameInfo;
 use crate::fixed::Fixed;
 use crate::render::display::gfx::DisplayGfx;
 use crate::render::landscape::PCLandscape;
+use crate::wa_alloc::{wa_malloc_struct_zeroed, wa_malloc_zeroed};
 
 /// Pure Rust implementation of SpriteGfxTable__Init (0x541620).
 ///
@@ -492,15 +493,12 @@ pub unsafe fn init_turn_state(wrapper: *mut DDGameWrapper) {
     (*ddgame3)._field_8160 = 0;
     (*ddgame3)._field_8164 = 0;
 
-    // Vtable dispatch: DDGame.landscape → vtable slot 1,
-    // param = game_info.donkey_disabled (byte at +0xD94C)
+    // Landscape vtable slot 1: set control flag (donkey_disabled)
     let ddgame4 = ddgame_from_wrapper(wrapper);
-    let landscape = (*ddgame4).landscape as *mut u8;
+    let landscape = (*ddgame4).landscape;
     if !landscape.is_null() {
-        let vtable = *(landscape as *const *const usize);
-        let slot1: unsafe extern "thiscall" fn(*mut u8, u32) = core::mem::transmute(*vtable.add(1));
         let param = (*(*ddgame4).game_info).donkey_disabled as u32;
-        slot1(landscape, param);
+        PCLandscape::set_control_flag_raw(landscape, param);
     }
 }
 
@@ -522,22 +520,15 @@ pub unsafe fn init_landscape_flags(wrapper: *mut DDGameWrapper) {
     let field_734c = (*ddgame)._field_734c;
     let field_7340 = (*ddgame)._field_7340;
 
-    // DDGame.landscape object
-    let landscape = (*ddgame).landscape as *mut u8;
-    let vtable = *(landscape as *const *const usize);
-    // Vtable slot 6 = offset +0x18
-    let slot6: unsafe extern "thiscall" fn(*mut u8, u32, u32, u32, u32, u32, u32, u32, u32) =
-        core::mem::transmute(*vtable.add(6));
+    let landscape = (*ddgame).landscape;
 
     if scheme_flag != 0 {
-        // Call with (1, 1, 1, 1, field_7318, field_730c, field_734c, field_7340)
-        slot6(
+        PCLandscape::init_borders_raw(
             landscape, 1, 1, 1, 1, field_7318, field_730c, field_734c, field_7340,
         );
         (*ddgame).level_width_raw = 1;
     } else if (*ddgame).level_width_raw != 0 {
-        // Call with (0, 0, 1, 0, field_7318, field_730c, field_734c, field_7340)
-        slot6(
+        PCLandscape::init_borders_raw(
             landscape, 0, 0, 1, 0, field_7318, field_730c, field_734c, field_7340,
         );
     }
@@ -622,9 +613,7 @@ pub unsafe fn init_game_state(wrapper: *mut DDGameWrapper) {
         let mem = wa_malloc_zeroed(0x264) as *mut u32;
         if !mem.is_null() {
             *mem = rb(0x664194); // GameStateStream vtable
-            let init: unsafe extern "stdcall" fn(*mut u32) =
-                core::mem::transmute(rb(va::GAME_STATE_STREAM_INIT) as usize);
-            init(mem.add(1)); // Init sub-object at offset +4
+            game_state_stream_init(mem.add(1));
             *mem.add(1) = 0;
             *mem.add(0x90) = ddgame as u32; // DDGame ptr backref
             *mem.add(0x8B) = 0;
@@ -642,18 +631,12 @@ pub unsafe fn init_game_state(wrapper: *mut DDGameWrapper) {
         (*ddgame)._unknown_52c = mem;
     }
 
-    // ===== Virtual call: display->vtable[1](&level_width_sound, &screen_height_pixels) =====
-    {
-        let display = (*ddgame).display;
-        let vtable = *(display as *const *const u32);
-        let vmethod: unsafe extern "thiscall" fn(*mut DisplayGfx, *mut i32, *mut i32) =
-            core::mem::transmute(*vtable.add(1));
-        vmethod(
-            display,
-            core::ptr::addr_of_mut!((*ddgame).level_width_sound),
-            core::ptr::addr_of_mut!((*ddgame).screen_height_pixels),
-        );
-    }
+    // Get display dimensions
+    DisplayGfx::get_dimensions_raw(
+        (*ddgame).display,
+        core::ptr::addr_of_mut!((*ddgame).level_width_sound) as *mut u32,
+        core::ptr::addr_of_mut!((*ddgame).screen_height_pixels) as *mut u32,
+    );
     (*ddgame)._field_77b0 = 0;
 
     // ===== Allocate BufferObject (main_buffer at wrapper+0x0C) =====
@@ -936,10 +919,7 @@ pub unsafe fn init_game_state(wrapper: *mut DDGameWrapper) {
     // ===== Network sync callback =====
     let sound = (*ddgame).sound;
     if !sound.is_null() {
-        let vtable = *(sound as *const *const u32);
-        let vmethod: unsafe extern "thiscall" fn(*mut DSSound) =
-            core::mem::transmute(*vtable.add(1));
-        vmethod(sound);
+        DSSound::update_channels_raw(sound);
     }
 
     // ===== CTaskTurnGame constructor =====
@@ -1024,10 +1004,7 @@ pub unsafe fn init_game_state(wrapper: *mut DDGameWrapper) {
 
         // Get frame counter via landscape vtable
         let landscape = (*ddgame).landscape;
-        let landscape_vtable = *(landscape as *const *const u32);
-        let get_frame: unsafe extern "thiscall" fn(*mut PCLandscape) -> u32 =
-            core::mem::transmute(*landscape_vtable.add(0x12));
-        let frame = get_frame(landscape);
+        let frame = PCLandscape::get_frame_checksum_raw(landscape);
 
         (*wrapper).initial_checksum = frame.wrapping_add(hash);
     }
@@ -1111,33 +1088,17 @@ unsafe fn allocate_ring_buffer_init() -> *mut u8 {
 /// Allocate and initialize a PaletteContext (0x72C bytes).
 /// Sets dirty_range_min=1, dirty_range_max=0xFF, then calls PaletteContext__Init.
 unsafe fn allocate_palette_context() -> *mut crate::render::palette::PaletteContext {
-    use crate::address::va;
-    use crate::rebase::rb;
-    use crate::wa_alloc::wa_malloc_zeroed;
+    use crate::render::palette::{palette_context_init, PaletteContext};
 
-    let mem = wa_malloc_zeroed(0x72C) as *mut u16;
-    if mem.is_null() {
+    let ctx = wa_malloc_struct_zeroed::<PaletteContext>();
+    if ctx.is_null() {
         return core::ptr::null_mut();
     }
-    *mem = 1; // dirty_range_min
-    *mem.add(1) = 0xFF; // dirty_range_max
-                        // Call PaletteContext__Init — usercall(EAX=ctx)
-    call_usercall_eax(mem as *mut u8, rb(va::PALETTE_CONTEXT_INIT));
-    *mem.add(900) = 0; // offset 0x708 (word)
-    mem as *mut crate::render::palette::PaletteContext
-}
-
-/// Bridge: usercall(EAX=ptr), plain RET.
-#[cfg(target_arch = "x86")]
-#[unsafe(naked)]
-unsafe extern "C" fn call_usercall_eax(_ptr: *mut u8, _addr: u32) {
-    core::arch::naked_asm!(
-        "movl 4(%esp), %eax", // EAX = ptr
-        "movl 8(%esp), %ecx", // ECX = target address (temp)
-        "calll *%ecx",
-        "retl",
-        options(att_syntax),
-    );
+    (*ctx).dirty_range_min = 1;
+    (*ctx).dirty_range_max = 0xFF;
+    palette_context_init(ctx);
+    (*ctx).dirty = 0;
+    ctx
 }
 
 /// Bridge: stdcall constructor with ECX = implicit register param.
@@ -1200,16 +1161,9 @@ unsafe fn init_game_state_display(
 
     let max_team_render = (*wrapper).max_team_render_index;
 
-    // Display virtual call: display->vtable[1](&display_width, &display_height)
     let mut display_width: u32 = 0;
     let mut display_height: u32 = 0;
-    {
-        let display = (*ddgame).display;
-        let vtable = *(display as *const *const u32);
-        let vmethod: unsafe extern "thiscall" fn(*mut DisplayGfx, *mut u32, *mut u32) =
-            core::mem::transmute(*vtable.add(1));
-        vmethod(display, &mut display_width, &mut display_height);
-    }
+    DisplayGfx::get_dimensions_raw((*ddgame).display, &mut display_width, &mut display_height);
 
     // Screen height for HUD: 0x12C (300) if wide layout, 0x8C (140) if narrow
     let screen_height: i32 = if max_team_render != 0xC {
@@ -1780,14 +1734,10 @@ unsafe fn init_game_state_tracking_arrays(ddgame: *mut DDGame, game_info: *const
     // Network speed callback
     let sound = (*ddgame).sound;
     if !sound.is_null() {
-        let snd_ptr = sound as *const u8;
-        let vtable = *(snd_ptr as *const *const u32);
-        let vmethod: unsafe extern "thiscall" fn(*const u8, u32, u32) =
-            core::mem::transmute(*vtable.add(2));
-        vmethod(
-            snd_ptr,
+        DSSound::set_frequency_scale_raw(
+            sound,
             (*ddgame).game_speed.0 as u32,
-            (*ddgame).game_speed_target.0 as u32,
+            (*ddgame).game_speed_target.0,
         );
     }
 
@@ -1848,3 +1798,37 @@ unsafe fn init_game_state_tracking_arrays(ddgame: *mut DDGame, game_info: *const
         }
     }
 }
+
+/// Pure Rust port of GameStateStream__Init (0x4FB490).
+///
+/// Convention: stdcall(sub_object_ptr), plain RET.
+///
+/// Initializes the sub-object within GameStateStream:
+/// - +0x14: capacity (0x100)
+/// - +0x18/+0x1C: zeroed
+/// - +0x20: main buffer (0x420 bytes, first 0x400 zeroed)
+/// - +0x24..+0x224: 32 sub-buffer elements (each 0x10 bytes)
+///
+/// Each sub-buffer element (FUN_004fdc20):
+/// - [0]: capacity (0x100)
+/// - [1]/[2]: zeroed
+/// - [3]: buffer (0x420 bytes, first 0x400 zeroed)
+unsafe fn game_state_stream_init(sub_obj: *mut u32) {
+    *sub_obj.add(5) = 0x100; // +0x14: capacity
+    *sub_obj.add(6) = 0; // +0x18
+    *sub_obj.add(7) = 0; // +0x1C
+
+    // +0x20: main buffer
+    let buf = wa_malloc_zeroed(0x420);
+    *sub_obj.add(8) = buf as u32;
+
+    // +0x24: 32 sub-buffer elements, each 0x10 bytes (4 u32s)
+    for i in 0..32usize {
+        let elem = sub_obj.add(9 + i * 4); // +0x24 + i*0x10
+        *elem = 0x100; // capacity
+        *elem.add(1) = 0;
+        *elem.add(2) = 0;
+        let elem_buf = wa_malloc_zeroed(0x420);
+        *elem.add(3) = elem_buf as u32;
+    }
+}

crates/openwa-core/src/render/landscape.rs

@@ -24,7 +24,7 @@ use crate::{engine::ddgame::DDGame, render::sprite::gfx_dir::GfxDir};
 #[repr(C)]
 pub struct PCLandscape {
     /// 0x000: Vtable pointer (0x66B208)
-    pub vtable: *mut u8,
+    pub vtable: *const PCLandscapeVtable,
     /// 0x004: Parent DDGame pointer (param_1[1])
     pub ddgame: *mut DDGame,
     /// 0x008-0x0CB: Pre-rendered crater sprites for 15 explosion sizes.
@@ -89,8 +89,8 @@ pub struct PCLandscape {
     pub level_gfx_dir: *mut GfxDir,
     /// 0xB38: GfxHandler for Water.dir (param_1[0x2CE])
     pub water_gfx_dir: *mut GfxDir,
-    /// 0xB3C: Remaining control flag
-    pub _unknown_b3c: u32,
+    /// 0xB3C: Control flag set by vtable slot 1 (donkey mode / landscape control)
+    pub control_flag: u32,
 }
 
 const _: () = assert!(core::mem::size_of::<PCLandscape>() == 0xB40);
@@ -108,14 +108,37 @@ pub struct DirtyRect {
 
 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;
+/// PCLandscape vtable (32 slots at 0x66B208).
+#[openwa_core::vtable(size = 32, va = 0x0066_B208, class = "PCLandscape")]
+pub struct PCLandscapeVtable {
+    /// destructor (0x57B540, RET 0x4)
+    #[slot(0)]
+    pub destructor: fn(this: *mut PCLandscape, flags: u32) -> *mut PCLandscape,
+    /// set control flag at +0xB3C (0x57BD10, RET 0x4)
+    #[slot(1)]
+    pub set_control_flag: fn(this: *mut PCLandscape, flag: u32),
+    /// apply explosion crater (0x57C820, RET 0xC) — terrain destruction
+    #[slot(2)]
+    pub apply_explosion: fn(this: *mut PCLandscape, p1: u32, p2: u32, p3: u32),
+    /// init landscape borders and layers (0x57D7F0, RET 0x20)
+    #[slot(6)]
+    pub init_borders: fn(
+        this: *mut PCLandscape,
+        p1: u32,
+        p2: u32,
+        p3: u32,
+        p4: u32,
+        p5: u32,
+        p6: u32,
+        p7: u32,
+        p8: u32,
+    ),
+    /// redraw single row (0x57CF60, RET 0x4)
+    #[slot(8)]
+    pub redraw_row: fn(this: *mut PCLandscape, row: u32),
+    /// get frame checksum component (0x57D540, plain RET)
+    #[slot(18)]
+    pub get_frame_checksum: fn(this: *mut PCLandscape) -> u32,
 }
+
+bind_PCLandscapeVtable!(PCLandscape, vtable);

crates/openwa-core/src/render/palette.rs

@@ -44,6 +44,29 @@ const _: () = assert!(core::mem::offset_of!(PaletteContext, cache) == 0x608);
 const _: () = assert!(core::mem::offset_of!(PaletteContext, dirty) == 0x708);
 const _: () = assert!(core::mem::offset_of!(PaletteContext, cache_iter) == 0x70A);
 
+/// Pure Rust port of PaletteContext__Init (0x5411A0).
+///
+/// Usercall: EAX = ctx pointer, plain RET.
+///
+/// Initializes the free slot stack and clears the in-use table.
+/// Caller must set `dirty_range_min` and `dirty_range_max` before calling.
+pub unsafe fn palette_context_init(ctx: *mut PaletteContext) {
+    let min = (*ctx).dirty_range_min;
+    let max = (*ctx).dirty_range_max;
+    let count = (max - min) + 1;
+
+    (*ctx).cache_count = 0;
+    (*ctx).free_count = count;
+
+    // Fill free stack with palette indices from max down to min
+    for i in 0..count as usize {
+        (*ctx).free_stack[i] = (max as u8).wrapping_sub(i as u8);
+    }
+
+    (*ctx).cache_iter = 0;
+    (*ctx).in_use = [0u8; 256];
+}
+
 /// Map an RGB color to the nearest display palette index.
 ///
 /// Rust port of `PaletteContext__MapColor` (0x5412B0). Operates on a raw

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

@@ -279,15 +279,15 @@ unsafe fn patch_dssound_vtable() -> Result<(), &'static str> {
     use openwa_core::audio::{
         dssound_destructor, dssound_noop, dssound_returns_0, dssound_returns_1,
         dssound_sub_destructor, is_channel_finished, is_slot_loaded, load_wav, play_sound,
-        play_sound_pooled, release_finished, set_channel_volume, set_master_volume, set_pan,
-        set_volume_params, stop_channel, update_channels, DSSoundVtable,
+        play_sound_pooled, release_finished, set_channel_volume, set_frequency_scale,
+        set_master_volume, set_pan, stop_channel, update_channels, DSSoundVtable,
     };
     use openwa_core::vtable_replace;
 
     vtable_replace!(DSSoundVtable, va::DS_SOUND_VTABLE, {
         destructor          => dssound_destructor,
         update_channels     => update_channels,
-        set_volume_params   => set_volume_params,
+        set_frequency_scale => set_frequency_scale,
         play_sound          => play_sound,
         play_sound_pooled   => play_sound_pooled,
         set_pan             => set_pan,