feat: add #[vtable(...)] attribute macro for typed vtable definitions

Add a proc macro that transforms sparse vtable slot definitions into
full #[repr(C)] structs with auto-filled gap slots, registry metadata,
calling wrappers, and optional address registration. Key features:

- #[slot(N)] for sparse vtables (gaps auto-filled with usize)
- Sequential slot inference when #[slot] is omitted (fully-typed vtables)
- fn(...) auto-normalized to unsafe extern "thiscall" fn(...)
- Named params (fn(this: *mut T, mode: u32)) flow through to bind wrappers
- bind_XxxVtable! companion macro generates method wrappers on class structs
- VtableInfo/VtableSlotEntry registry with inventory integration
- vtable_replace! macro for type-safe in-place vtable slot patching
- Compile-time size assertion and optional pub const + AddrEntry generation

All 8 vtable structs migrated: PaletteVtable, InputCtrlVtable,
MapViewVtable, DDDisplayVtable (38→18 lines), SoundEmitterVTable,
CTaskWormVTable, DisplayBaseVtable, DSSoundVtable.

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

crates/openwa-core/src/address.rs

@@ -61,6 +61,15 @@ pub mod va {
     pub use crate::task::filter::{CTASK_FILTER_VTABLE, CTASK_FILTER_CTOR};
     pub use crate::task::fire::{CTASK_FIRE_VTABLE, CTASK_FIRE_CTOR};
 
+    // Re-exported from modules using #[vtable(...)] attribute
+    pub use crate::display::palette::PALETTE_VTABLE;
+    pub use crate::display::dd_display::DD_DISPLAY_VTABLE;
+    pub use crate::input::controller::INPUT_CTRL_VTABLE;
+    pub use crate::frontend::map_view::MAP_VIEW_VTABLE;
+    pub use crate::task::game_task::SOUND_EMITTER_VTABLE;
+    pub use crate::display::base::DISPLAY_BASE_VTABLE;
+    pub use crate::audio::dssound::DS_SOUND_VTABLE;
+
     crate::define_addresses! {
         class "DDGameWrapper" {
             /// DDGameWrapper vtable
@@ -123,8 +132,7 @@ pub mod va {
         }
 
         class "DSSound" {
-            /// DSSound vtable
-            vtable DS_SOUND_VTABLE = 0x0066_AF20;
+            // Vtable now defined via #[vtable(...)] in audio/dssound.rs
             /// DSSound constructor — usercall(EAX=this), plain RET
             ctor/Usercall CONSTRUCT_DS_SOUND = 0x0057_3D50;
             /// DSSound init buffers — usercall(EAX=dssound), plain RET
@@ -144,14 +152,10 @@ pub mod va {
             fn/Stdcall DDKEYBOARD_POLL_KEYBOARD_STATE = 0x0057_2290;
         }
 
-        class "Palette" {
-            /// Palette vtable (0x28-byte palette object)
-            vtable PALETTE_VTABLE_MAYBE = 0x0066_A2E4;
-        }
+        // Palette vtable is now defined via #[derive(Vtable)] in display/palette.rs
 
         class "DisplayBase" {
-            /// DisplayBase primary vtable (set by constructor, has _purecall slots)
-            vtable DISPLAY_BASE_VTABLE = 0x0066_45F8;
+            // Primary vtable now defined via #[vtable(...)] in display/base.rs
             /// DisplayBase headless vtable
             vtable DISPLAY_BASE_HEADLESS_VTABLE = 0x0066_A0F8;
             /// DisplayBase constructor (0x3560-byte object)
@@ -159,8 +163,7 @@ pub mod va {
         }
 
         class "InputCtrl" {
-            /// Input controller vtable (0x1800-byte object)
-            vtable INPUT_CTRL_VTABLE = 0x0066_B3FC;
+            // Vtable now defined via #[vtable(...)] in input/controller.rs
             /// Input controller initializer
             fn/Usercall INPUT_CTRL_INIT = 0x0058_C0D0;
         }

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

@@ -77,61 +77,58 @@ impl ChannelDescriptor {
 ///
 /// Methods operate on the 8 channel descriptors and 64-entry buffer pool.
 /// Trivial slots (stubs, noops, return-constant) are marked.
-#[repr(C)]
+#[openwa_core::vtable(size = 24, va = 0x0066_AF20, class = "DSSound")]
 pub struct DSSoundVtable {
-    /// Slot 0 (0x573DB0): destructor — thiscall(this, flags)
-    pub destructor: unsafe extern "thiscall" fn(*mut DSSound, u8) -> *mut DSSound,
-    /// Slot 1 (0x574400): update_channels — iterates 8 descs, releases finished buffers
-    pub update_channels: unsafe extern "thiscall" fn(*mut DSSound),
-    /// Slot 2 (0x574460): set_volume_params — sets status_1/2, adjusts channel volumes
-    pub set_volume_params: unsafe extern "thiscall" fn(*mut DSSound, u32, i32),
-    /// Slot 3 (0x574730): play_sound — wrapper around core play, returns bool. RET 0x14 = 5 stack params.
-    pub play_sound: unsafe extern "thiscall" fn(*mut DSSound, u32, u32, u32, u32, u32) -> bool,
-    /// Slot 4 (0x574770): play_sound_pooled — allocates from buffer pool, plays. RET 0x14 = 5 stack params.
-    pub play_sound_pooled:
-        unsafe extern "thiscall" fn(*mut DSSound, u32, u32, u32, u32, u32) -> i32,
-    /// Slot 5 (0x574900): set_pan — sets pan on channel (dB lookup)
-    pub set_pan: unsafe extern "thiscall" fn(*mut DSSound, u32, u32) -> u32,
-    /// Slot 6 (0x505430): **stub** — returns 0
-    pub stub_6: unsafe extern "thiscall" fn(*mut DSSound) -> u32,
-    /// Slot 7 (0x574A10): set_master_volume — sets volume, adjusts all channels
-    pub set_master_volume: unsafe extern "thiscall" fn(*mut DSSound, i32) -> u32,
-    /// Slot 8 (0x574980): set_channel_volume — volume on specific channel
-    pub set_channel_volume: unsafe extern "thiscall" fn(*mut DSSound, i32, i32) -> u32,
-    /// Slot 9 (0x5747F0): is_channel_finished — returns 1 if stopped, 0 if playing
-    pub is_channel_finished: unsafe extern "thiscall" fn(*mut DSSound, i32) -> u8,
-    /// Slot 10 (0x574840): stop_channel — stops + releases buffer, returns to pool
-    pub stop_channel: unsafe extern "thiscall" fn(*mut DSSound, i32) -> u32,
-    /// Slot 11 (0x574AB0): release_finished — releases finished buffers, returns count
-    pub release_finished: unsafe extern "thiscall" fn(*mut DSSound) -> i32,
-    /// Slot 12 (0x573FF0): load_wav — opens WAV file, parses RIFF, creates buffer
-    pub load_wav: unsafe extern "thiscall" fn(*mut DSSound, i32, *const u8) -> u32,
-    /// Slot 13 (0x573FD0): is_slot_loaded — returns channel_slots[idx] != 0
-    pub is_slot_loaded: unsafe extern "thiscall" fn(*mut DSSound, i32) -> bool,
-    /// Slot 14 (0x573D30): sub_destructor — sets secondary vtable
-    pub sub_destructor: unsafe extern "thiscall" fn(*mut DSSound, u8) -> *mut DSSound,
-    /// Slot 15 (0x4AA060): **noop** — returns void
-    pub noop_15: unsafe extern "thiscall" fn(*mut DSSound),
-    /// Slot 16 (0x5931C0): **noop** — returns void
-    pub noop_16: unsafe extern "thiscall" fn(*mut DSSound),
-    /// Slot 17 (0x573D20): **returns_0**
-    pub returns_0_17: unsafe extern "thiscall" fn(*mut DSSound) -> u32,
-    /// Slot 18 (0x573D20): **returns_0** (same as 17)
-    pub returns_0_18: unsafe extern "thiscall" fn(*mut DSSound) -> u32,
-    /// Slot 19 (0x505430): **stub** — returns 0
-    pub stub_19: unsafe extern "thiscall" fn(*mut DSSound) -> u32,
-    /// Slot 20 (0x505430): **stub** — returns 0
-    pub stub_20: unsafe extern "thiscall" fn(*mut DSSound) -> u32,
-    /// Slot 21 (0x571AF0): **returns_0**
-    pub returns_0_21: unsafe extern "thiscall" fn(*mut DSSound) -> u32,
-    /// Slot 22 (0x505430): **stub** — returns 0
-    pub stub_22: unsafe extern "thiscall" fn(*mut DSSound) -> u32,
-    /// Slot 23 (0x4260E0): **returns_1**
-    pub returns_1_23: unsafe extern "thiscall" fn(*mut DSSound) -> u32,
+    /// destructor
+    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),
+    /// play_sound — wrapper around core play. RET 0x14 = 5 stack params.
+    pub play_sound: fn(this: *mut DSSound, slot: u32, flags: u32, volume: u32, pan: u32, freq: u32) -> bool,
+    /// play_sound_pooled — allocates from buffer pool, plays. RET 0x14.
+    pub play_sound_pooled: fn(this: *mut DSSound, slot: u32, flags: u32, volume: u32, pan: u32, freq: u32) -> i32,
+    /// set_pan — sets pan on channel (dB lookup)
+    pub set_pan: fn(this: *mut DSSound, channel: u32, pan: u32) -> u32,
+    /// **stub** — returns 0
+    pub stub_6: fn(this: *mut DSSound) -> u32,
+    /// set_master_volume — sets volume, adjusts all channels
+    pub set_master_volume: fn(this: *mut DSSound, volume: i32) -> u32,
+    /// set_channel_volume — volume on specific channel
+    pub set_channel_volume: fn(this: *mut DSSound, channel: i32, volume: i32) -> u32,
+    /// is_channel_finished — returns 1 if stopped, 0 if playing
+    pub is_channel_finished: fn(this: *mut DSSound, channel: i32) -> u8,
+    /// stop_channel — stops + releases buffer, returns to pool
+    pub stop_channel: fn(this: *mut DSSound, channel: i32) -> u32,
+    /// release_finished — releases finished buffers, returns count
+    pub release_finished: fn(this: *mut DSSound) -> i32,
+    /// load_wav — opens WAV file, parses RIFF, creates buffer
+    pub load_wav: fn(this: *mut DSSound, slot: i32, path: *const u8) -> u32,
+    /// is_slot_loaded — returns channel_slots[idx] != 0
+    pub is_slot_loaded: fn(this: *mut DSSound, slot: i32) -> bool,
+    /// sub_destructor — sets secondary vtable
+    pub sub_destructor: fn(this: *mut DSSound, flags: u8) -> *mut DSSound,
+    /// **noop**
+    pub noop_15: fn(this: *mut DSSound),
+    /// **noop**
+    pub noop_16: fn(this: *mut DSSound),
+    /// **returns_0**
+    pub returns_0_17: fn(this: *mut DSSound) -> u32,
+    /// **returns_0** (same as 17)
+    pub returns_0_18: fn(this: *mut DSSound) -> u32,
+    /// **stub** — returns 0
+    pub stub_19: fn(this: *mut DSSound) -> u32,
+    /// **stub** — returns 0
+    pub stub_20: fn(this: *mut DSSound) -> u32,
+    /// **returns_0**
+    pub returns_0_21: fn(this: *mut DSSound) -> u32,
+    /// **stub** — returns 0
+    pub stub_22: fn(this: *mut DSSound) -> u32,
+    /// **returns_1**
+    pub returns_1_23: fn(this: *mut DSSound) -> u32,
 }
 
-const _: () = assert!(core::mem::size_of::<DSSoundVtable>() == 24 * 4);
-
 #[repr(C)]
 pub struct DSSound {
     /// 0x000: Vtable pointer (0x66AF20)

crates/openwa-core/src/display/base.rs

@@ -62,47 +62,43 @@ const _: () = assert!(core::mem::size_of::<DisplayBase>() == 0x3560);
 ///
 /// In headless mode, most slots are no-op stubs. The primary vtable (0x6645F8)
 /// has _purecall for the drawing slots; the headless overlay replaces them.
-#[repr(C)]
+#[openwa_core::vtable(size = 32, va = 0x0066_45F8, class = "DisplayBase")]
 pub struct DisplayBaseVtable {
-    /// Slot 0: destructor — thiscall(this, flags)
-    pub destructor: unsafe extern "thiscall" fn(*mut DisplayBase, u8) -> *mut DisplayBase,
-    /// Slot 1: thiscall(this)
-    pub slot_01: unsafe extern "thiscall" fn(*mut DisplayBase),
-    /// Slot 2-3: thiscall(this) — identical in headless (0x4AA060)
-    pub slot_02: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_03: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_04: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_05: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_06: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_07: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_08: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_09: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_10: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_11: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_12: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_13: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_14: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_15: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_16: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_17: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_18: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_19: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_20: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_21: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_22: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_23: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_24: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_25: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_26: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_27: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_28: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_29: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_30: unsafe extern "thiscall" fn(*mut DisplayBase),
-    pub slot_31: unsafe extern "thiscall" fn(*mut DisplayBase),
+    /// destructor
+    pub destructor: fn(this: *mut DisplayBase, flags: u8) -> *mut DisplayBase,
+    pub slot_01: fn(this: *mut DisplayBase),
+    pub slot_02: fn(this: *mut DisplayBase),
+    pub slot_03: fn(this: *mut DisplayBase),
+    pub slot_04: fn(this: *mut DisplayBase),
+    pub slot_05: fn(this: *mut DisplayBase),
+    pub slot_06: fn(this: *mut DisplayBase),
+    pub slot_07: fn(this: *mut DisplayBase),
+    pub slot_08: fn(this: *mut DisplayBase),
+    pub slot_09: fn(this: *mut DisplayBase),
+    pub slot_10: fn(this: *mut DisplayBase),
+    pub slot_11: fn(this: *mut DisplayBase),
+    pub slot_12: fn(this: *mut DisplayBase),
+    pub slot_13: fn(this: *mut DisplayBase),
+    pub slot_14: fn(this: *mut DisplayBase),
+    pub slot_15: fn(this: *mut DisplayBase),
+    pub slot_16: fn(this: *mut DisplayBase),
+    pub slot_17: fn(this: *mut DisplayBase),
+    pub slot_18: fn(this: *mut DisplayBase),
+    pub slot_19: fn(this: *mut DisplayBase),
+    pub slot_20: fn(this: *mut DisplayBase),
+    pub slot_21: fn(this: *mut DisplayBase),
+    pub slot_22: fn(this: *mut DisplayBase),
+    pub slot_23: fn(this: *mut DisplayBase),
+    pub slot_24: fn(this: *mut DisplayBase),
+    pub slot_25: fn(this: *mut DisplayBase),
+    pub slot_26: fn(this: *mut DisplayBase),
+    pub slot_27: fn(this: *mut DisplayBase),
+    pub slot_28: fn(this: *mut DisplayBase),
+    pub slot_29: fn(this: *mut DisplayBase),
+    pub slot_30: fn(this: *mut DisplayBase),
+    pub slot_31: fn(this: *mut DisplayBase),
 }
 
-const _: () = assert!(core::mem::size_of::<DisplayBaseVtable>() == 32 * 4);
-
 // ── Sprite cache sub-objects ──────────────────────────────────────────────
 
 /// Sprite buffer control block (0x3C bytes, inner).

crates/openwa-core/src/display/dd_display.rs

@@ -17,146 +17,25 @@ pub struct DDDisplay {
 
 /// DDDisplay vtable (0x66A218, 38 slots).
 ///
-/// Only actively-used slots have typed signatures. Unknown slots are `usize`.
-/// Follows the DSSoundVtable pattern: all slots defined, unknowns as stubs.
-#[repr(C)]
+/// Only actively-used slots have typed signatures. Unknown slots are auto-filled.
+#[openwa_core::vtable(size = 38, va = 0x0066_A218, class = "DDDisplay")]
 pub struct DDDisplayVtable {
-    /// Slot 0: destructor
-    pub _slot_00: usize,
-    /// Slot 1
-    pub _slot_01: usize,
-    /// Slot 2
-    pub _slot_02: usize,
-    /// Slot 3
-    pub _slot_03: usize,
-    /// Slot 4: set layer color — thiscall(this, layer, color)
-    pub set_layer_color: unsafe extern "thiscall" fn(*mut DDDisplay, i32, i32),
-    /// Slot 5: set active layer — thiscall(this, layer) -> layer context ptr
-    pub set_active_layer: unsafe extern "thiscall" fn(*mut DDDisplay, i32) -> *mut u8,
-    /// Slot 6
-    pub _slot_06: usize,
-    /// Slot 7
-    pub _slot_07: usize,
-    /// Slot 8
-    pub _slot_08: usize,
-    /// Slot 9
-    pub _slot_09: usize,
-    /// Slot 10
-    pub _slot_10: usize,
-    /// Slot 11
-    pub _slot_11: usize,
-    /// Slot 12
-    pub _slot_12: usize,
-    /// Slot 13
-    pub _slot_13: usize,
-    /// Slot 14
-    pub _slot_14: usize,
-    /// Slot 15
-    pub _slot_15: usize,
-    /// Slot 16
-    pub _slot_16: usize,
-    /// Slot 17
-    pub _slot_17: usize,
-    /// Slot 18
-    pub _slot_18: usize,
-    /// Slot 19
-    pub _slot_19: usize,
-    /// Slot 20
-    pub _slot_20: usize,
-    /// Slot 21
-    pub _slot_21: usize,
-    /// Slot 22
-    pub _slot_22: usize,
-    /// Slot 23 (0x5C): set layer visibility — thiscall(this, layer, value)
-    pub set_layer_visibility: unsafe extern "thiscall" fn(*mut DDDisplay, i32, i32),
-    /// Slot 24
-    pub _slot_24: usize,
-    /// Slot 25
-    pub _slot_25: usize,
-    /// Slot 26
-    pub _slot_26: usize,
-    /// Slot 27
-    pub _slot_27: usize,
-    /// Slot 28
-    pub _slot_28: usize,
-    /// Slot 29
-    pub _slot_29: usize,
-    /// Slot 30
-    pub _slot_30: usize,
-    /// Slot 31 (0x7C): load sprite with flag — thiscall(this, layer, id, flag, gfx, name), RET 0x14
-    pub load_sprite: unsafe extern "thiscall" fn(
-        *mut DDDisplay,
-        u32,
-        u32,
-        u32,
-        *mut u8,
-        *const core::ffi::c_char,
-    ) -> i32,
-    /// Slot 32
-    pub _slot_32: usize,
-    /// Slot 33
-    pub _slot_33: usize,
-    /// Slot 34
-    pub _slot_34: usize,
-    /// Slot 35
-    pub _slot_35: usize,
-    /// Slot 36
-    pub _slot_36: usize,
-    /// Slot 37 (0x94): load sprite by layer — thiscall(this, layer, id, gfx, name), RET 0x10
-    pub load_sprite_by_layer: unsafe extern "thiscall" fn(
-        *mut DDDisplay,
-        u32,
-        u32,
-        *mut u8,
-        *const core::ffi::c_char,
-    ) -> i32,
+    /// set layer color
+    #[slot(4)]
+    pub set_layer_color: fn(this: *mut DDDisplay, layer: i32, color: i32),
+    /// set active layer, returns layer context ptr
+    #[slot(5)]
+    pub set_active_layer: fn(this: *mut DDDisplay, layer: i32) -> *mut u8,
+    /// set layer visibility
+    #[slot(23)]
+    pub set_layer_visibility: fn(this: *mut DDDisplay, layer: i32, value: i32),
+    /// load sprite with flag (RET 0x14)
+    #[slot(31)]
+    pub load_sprite: fn(this: *mut DDDisplay, layer: u32, id: u32, flag: u32, gfx: *mut u8, name: *const core::ffi::c_char) -> i32,
+    /// load sprite by layer (RET 0x10)
+    #[slot(37)]
+    pub load_sprite_by_layer: fn(this: *mut DDDisplay, layer: u32, id: u32, gfx: *mut u8, name: *const core::ffi::c_char) -> i32,
 }
 
-const _: () = assert!(core::mem::size_of::<DDDisplayVtable>() == 38 * 4);
-
-/// Typed wrappers for DDDisplay vtable calls.
-/// All take `*mut DDDisplay` since thiscall passes `this` as mutable.
-impl DDDisplay {
-    /// Vtable slot 5: set active display layer, returns layer context pointer.
-    #[inline]
-    pub unsafe fn set_active_layer(this: *mut Self, layer: i32) -> *mut u8 {
-        ((*(*this).vtable).set_active_layer)(this, layer)
-    }
-
-    /// Vtable slot 4: set color for a display layer.
-    #[inline]
-    pub unsafe fn set_layer_color(this: *mut Self, layer: i32, color: i32) {
-        ((*(*this).vtable).set_layer_color)(this, layer, color)
-    }
-
-    /// Vtable slot 23: set layer visibility.
-    #[inline]
-    pub unsafe fn set_layer_visibility(this: *mut Self, layer: i32, value: i32) {
-        ((*(*this).vtable).set_layer_visibility)(this, layer, value)
-    }
-
-    /// Vtable slot 37: load sprite into a layer by name.
-    #[inline]
-    pub unsafe fn load_sprite_by_layer(
-        this: *mut Self,
-        layer: u32,
-        id: u32,
-        gfx: *mut u8,
-        name: *const core::ffi::c_char,
-    ) -> i32 {
-        ((*(*this).vtable).load_sprite_by_layer)(this, layer, id, gfx, name)
-    }
-
-    /// Vtable slot 31: load sprite with flag.
-    #[inline]
-    pub unsafe fn load_sprite(
-        this: *mut Self,
-        layer: u32,
-        id: u32,
-        flag: u32,
-        gfx: *mut u8,
-        name: *const core::ffi::c_char,
-    ) -> i32 {
-        ((*(*this).vtable).load_sprite)(this, layer, id, flag, gfx, name)
-    }
-}
+// Generate calling wrappers: DDDisplay::set_layer_color(), etc.
+bind_DDDisplayVtable!(DDDisplay, vtable);

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

@@ -1,3 +1,20 @@
+/// Vtable for Palette (0x66A2E4).
+///
+/// Slots 2-4 are called by GameEngine__InitHardware after DDGameWrapper construction.
+/// Slots 0-1 are unknown.
+#[openwa_core::vtable(size = 5, va = 0x0066_A2E4, class = "Palette")]
+pub struct PaletteVtable {
+    /// set_mode(this, mode) — called with mode=7 during hardware init
+    #[slot(2)]
+    pub set_mode: fn(this: *mut Palette, mode: u32),
+    /// init — called during hardware init
+    #[slot(3)]
+    pub init: fn(this: *mut Palette),
+    /// reset — called first during hardware init
+    #[slot(4)]
+    pub reset: fn(this: *mut Palette),
+}
+
 /// Palette — palette management object.
 ///
 /// Vtable: 0x66A2E4.
@@ -17,23 +34,8 @@ pub struct Palette {
 
 const _: () = assert!(core::mem::size_of::<Palette>() == 0x28);
 
-/// Vtable for Palette (0x66A2E4).
-///
-/// Slots 2-4 are called by GameEngine__InitHardware after DDGameWrapper construction.
-/// Slots 0-1 are unknown.
-#[repr(C)]
-pub struct PaletteVtable {
-    /// [0]: Unknown
-    pub _slot_0: usize,
-    /// [1]: Unknown
-    pub _slot_1: usize,
-    /// [2]: set_mode(this, mode) — called with mode=7 during hardware init
-    pub set_mode: unsafe extern "thiscall" fn(*mut Palette, u32),
-    /// [3]: init(this) — called during hardware init
-    pub init: unsafe extern "thiscall" fn(*mut Palette),
-    /// [4]: reset(this) — called first during hardware init
-    pub reset: unsafe extern "thiscall" fn(*mut Palette),
-}
+// Generate calling wrappers: Palette::set_mode(), Palette::init(), Palette::reset()
+bind_PaletteVtable!(Palette, vtable);
 
 impl Palette {
     /// Create a new Palette with inline construction (no native C++ ctor).
@@ -47,17 +49,4 @@ impl Palette {
             _unknown_008: [0; 0x20],
         }
     }
-
-    /// Vtable[4]: Reset palette state.
-    pub unsafe fn reset(&mut self) {
-        vcall!(self, reset)
-    }
-    /// Vtable[3]: Initialize palette.
-    pub unsafe fn init(&mut self) {
-        vcall!(self, init)
-    }
-    /// Vtable[2]: Set palette mode.
-    pub unsafe fn set_mode(&mut self, mode: u32) {
-        vcall!(self, set_mode, mode)
-    }
 }

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

@@ -494,9 +494,9 @@ pub unsafe fn display_layer_color_init(wrapper: *mut DDGameWrapper) {
     };
 
     let display = (*wrapper).display;
-    DDDisplay::set_layer_color(display, 1, layer1_color);
-    DDDisplay::set_layer_color(display, 2, 0x20);
-    DDDisplay::set_layer_color(display, 3, 0x70);
+    (*display).set_layer_color(1, layer1_color);
+    (*display).set_layer_color(2, 0x20);
+    (*display).set_layer_color(3, 0x70);
 }
 
 /// Initialize runtime addresses for the constructor bridges.
@@ -841,16 +841,15 @@ unsafe fn init_graphics_and_resources(
         }
         let disp = (*wrapper).display;
         let gfx_dir = (*wrapper).primary_gfx_dir;
-        DDDisplay::set_layer_color(disp, 1, 0xFE);
-        DDDisplay::load_sprite(
-            disp,
+        (*disp).set_layer_color(1, 0xFE);
+        (*disp).load_sprite(
             1,
             1,
             0,
             gfx_dir,
             rb(va::STR_CDROM_SPR) as *const c_char,
         );
-        DDDisplay::set_layer_visibility(disp, 1, -100);
+        (*disp).set_layer_visibility(1, -100);
 
         // Palette slot range init (raw byte offsets into DisplayBase)
         let disp_raw = disp as *mut u8;
@@ -875,7 +874,7 @@ unsafe fn init_graphics_and_resources(
     // ── Display vtable slot 5 (offset 0x14) ──
     // Original: CALL EAX (vtable[5]), saves return value in ESI for use as
     // the `output` parameter in the color-entries GfxResource__Create call below.
-    let layer_ctx = DDDisplay::set_active_layer((*ddgame).display, 1);
+    let layer_ctx = (*(*ddgame).display).set_active_layer(1);
 
     // ── GfxDir color entries DDGame+0x730C..0x732C ──
     // Original logic: if gfx_mode!=0, try GfxResource__Create for colours.img.
@@ -1089,7 +1088,7 @@ unsafe fn init_graphics_and_resources(
             name_buf[5] = b'0' + (i / 10) as u8;
             name_buf[6] = b'0' + (i % 10) as u8;
 
-            let layer_ctx = DDDisplay::set_active_layer((*ddgame).display, 1);
+            let layer_ctx = (*(*ddgame).display).set_active_layer(1);
 
             let entry = gfx_dir_find_entry(name_buf.as_ptr().cast(), gfx_dir);
 
@@ -1272,14 +1271,13 @@ unsafe fn init_graphics_and_resources(
         );
 
         let disp = (*wrapper).display;
-        DDDisplay::set_active_layer(disp, 3);
+        (*disp).set_active_layer(3);
 
         // back.spr and debris.spr must be loaded unconditionally — they're used by
         // GenerateDebrisParticles (0x546F70) for particle effects, which affects
         // the game RNG (DDGame+0x45EC). The original constructor loads them even
         // in headless mode. Skipping them causes replay desync.
-        DDDisplay::load_sprite_by_layer(
-            disp,
+        (*disp).load_sprite_by_layer(
             3,
             0x26D,
             land_layer,
@@ -1289,10 +1287,9 @@ unsafe fn init_graphics_and_resources(
         // GenerateDebrisParticles (0x546F70) for particle effects, which
         // affects the game RNG (DDGame+0x45EC). Skipping it in headless
         // mode causes desync (longbow replay checksum mismatch at frame 1350).
-        DDDisplay::load_sprite(disp, 3, 0x26E, 0, land_layer, c"debris.spr".as_ptr());
+        (*disp).load_sprite(3, 0x26E, 0, land_layer, c"debris.spr".as_ptr());
 
-        DDDisplay::load_sprite_by_layer(
-            disp,
+        (*disp).load_sprite_by_layer(
             2,
             0x26C,
             water_layer,
@@ -1303,7 +1300,7 @@ unsafe fn init_graphics_and_resources(
 
         // ── Gradient image (0x030) ──
         let level_height = (*ddgame).level_height as i32;
-        let layer3_ctx = DDDisplay::set_active_layer(disp, 3);
+        let layer3_ctx = (*disp).set_active_layer(3);
         let s_var1 = *(layer3_ctx.add(0x606) as *const i16);
 
         if s_var1 < 0x61 && level_height == 0x2B8 {
@@ -1316,7 +1313,7 @@ unsafe fn init_graphics_and_resources(
 
         // ── Fill image → fill_pixel (0x7338) ──
         {
-            let layer2_ctx = DDDisplay::set_active_layer((*ddgame).display, 2);
+            let layer2_ctx = (*(*ddgame).display).set_active_layer(2);
             // In the original, fill.img uses piStack_126c which the decompiler
             // shows was set from piVar3 (water_layer from landscape+0xB38).
             let fill_sprite = call_gfx_find_and_load(water_layer, c"fill.img", layer2_ctx);
@@ -1381,9 +1378,9 @@ unsafe fn init_graphics_and_resources(
     // ── Final display layer visibility ──
     {
         let disp = (*wrapper).display;
-        DDDisplay::set_layer_visibility(disp, 1, 0);
-        DDDisplay::set_layer_visibility(disp, 2, 0);
-        DDDisplay::set_layer_visibility(disp, 3, 1);
+        (*disp).set_layer_visibility(1, 0);
+        (*disp).set_layer_visibility(2, 0);
+        (*disp).set_layer_visibility(3, 1);
     }
 
     let _ = crate::log::log_line("[DDGame] init_graphics_and_resources DONE");

crates/openwa-core/src/frontend/map_view.rs

@@ -36,10 +36,9 @@ pub struct MapView {
 const _: () = assert!(core::mem::size_of::<MapView>() == 0x29628);
 
 /// MapView vtable (partial — only known slots).
-#[repr(C)]
+#[openwa_core::vtable(size = 2, va = 0x0064_FC60, class = "MapView")]
 pub struct MapViewVtable {
-    /// Slot 0: Unknown virtual method.
-    pub slot_0: usize,
-    /// Slot 1: Destructor — thiscall(this, free_flag). Frees the object if flag & 1.
-    pub destructor: unsafe extern "thiscall" fn(*mut MapView, i32),
+    /// Destructor — thiscall(this, free_flag). Frees the object if flag & 1.
+    #[slot(1)]
+    pub destructor: fn(this: *mut MapView, free_flag: i32),
 }

crates/openwa-core/src/input/controller.rs

@@ -1,3 +1,13 @@
+/// Vtable for InputCtrl (0x66B3FC).
+///
+/// Only slot 0 (destructor) is known — called on init failure cleanup.
+#[openwa_core::vtable(size = 1, va = 0x0066_B3FC, class = "InputCtrl")]
+pub struct InputCtrlVtable {
+    /// Destructor(this, flags) — scalar deleting destructor
+    #[slot(0)]
+    pub destructor: fn(this: *mut InputCtrl, flags: u32),
+}
+
 /// InputCtrl — input controller subsystem.
 ///
 /// Initializer: FUN_0058C0D0, usercall(ESI=this) + stdcall(4 params), RET 0x10.
@@ -20,18 +30,12 @@ pub struct InputCtrl {
 
 const _: () = assert!(core::mem::size_of::<InputCtrl>() == 0x1800);
 
-/// Vtable for InputCtrl (0x66B3FC).
-///
-/// Only slot 0 (destructor) is known — called on init failure cleanup.
-#[repr(C)]
-pub struct InputCtrlVtable {
-    /// [0]: Destructor(this, flags) — scalar deleting destructor
-    pub destructor: unsafe extern "thiscall" fn(*mut InputCtrl, u32),
-}
+// Generate calling wrappers: InputCtrl::destructor()
+bind_InputCtrlVtable!(InputCtrl, vtable);
 
 impl InputCtrl {
     /// Vtable[0]: Destroy and optionally free (flags & 1 = free).
     pub unsafe fn destroy(&mut self, flags: u32) {
-        vcall!(self, destructor, flags)
+        self.destructor(flags);
     }
 }

crates/openwa-core/src/lib.rs

@@ -23,6 +23,7 @@ pub use inventory;
 
 // Re-export derive macros so users write `use openwa_core::FieldRegistry;`
 pub use openwa_derive::FieldRegistry;
+pub use openwa_derive::vtable;
 
 #[macro_use]
 pub mod macros;

crates/openwa-core/src/macros.rs

@@ -149,6 +149,59 @@ macro_rules! define_addresses {
     };
 }
 
+/// Replace specific slots in a WA.exe vtable with Rust function pointers.
+///
+/// Expands to executable code for use inside `install()` functions.
+/// Uses `patch_vtable` (VirtualProtect) to make .rdata writable.
+///
+/// # Syntax
+///
+/// ```ignore
+/// vtable_replace!(PaletteVtable, va::PALETTE_VTABLE, {
+///     slot 2 => my_set_mode,                    // pure replace
+///     slot 3 [originals::INIT] => my_init,      // replace + save original
+/// })?;
+/// ```
+///
+/// The `[static]` syntax saves the original fn pointer to the given `AtomicU32`
+/// before overwriting. Omit it for pure replacement (no call-through).
+///
+/// Size is derived from `size_of::<VtableType>() / 4`.
+#[macro_export]
+macro_rules! vtable_replace {
+    ($vtable_ty:ty, $va:expr, { $($slot:tt)* }) => {{
+        let vtable_ptr = $crate::rebase::rb($va) as *mut u32;
+        let slot_count = core::mem::size_of::<$vtable_ty>() / 4;
+        unsafe {
+            $crate::vtable::patch_vtable(vtable_ptr, slot_count, |vt| {
+                $crate::vtable_replace!(@slots vt $($slot)*);
+            })
+        }
+    }};
+
+    // Slot with original save: slot N [static_path] => replacement,
+    (@slots $vt:ident slot $idx:literal [$orig:expr] => $replacement:expr, $($rest:tt)*) => {
+        {
+            let slot = $vt.add($idx);
+            $orig.store(unsafe { *slot }, core::sync::atomic::Ordering::Relaxed);
+            unsafe { *slot = $replacement as *const () as u32; }
+        }
+        $crate::vtable_replace!(@slots $vt $($rest)*);
+    };
+
+    // Slot without original save: slot N => replacement,
+    (@slots $vt:ident slot $idx:literal => $replacement:expr, $($rest:tt)*) => {
+        {
+            let slot = $vt.add($idx);
+            unsafe { *slot = $replacement as *const () as u32; }
+        }
+        $crate::vtable_replace!(@slots $vt $($rest)*);
+    };
+
+    // Base case
+    (@slots $vt:ident) => {};
+}
+
 /// Call a virtual method through a typed vtable pointer.
 ///
 /// Assumes `$obj` is a raw pointer to a struct whose first field `vtable`

crates/openwa-core/src/registry.rs

@@ -308,6 +308,82 @@ pub fn field_at_inherited(struct_name: &str, offset: u32) -> Option<&'static Fie
     None
 }
 
+// =========================================================================
+// Vtable registry (for #[derive(Vtable)])
+// =========================================================================
+
+/// Metadata for a single vtable slot.
+#[derive(Debug, Clone, Copy)]
+pub struct VtableSlotEntry {
+    /// Slot index in the vtable (0-based).
+    pub index: u32,
+    /// Method name (e.g., "set_mode").
+    pub name: &'static str,
+    /// Brief description from doc comment.
+    pub doc: &'static str,
+}
+
+/// Metadata for a vtable struct.
+#[derive(Debug)]
+pub struct VtableInfo {
+    /// Vtable struct name (e.g., "PaletteVtable").
+    pub struct_name: &'static str,
+    /// Owning C++ class name (e.g., "Palette"), if specified.
+    pub class_name: &'static str,
+    /// Ghidra VA of the vtable in .rdata (0 if not specified).
+    pub ghidra_va: u32,
+    /// Total number of slots in the vtable.
+    pub slot_count: u32,
+    /// Known (named) slots only.
+    pub slots: &'static [VtableSlotEntry],
+}
+
+impl VtableInfo {
+    /// Look up a slot by method name.
+    pub fn slot_by_name(&self, name: &str) -> Option<&VtableSlotEntry> {
+        self.slots.iter().find(|s| s.name == name)
+    }
+
+    /// Look up a slot by index.
+    pub fn slot_by_index(&self, index: u32) -> Option<&VtableSlotEntry> {
+        self.slots.iter().find(|s| s.index == index)
+    }
+}
+
+/// Trait for vtable structs with auto-generated registry metadata.
+pub trait HasVtableRegistry {
+    fn vtable_info() -> &'static VtableInfo;
+}
+
+/// A vtable's registry submitted to the global collection via `inventory`.
+pub struct VtableRegistration {
+    pub info: &'static VtableInfo,
+}
+
+inventory::collect!(VtableRegistration);
+
+static VTABLE_MAP: OnceLock<std::collections::HashMap<&'static str, &'static VtableInfo>> =
+    OnceLock::new();
+
+fn vtable_map() -> &'static std::collections::HashMap<&'static str, &'static VtableInfo> {
+    VTABLE_MAP.get_or_init(|| {
+        inventory::iter::<VtableRegistration>
+            .into_iter()
+            .map(|r| (r.info.struct_name, r.info))
+            .collect()
+    })
+}
+
+/// Look up vtable metadata by struct name.
+pub fn vtable_info_for(struct_name: &str) -> Option<&'static VtableInfo> {
+    vtable_map().get(struct_name).copied()
+}
+
+/// Return all registered vtable info entries.
+pub fn all_vtable_info() -> impl Iterator<Item = &'static VtableInfo> {
+    vtable_map().values().copied()
+}
+
 // =========================================================================
 // Live object tracker
 // =========================================================================
@@ -602,4 +678,51 @@ mod tests {
         assert!(fields.is_some(), "CTask fields not found via vtable");
         assert_eq!(fields.unwrap().struct_name, "CTask");
     }
+
+    #[test]
+    fn vtable_registry_palette() {
+        // PaletteVtable should be registered via #[vtable(...)] attribute
+        let info = vtable_info_for("PaletteVtable");
+        assert!(info.is_some(), "PaletteVtable not found in vtable registry");
+        let info = info.unwrap();
+
+        assert_eq!(info.struct_name, "PaletteVtable");
+        assert_eq!(info.class_name, "Palette");
+        assert_eq!(info.ghidra_va, 0x0066_A2E4);
+        assert_eq!(info.slot_count, 5);
+        assert_eq!(info.slots.len(), 3); // set_mode, init, reset
+
+        // Check individual slots
+        let set_mode = info.slot_by_name("set_mode");
+        assert!(set_mode.is_some(), "set_mode not found");
+        assert_eq!(set_mode.unwrap().index, 2);
+
+        let init = info.slot_by_index(3);
+        assert!(init.is_some(), "slot 3 not found");
+        assert_eq!(init.unwrap().name, "init");
+    }
+
+    #[test]
+    fn vtable_generates_addr_entry() {
+        use crate::address::va;
+
+        // The vtable macro should have generated PALETTE_VTABLE const
+        assert_eq!(va::PALETTE_VTABLE, 0x0066_A2E4);
+
+        // And an AddrEntry in the registry
+        let entry = lookup_va_exact(0x0066_A2E4);
+        assert!(entry.is_some(), "PALETTE_VTABLE addr entry not found");
+        let entry = entry.unwrap();
+        assert_eq!(entry.kind, AddrKind::Vtable);
+        assert_eq!(entry.class_name, Some("Palette"));
+    }
+
+    #[test]
+    fn vtable_size_assertion() {
+        // PaletteVtable should be 5 * 4 = 20 bytes
+        assert_eq!(
+            core::mem::size_of::<crate::display::palette::PaletteVtable>(),
+            5 * core::mem::size_of::<usize>()
+        );
+    }
 }

crates/openwa-core/src/task/game_task.rs

@@ -6,8 +6,7 @@ crate::define_addresses! {
     class "CGameTask" {
         /// CGameTask vtable - extends CTask vtable with 12 more methods
         vtable CGAMETASK_VTABLE = 0x0066_41F8;
-        /// CGameTask sound emitter vtable (embedded sub-object at offset 0xE8)
-        vtable CGAMETASK_SOUND_EMITTER_VT = 0x0066_9CF8;
+        // Sound emitter vtable now defined via #[vtable(...)] on SoundEmitterVTable
         /// CGameTask constructor - calls CTask ctor, sets physics defaults
         ctor/Stdcall CGAMETASK_CONSTRUCTOR = 0x004F_ED50;
         /// CGameTask::vtable0 override
@@ -19,6 +18,9 @@ crate::define_addresses! {
     }
 }
 
+/// Backward-compatible alias for the SoundEmitter vtable const.
+pub const CGAMETASK_SOUND_EMITTER_VT: u32 = SOUND_EMITTER_VTABLE;
+
 /// Game task - extends CTask with physics and gameplay data.
 ///
 /// PARTIAL: Most fields between 0x30-0x83 and 0x98-0xE7 are unknown.
@@ -81,18 +83,18 @@ const _: () = assert!(core::mem::size_of::<SoundEmitter>() == 0x14);
 ///
 /// Slots [0]-[4] are the sound emitter's own interface.
 /// Slots [5]-[11] are inherited CTask base methods.
-#[repr(C)]
+#[openwa_core::vtable(size = 12, va = 0x0066_9CF8, class = "SoundEmitter")]
 pub struct SoundEmitterVTable {
-    /// [0] 0x546680: GetPosition(this, out_x, out_y) — reads pos_x/pos_y via owner
-    pub get_position: unsafe extern "thiscall" fn(*const SoundEmitter, *mut u32, *mut u32),
-    /// [1] 0x5466A0: GetPosition2(this, out_x, out_y) — reads CGameTask+0x38/0x3C
-    pub get_position2: unsafe extern "thiscall" fn(*const SoundEmitter, *mut u32, *mut u32),
-    /// [2] 0x4260E0: Unknown
-    pub _unknown_2: *const (),
-    /// [3] 0x546990: Destructor(this, flags)
-    pub destructor: unsafe extern "thiscall" fn(*mut SoundEmitter, u32) -> *mut SoundEmitter,
-    /// [4] 0x546760: HandleMessage — sound queue manager
-    pub handle_message: unsafe extern "thiscall" fn(*mut SoundEmitter, u32, u32, u32, u32),
-    /// [5]-[11]: Inherited CTask base methods
-    pub _base_methods: [*const (); 7],
+    /// GetPosition(this, out_x, out_y) — reads pos_x/pos_y via owner
+    #[slot(0)]
+    pub get_position: fn(this: *const SoundEmitter, out_x: *mut u32, out_y: *mut u32),
+    /// GetPosition2 — reads CGameTask+0x38/0x3C
+    #[slot(1)]
+    pub get_position2: fn(this: *const SoundEmitter, out_x: *mut u32, out_y: *mut u32),
+    /// Destructor
+    #[slot(3)]
+    pub destructor: fn(this: *mut SoundEmitter, flags: u32) -> *mut SoundEmitter,
+    /// HandleMessage — sound queue manager
+    #[slot(4)]
+    pub handle_message: fn(this: *mut SoundEmitter, sender: u32, msg_type: u32, size: u32, data: u32),
 }

crates/openwa-core/src/task/worm.rs

@@ -25,56 +25,56 @@ crate::define_addresses! {
 /// 0x38 SetState          0x3C CheckPendingAction 0x40 IsNotOnRope
 /// 0x44 inherited         0x48 GetTeamIndex     0x4C inherited
 /// ```
-#[repr(C)]
+#[openwa_core::vtable(size = 20)]
 pub struct CTaskWormVTable {
-    /// [0] 0x0050CAA0: WriteReplayState — serializes worm state to a replay stream;
-    ///   writes entity type byte 0x12, then packs field groups based on current state
-    pub write_replay_state: unsafe extern "thiscall" fn(*mut CTaskWorm, *mut u8),
-    /// [1] 0x0050C7E0: Free — calls inner destructor, then `_free(this)` if flags & 1
-    pub free: unsafe extern "thiscall" fn(*mut CTaskWorm, u8) -> *mut CTaskWorm,
-    /// [2] 0x00510B40: HandleMessage — processes all TaskMessages sent to this worm
-    pub handle_message:
-        unsafe extern "thiscall" fn(*mut CTaskWorm, *mut CTask, u32, u32, *const u8),
-    /// [3] 0x00516780: GetEntityData — returns worm data by query code:
-    ///   0x7D0=(pos_x, pos_y), 0x7D1/0x7D2=collision test, 0x7D4=full state dump
-    pub get_entity_data: unsafe extern "thiscall" fn(*mut CTaskWorm, u32, u32, *mut u32) -> u32,
-    /// [4]-[6]: Inherited CTask stubs (not overridden by CTaskWorm)
-    pub _inherited_4_to_6: [*const (); 3],
-    /// [7] 0x0050D5D0: OnContactEntity — handles physical contact with another entity;
-    ///   worm-on-dying-worm → apply crush damage; projectile close-pass → SetState(0x80)
-    pub on_contact_entity: unsafe extern "thiscall" fn(*mut CTaskWorm, *mut CGameTask, u32) -> u32,
-    /// [8] 0x0050D9A0: OnWormPush — post-contact worm-worm push impulse;
-    ///   deduplicates via a recent-collision table, then adjusts pos_x or pos_y
-    pub on_worm_push: unsafe extern "thiscall" fn(*mut CTaskWorm, *mut CGameTask, u32) -> u32,
-    /// [9] 0x0050D810: OnLandBounce — worm lands on terrain; plays thud sound, bounce physics
-    pub on_land_bounce: unsafe extern "thiscall" fn(*mut CTaskWorm),
-    /// [10] 0x0050D820: OnLandSlide — secondary landing callback; sliding/friction physics
-    pub on_land_slide: unsafe extern "thiscall" fn(*mut CTaskWorm),
-    /// [11] 0x0050D570: OnSink — worm sinks in water/acid; applies (dx, dy) displacement,
-    ///   transitions to drowning state (0x7F) unless already flying/rope/dead
-    pub on_sink: unsafe extern "thiscall" fn(*mut CTaskWorm, i32, i32) -> u32,
-    /// [12]: Inherited (vtable30 from CGameTask — not overridden)
-    pub _inherited_12: *const (),
-    /// [13] 0x0050D3B0: OnKilled — worm death; plays death sound (0x3A),
-    ///   transitions to dead state (0x81 or 0x89) based on game round count
-    pub on_killed: unsafe extern "thiscall" fn(*mut CTaskWorm),
-    /// [14] 0x0050E850: SetState — worm state machine; handles all state transitions
-    ///   (0x65=idle, 0x67=active turn, 0x7F=drowning, 0x80=hurt, 0x81/0x86=dead, …)
-    pub set_state: unsafe extern "thiscall" fn(*mut CTaskWorm, u32),
-    /// [15] 0x00516900: CheckPendingAction — if field +0xBC is set, calls SetState(0x73)
-    pub check_pending_action: unsafe extern "thiscall" fn(*mut CTaskWorm),
-    /// [16] 0x00516920: IsNotOnRope — returns true if worm state != 0x7C (rope-swinging)
-    pub is_not_on_rope: unsafe extern "thiscall" fn(*const CTaskWorm) -> bool,
-    /// [17]: Inherited (vtable44 from CGameTask — not overridden)
-    pub _inherited_17: *const (),
-    /// [18] 0x005168F0: GetTeamIndex — returns worm's team index (field +0xFC)
-    pub get_team_index: unsafe extern "thiscall" fn(*const CTaskWorm) -> u32,
-    /// [19]: Inherited (vtable4C from CGameTask — not overridden)
-    pub _inherited_19: *const (),
+    /// WriteReplayState — serializes worm state to a replay stream
+    #[slot(0)]
+    pub write_replay_state: fn(this: *mut CTaskWorm, stream: *mut u8),
+    /// Free — calls inner destructor, then `_free(this)` if flags & 1
+    #[slot(1)]
+    pub free: fn(this: *mut CTaskWorm, flags: u8) -> *mut CTaskWorm,
+    /// HandleMessage — processes all TaskMessages sent to this worm
+    #[slot(2)]
+    pub handle_message: fn(this: *mut CTaskWorm, sender: *mut CTask, msg_type: u32, size: u32, data: *const u8),
+    /// GetEntityData — returns worm data by query code
+    #[slot(3)]
+    pub get_entity_data: fn(this: *mut CTaskWorm, query: u32, param: u32, out: *mut u32) -> u32,
+    // Slots 4-6: Inherited CTask stubs (auto-filled as usize)
+    /// OnContactEntity — handles physical contact with another entity
+    #[slot(7)]
+    pub on_contact_entity: fn(this: *mut CTaskWorm, other: *mut CGameTask, flags: u32) -> u32,
+    /// OnWormPush — post-contact worm-worm push impulse
+    #[slot(8)]
+    pub on_worm_push: fn(this: *mut CTaskWorm, other: *mut CGameTask, flags: u32) -> u32,
+    /// OnLandBounce — worm lands on terrain; plays thud sound, bounce physics
+    #[slot(9)]
+    pub on_land_bounce: fn(this: *mut CTaskWorm),
+    /// OnLandSlide — secondary landing callback; sliding/friction physics
+    #[slot(10)]
+    pub on_land_slide: fn(this: *mut CTaskWorm),
+    /// OnSink — worm sinks in water/acid; transitions to drowning state
+    #[slot(11)]
+    pub on_sink: fn(this: *mut CTaskWorm, dx: i32, dy: i32) -> u32,
+    // Slot 12: Inherited (auto-filled)
+    /// OnKilled — worm death; plays death sound, transitions to dead state
+    #[slot(13)]
+    pub on_killed: fn(this: *mut CTaskWorm),
+    /// SetState — worm state machine; handles all state transitions
+    #[slot(14)]
+    pub set_state: fn(this: *mut CTaskWorm, state: u32),
+    /// CheckPendingAction — if field +0xBC is set, calls SetState(0x73)
+    #[slot(15)]
+    pub check_pending_action: fn(this: *mut CTaskWorm),
+    /// IsNotOnRope — returns true if worm state != 0x7C (rope-swinging)
+    #[slot(16)]
+    pub is_not_on_rope: fn(this: *const CTaskWorm) -> bool,
+    // Slot 17: Inherited (auto-filled)
+    /// GetTeamIndex — returns worm's team index (field +0xFC)
+    #[slot(18)]
+    pub get_team_index: fn(this: *const CTaskWorm) -> u32,
+    // Slot 19: Inherited (auto-filled)
 }
 
-const _: () = assert!(core::mem::size_of::<CTaskWormVTable>() == 20 * 4);
-
 /// Worm entity task — the primary playable character in WA.
 ///
 /// Extends CGameTask (0xFC bytes) with worm identity, physics overrides, and

crates/openwa-derive/src/lib.rs

@@ -25,6 +25,508 @@ use proc_macro::TokenStream;
 use quote::quote;
 use syn::{parse_macro_input, Data, DeriveInput, Fields, Lit, Meta};
 
+// =========================================================================
+// #[derive(Vtable)]
+// =========================================================================
+
+/// Derive a typed vtable struct from a sparse slot definition.
+///
+/// Only declare known methods with `#[slot(N)]`. The macro generates the full
+/// `#[repr(C)]` struct with `usize` gap-fillers for unknown slots, plus:
+///
+/// - Registry metadata (`HasVtableRegistry` impl + `inventory` registration)
+/// - A companion `bind_{VtableName}!` macro for generating calling wrappers
+/// - Optional `pub const` + `AddrEntry` if `va` is specified
+/// - Compile-time size assertion
+///
+/// # Attributes
+///
+/// - `#[vtable(size = N)]` — total number of slots (required)
+/// - `#[vtable(va = 0x...)]` — Ghidra VA of the vtable in .rdata (optional)
+/// - `#[vtable(class = "Name")]` — owning C++ class name (optional)
+///
+/// # Example
+///
+/// ```ignore
+/// #[derive(Vtable)]
+/// #[vtable(size = 5, va = 0x0066_A2E4, class = "Palette")]
+/// pub struct PaletteVtable {
+///     #[slot(2)]
+///     pub set_mode: unsafe extern "thiscall" fn(*mut Palette, u32),
+///     #[slot(3)]
+///     pub init: unsafe extern "thiscall" fn(*mut Palette),
+///     #[slot(4)]
+///     pub reset: unsafe extern "thiscall" fn(*mut Palette),
+/// }
+/// ```
+/// Attribute macro that transforms a sparse vtable definition into a full
+/// `#[repr(C)]` struct with gap-fillers, registry metadata, and a binding macro.
+///
+/// See module docs for usage.
+#[proc_macro_attribute]
+pub fn vtable(attr: TokenStream, item: TokenStream) -> TokenStream {
+    let input = parse_macro_input!(item as DeriveInput);
+    let attr_tokens = proc_macro2::TokenStream::from(attr);
+    match vtable_impl(attr_tokens, input) {
+        Ok(ts) => ts.into(),
+        Err(e) => e.to_compile_error().into(),
+    }
+}
+
+fn vtable_impl(
+    attr: proc_macro2::TokenStream,
+    input: DeriveInput,
+) -> syn::Result<proc_macro2::TokenStream> {
+    let struct_name = &input.ident;
+    let struct_name_str = struct_name.to_string();
+    let vis = &input.vis;
+
+    // Parse vtable(size = N, va = 0x..., class = "...") from the attribute args
+    let (vtable_size, vtable_va, class_name) = parse_vtable_attr_args(attr, struct_name)?;
+
+    // Parse fields — each must have #[slot(N)]
+    let fields = match &input.data {
+        Data::Struct(data) => match &data.fields {
+            Fields::Named(named) => &named.named,
+            _ => {
+                return Err(syn::Error::new_spanned(
+                    struct_name,
+                    "Vtable requires named fields",
+                ));
+            }
+        },
+        _ => {
+            return Err(syn::Error::new_spanned(
+                struct_name,
+                "Vtable can only be used on structs",
+            ));
+        }
+    };
+
+    // Collect slots. #[slot(N)] is optional — if omitted, indices are assigned
+    // sequentially. If ANY field has #[slot(N)], all must (mixing is an error).
+    let mut slots: Vec<SlotInfo> = Vec::new();
+    let mut has_explicit_slot = false;
+    let mut has_implicit_slot = false;
+
+    for (field_idx, field) in fields.iter().enumerate() {
+        let ident = field.ident.as_ref().ok_or_else(|| {
+            syn::Error::new_spanned(field, "Vtable fields must be named")
+        })?;
+
+        let explicit_index = parse_slot_attr(&field.attrs, ident)?;
+
+        let slot_index = match explicit_index {
+            Some(idx) => {
+                has_explicit_slot = true;
+                idx
+            }
+            None => {
+                has_implicit_slot = true;
+                field_idx as u32
+            }
+        };
+
+        if has_explicit_slot && has_implicit_slot {
+            return Err(syn::Error::new_spanned(
+                ident,
+                "cannot mix fields with and without #[slot(N)] — use it on all or none",
+            ));
+        }
+
+        if slot_index >= vtable_size {
+            return Err(syn::Error::new_spanned(
+                ident,
+                format!("slot index {} >= vtable size {}", slot_index, vtable_size),
+            ));
+        }
+
+        // Check for duplicates
+        if slots.iter().any(|s| s.index == slot_index) {
+            return Err(syn::Error::new_spanned(
+                ident,
+                format!("duplicate slot index {}", slot_index),
+            ));
+        }
+
+        let doc = extract_doc_comment(&field.attrs);
+        let kept_attrs: Vec<_> = field
+            .attrs
+            .iter()
+            .filter(|a| !a.path().is_ident("slot"))
+            .cloned()
+            .collect();
+
+        // Normalize fn type: plain `fn(...)` becomes `unsafe extern "thiscall" fn(...)`
+        let normalized_ty = normalize_vtable_fn_type(&field.ty);
+
+        slots.push(SlotInfo {
+            index: slot_index,
+            ident: ident.clone(),
+            ty: normalized_ty,
+            doc,
+            attrs: kept_attrs,
+            vis: field.vis.clone(),
+        });
+    }
+
+    // Sort by slot index
+    slots.sort_by_key(|s| s.index);
+
+    // Generate struct fields: gap-fillers + typed slots
+    let mut struct_fields = Vec::new();
+    let mut next_index = 0u32;
+
+    for slot in &slots {
+        // Fill gaps with usize fields
+        while next_index < slot.index {
+            let gap_name = quote::format_ident!("_slot_{}", next_index);
+            struct_fields.push(quote! {
+                pub #gap_name: usize
+            });
+            next_index += 1;
+        }
+
+        // Emit the typed slot
+        let ident = &slot.ident;
+        let ty = &slot.ty;
+        let attrs = &slot.attrs;
+        let slot_vis = &slot.vis;
+        struct_fields.push(quote! {
+            #(#attrs)*
+            #slot_vis #ident: #ty
+        });
+        next_index = slot.index + 1;
+    }
+
+    // Fill trailing gaps
+    while next_index < vtable_size {
+        let gap_name = quote::format_ident!("_slot_{}", next_index);
+        struct_fields.push(quote! {
+            pub #gap_name: usize
+        });
+        next_index += 1;
+    }
+
+    // Generate registry slot entries
+    let slot_entries: Vec<_> = slots
+        .iter()
+        .map(|s| {
+            let idx = s.index;
+            let name = s.ident.to_string();
+            let doc = &s.doc;
+            quote! {
+                openwa_core::registry::VtableSlotEntry {
+                    index: #idx,
+                    name: #name,
+                    doc: #doc,
+                }
+            }
+        })
+        .collect();
+    let slot_entry_count = slot_entries.len();
+
+    let class_name_str = class_name.as_deref().unwrap_or("");
+    let va_value = vtable_va.unwrap_or(0);
+
+    // Generate the info static name
+    let info_static = quote::format_ident!("_VTABLE_INFO_{}", struct_name);
+
+    // Generate optional pub const + AddrEntry for the VA
+    let va_items = if let Some(va) = vtable_va {
+        // Derive const name: class "Palette" → PALETTE_VTABLE, or struct PaletteVtable → PALETTE_VTABLE
+        let const_name_str = if let Some(ref class) = class_name {
+            format!("{}_VTABLE", to_screaming_snake(class))
+        } else {
+            to_screaming_snake(&struct_name_str)
+        };
+        let const_ident = quote::format_ident!("{}", const_name_str);
+        let class_expr = if let Some(ref class) = class_name {
+            quote! { Some(#class) }
+        } else {
+            quote! { None }
+        };
+        quote! {
+            #vis const #const_ident: u32 = #va;
+
+            openwa_core::inventory::submit! {
+                openwa_core::registry::AddrEntry {
+                    va: #va,
+                    name: #const_name_str,
+                    kind: openwa_core::registry::AddrKind::Vtable,
+                    calling_conv: None,
+                    class_name: #class_expr,
+                    doc: "",
+                }
+            }
+        }
+    } else {
+        quote! {}
+    };
+
+    // Generate the companion bind macro
+    let bind_macro_name = quote::format_ident!("bind_{}", struct_name);
+    let bind_methods = generate_bind_methods(&slots)?;
+
+    let vtable_size_usize = vtable_size as usize;
+
+    let expanded = quote! {
+        #[repr(C)]
+        #vis struct #struct_name {
+            #(#struct_fields),*
+        }
+
+        const _: () = assert!(
+            core::mem::size_of::<#struct_name>() == #vtable_size_usize * core::mem::size_of::<usize>(),
+            "vtable struct size mismatch"
+        );
+
+        // Vtable registry metadata
+        #[doc(hidden)]
+        #[allow(non_upper_case_globals)]
+        static #info_static: openwa_core::registry::VtableInfo = openwa_core::registry::VtableInfo {
+            struct_name: #struct_name_str,
+            class_name: #class_name_str,
+            ghidra_va: #va_value,
+            slot_count: #vtable_size,
+            slots: {
+                const ENTRIES: [openwa_core::registry::VtableSlotEntry; #slot_entry_count] = [
+                    #(#slot_entries),*
+                ];
+                &ENTRIES
+            },
+        };
+
+        impl openwa_core::registry::HasVtableRegistry for #struct_name {
+            fn vtable_info() -> &'static openwa_core::registry::VtableInfo {
+                &#info_static
+            }
+        }
+
+        openwa_core::inventory::submit! {
+            openwa_core::registry::VtableRegistration {
+                info: &#info_static,
+            }
+        }
+
+        #va_items
+
+        /// Bind this vtable's known methods as wrapper methods on a class struct.
+        ///
+        /// Usage: `bind_VtableName!(ClassName, vtable_field_name);`
+        #[macro_export]
+        macro_rules! #bind_macro_name {
+            ($class:ty, $vtable_field:ident) => {
+                impl $class {
+                    #bind_methods
+                }
+            };
+        }
+    };
+
+    Ok(expanded)
+}
+
+/// A parsed vtable slot definition.
+struct SlotInfo {
+    index: u32,
+    ident: syn::Ident,
+    ty: syn::Type,
+    doc: String,
+    attrs: Vec<syn::Attribute>,
+    vis: syn::Visibility,
+}
+
+/// Generate the method wrappers for the bind macro.
+///
+/// For each slot, parses the fn pointer type to extract:
+/// - `this` mutability (*mut → &mut self, *const → &self)
+/// - Remaining parameters (with generated names p0, p1, ...)
+/// - Return type
+fn generate_bind_methods(slots: &[SlotInfo]) -> syn::Result<proc_macro2::TokenStream> {
+    let mut methods = Vec::new();
+
+    for slot in slots {
+        let ident = &slot.ident;
+        let doc = &slot.doc;
+
+        // Parse the fn pointer type
+        let bare_fn = match &slot.ty {
+            syn::Type::BareFn(bf) => bf,
+            other => {
+                return Err(syn::Error::new_spanned(
+                    other,
+                    "vtable slot type must be a bare fn pointer (e.g., unsafe extern \"thiscall\" fn(...))",
+                ));
+            }
+        };
+
+        // First param is `this` — determine mutability
+        let inputs = &bare_fn.inputs;
+        if inputs.is_empty() {
+            return Err(syn::Error::new_spanned(
+                bare_fn,
+                "vtable fn must have at least a `this` parameter",
+            ));
+        }
+
+        let this_is_const = is_const_ptr(&inputs[0].ty);
+        let self_param = if this_is_const {
+            quote! { &self }
+        } else {
+            quote! { &mut self }
+        };
+        let self_cast = if this_is_const {
+            quote! { self as *const Self }
+        } else {
+            quote! { self as *mut Self }
+        };
+
+        // Remaining params
+        let mut param_decls = Vec::new();
+        let mut param_names = Vec::new();
+        for (i, arg) in inputs.iter().skip(1).enumerate() {
+            let param_name = if let Some(ref name) = arg.name {
+                let (ident, _) = name;
+                ident.clone()
+            } else {
+                quote::format_ident!("p{}", i)
+            };
+            let param_ty = &arg.ty;
+            param_decls.push(quote! { #param_name: #param_ty });
+            param_names.push(param_name);
+        }
+
+        // Return type
+        let ret_ty = match &bare_fn.output {
+            syn::ReturnType::Default => quote! {},
+            syn::ReturnType::Type(_, ty) => quote! { -> #ty },
+        };
+
+        methods.push(quote! {
+            #[doc = #doc]
+            pub unsafe fn #ident(#self_param #(, #param_decls)*) #ret_ty {
+                ((*self.$vtable_field).#ident)(#self_cast #(, #param_names)*)
+            }
+        });
+    }
+
+    Ok(quote! { #(#methods)* })
+}
+
+/// Normalize a vtable fn pointer type: if it's a plain `fn(...)` (no `unsafe`,
+/// no explicit ABI), transform it to `unsafe extern "thiscall" fn(...)`.
+///
+/// Already-qualified types (e.g., `unsafe extern "thiscall" fn(...)`) pass through unchanged.
+fn normalize_vtable_fn_type(ty: &syn::Type) -> syn::Type {
+    if let syn::Type::BareFn(bare) = ty {
+        let needs_unsafe = bare.unsafety.is_none();
+        let needs_abi = bare.abi.is_none();
+
+        if needs_unsafe || needs_abi {
+            let mut normalized = bare.clone();
+            if needs_unsafe {
+                normalized.unsafety = Some(syn::token::Unsafe::default());
+            }
+            if needs_abi {
+                normalized.abi = Some(syn::Abi {
+                    extern_token: syn::token::Extern::default(),
+                    name: Some(syn::LitStr::new("thiscall", proc_macro2::Span::call_site())),
+                });
+            }
+            return syn::Type::BareFn(normalized);
+        }
+    }
+    ty.clone()
+}
+
+/// Check if a type is `*const T` (as opposed to `*mut T`).
+fn is_const_ptr(ty: &syn::Type) -> bool {
+    if let syn::Type::Ptr(ptr) = ty {
+        ptr.const_token.is_some()
+    } else {
+        false
+    }
+}
+
+/// Parse the attribute arguments: `size = N, va = 0x..., class = "..."`.
+fn parse_vtable_attr_args(
+    attr: proc_macro2::TokenStream,
+    span: &syn::Ident,
+) -> syn::Result<(u32, Option<u32>, Option<String>)> {
+    // Parse as a comma-separated list of key = value pairs
+    struct VtableArgs {
+        size: Option<u32>,
+        va: Option<u32>,
+        class: Option<String>,
+    }
+
+    let mut args = VtableArgs {
+        size: None,
+        va: None,
+        class: None,
+    };
+
+    // Use syn's parser by wrapping in parens
+    let parser = syn::meta::parser(|meta| {
+        if meta.path.is_ident("size") {
+            let _eq: syn::Token![=] = meta.input.parse()?;
+            let lit: syn::LitInt = meta.input.parse()?;
+            args.size = Some(lit.base10_parse()?);
+        } else if meta.path.is_ident("va") {
+            let _eq: syn::Token![=] = meta.input.parse()?;
+            let lit: syn::LitInt = meta.input.parse()?;
+            args.va = Some(lit.base10_parse()?);
+        } else if meta.path.is_ident("class") {
+            let _eq: syn::Token![=] = meta.input.parse()?;
+            let lit: syn::LitStr = meta.input.parse()?;
+            args.class = Some(lit.value());
+        } else {
+            return Err(meta.error("unknown vtable attribute"));
+        }
+        Ok(())
+    });
+
+    syn::parse::Parser::parse2(parser, attr)?;
+
+    let size = args.size.ok_or_else(|| {
+        syn::Error::new_spanned(span, "vtable attribute requires `size = N`")
+    })?;
+
+    Ok((size, args.va, args.class))
+}
+
+/// Parse #[slot(N)] attribute from a field.
+fn parse_slot_attr(attrs: &[syn::Attribute], _span: &syn::Ident) -> syn::Result<Option<u32>> {
+    for attr in attrs {
+        if attr.path().is_ident("slot") {
+            let index: syn::LitInt = attr.parse_args()?;
+            return Ok(Some(index.base10_parse()?));
+        }
+    }
+    Ok(None)
+}
+
+/// Convert "PaletteVtable" or "Palette" to "PALETTE_VTABLE" or "PALETTE".
+fn to_screaming_snake(name: &str) -> String {
+    let mut result = String::new();
+    for (i, ch) in name.chars().enumerate() {
+        if ch.is_uppercase() && i > 0 {
+            // Don't insert underscore between consecutive uppercase (e.g., "DDGame" → "DD_GAME")
+            let prev = name.chars().nth(i - 1).unwrap_or('_');
+            if prev.is_lowercase() || prev.is_numeric() {
+                result.push('_');
+            } else if let Some(next) = name.chars().nth(i + 1) {
+                if next.is_lowercase() {
+                    result.push('_');
+                }
+            }
+        }
+        result.push(ch.to_ascii_uppercase());
+    }
+    result
+}
+
 /// Derive `HasFieldRegistry` for a `#[repr(C)]` struct.
 ///
 /// Generates a static `StructFields` table with one `FieldEntry` per named

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

@@ -368,7 +368,7 @@ unsafe extern "cdecl" fn impl_init_hardware(
         (*session).keyboard = kb;
 
         // ── Palette (inline construction) ─────────────────────────────────────
-        let pal = WABox::from_value(Palette::new(rb(va::PALETTE_VTABLE_MAYBE))).leak();
+        let pal = WABox::from_value(Palette::new(rb(va::PALETTE_VTABLE))).leak();
         (*session).palette = pal;
 
         // ── DSSound ───────────────────────────────────────────────────────────

docs/superpowers/specs/2026-03-25-vtable-derive-design.md

@@ -0,0 +1,337 @@
+# Design: `#[vtable(...)]` System for OpenWA
+
+## Context
+
+OpenWA has 7+ manually-written vtable structs (`PaletteVtable`, `DisplayBaseVtable`, `DDDisplayVtable`, etc.) with hand-coded `#[repr(C)]` layouts, manual `impl` wrapper methods, and ad-hoc vtable patching. The existing `#[derive(FieldRegistry)]` macro and `inventory`-based registry provide a proven pattern for auto-generating struct metadata. This design extends that infrastructure to vtables, providing a single definition per vtable that handles introspection, calling, and replacement.
+
+**Constraints:**
+- A C++ class can have multiple vtables at different struct offsets (multiple inheritance)
+- The same vtable type can theoretically serve multiple classes
+- All vtable methods are `unsafe extern "thiscall"` (ECX = this)
+- Target is i686-pc-windows-msvc (32-bit, 4-byte pointers/fn pointers)
+
+## Design
+
+### 1. Vtable Definition (`#[vtable(...)]`)
+
+**Input syntax** — declare only known methods with `#[slot(N)]`:
+
+```rust
+#[openwa_core::vtable(size = 5, va = 0x0066_A2E4, class = "Palette")]
+pub struct PaletteVtable {
+    /// set_mode(this, mode) — called with mode=7 during hardware init
+    #[slot(2)]
+    pub set_mode: unsafe extern "thiscall" fn(*mut Palette, u32),
+    /// init(this) — called during hardware init
+    #[slot(3)]
+    pub init: unsafe extern "thiscall" fn(*mut Palette),
+    /// reset(this) — called first during hardware init
+    #[slot(4)]
+    pub reset: unsafe extern "thiscall" fn(*mut Palette),
+}
+```
+
+**Generated output:**
+
+```rust
+// 1. The actual #[repr(C)] struct with gap-fillers
+#[repr(C)]
+pub struct PaletteVtable {
+    pub _slot_0: usize,
+    pub _slot_1: usize,
+    /// set_mode(this, mode) — called with mode=7 during hardware init
+    pub set_mode: unsafe extern "thiscall" fn(*mut Palette, u32),
+    /// init(this) — called during hardware init
+    pub init: unsafe extern "thiscall" fn(*mut Palette),
+    /// reset(this) — called first during hardware init
+    pub reset: unsafe extern "thiscall" fn(*mut Palette),
+}
+
+// 2. Registry integration (introspection)
+impl HasVtableRegistry for PaletteVtable {
+    fn vtable_info() -> &'static VtableInfo {
+        static INFO: VtableInfo = VtableInfo {
+            struct_name: "PaletteVtable",
+            class_name: "Palette",
+            ghidra_va: 0x0066_A2E4,
+            slot_count: 5,
+            slots: &[
+                VtableSlotEntry { index: 2, name: "set_mode", doc: "set_mode(this, mode) ..." },
+                VtableSlotEntry { index: 3, name: "init", doc: "init(this) ..." },
+                VtableSlotEntry { index: 4, name: "reset", doc: "reset(this) ..." },
+            ],
+        };
+        &INFO
+    }
+}
+
+inventory::submit!(VtableRegistration {
+    info: <PaletteVtable as HasVtableRegistry>::vtable_info(),
+});
+
+// 3. Address registry entry (replaces define_addresses! for this vtable)
+inventory::submit!(AddrEntry {
+    va: 0x0066_A2E4,
+    name: "PALETTE_VTABLE",
+    kind: AddrKind::Vtable,
+    class_name: Some("Palette"),
+    calling_convention: None,
+});
+
+// 4. Companion binding macro (see Part 2)
+#[macro_export]
+macro_rules! bind_PaletteVtable { ... }
+```
+
+**Proc macro implementation** in `openwa-derive/src/lib.rs`:
+- Parse `#[vtable(...)]` attributes for `size`, `va` (optional), `class` (optional)
+- Parse `#[slot(N)]` on each field to determine position
+- Validate: no duplicate slots, all slots < size, slot indices ascending
+- Generate gap-filler fields `_slot_N: usize` for missing indices
+- Preserve doc comments, visibility, and field types from input
+- Generate compile-time size assertion: `const _: () = assert!(size_of::<VtableName>() == size * 4);`
+- Parse fn pointer types to extract `this` type (`*mut T` or `*const T`), params, and return type
+- Generate `HasVtableRegistry` impl, inventory submissions, and binding macro
+- If `va` is provided: generate `pub const` and `AddrEntry` submission. Name derived from `class` attribute: `"Palette"` → `PALETTE_VTABLE`. If no `class`, derive from struct name: `PaletteVtable` → `PALETTE_VTABLE`
+- If `va` is omitted: no `AddrEntry`, no const — vtable exists purely as a type
+
+### 2. Calling Wrappers (`bind_XxxVtable!`)
+
+The derive generates a companion macro named `bind_{VtableName}!` that creates method wrappers:
+
+```rust
+// Generated by #[derive(Vtable)] on PaletteVtable:
+#[macro_export]
+macro_rules! bind_PaletteVtable {
+    ($class:ty, $vtable_field:ident) => {
+        impl $class {
+            #[doc = "set_mode(this, mode) — called with mode=7 during hardware init"]
+            pub unsafe fn set_mode(&mut self, mode: u32) {
+                ((*self.$vtable_field).set_mode)(self as *mut Self, mode)
+            }
+            #[doc = "init(this) — called during hardware init"]
+            pub unsafe fn init(&mut self) {
+                ((*self.$vtable_field).init)(self as *mut Self)
+            }
+            #[doc = "reset(this) — called first during hardware init"]
+            pub unsafe fn reset(&mut self) {
+                ((*self.$vtable_field).reset)(self as *mut Self)
+            }
+        }
+    };
+}
+```
+
+**Usage:**
+```rust
+// In palette.rs, after struct Palette { vtable: *const PaletteVtable, ... }
+bind_PaletteVtable!(Palette, vtable);
+
+// Now you can write:
+(*pal).set_mode(7);   // instead of vcall!(pal, set_mode, 7)
+(*pal).init();
+(*pal).reset();
+```
+
+**Multiple vtables (multiple inheritance):**
+```rust
+// CGameTask has primary vtable at +0x00
+bind_CGameTaskVtable!(CGameTask, vtable);
+
+// SoundEmitter is a sub-object with its own vtable — bind on its own struct
+bind_SoundEmitterVTable!(SoundEmitter, vtable);
+```
+
+**Method signature extraction:** The proc macro parses the fn pointer type as `syn::Type::BareFn` to extract:
+- First param is `this` — if `*const T`, generates `&self`; if `*mut T`, generates `&mut self`
+- Remaining params become the wrapper's named parameters (e.g., `p0: u32`, `p1: *mut u8`)
+- Return type is preserved (default `()` if absent)
+- The wrapper calls through `self.$vtable_field` and casts `self` to the correct pointer type
+
+**Type safety:** The binding macro passes `self as *mut Self` (or `*const Self`) as the `this` argument. The `$class` type passed to the macro must match the `this` pointer type in the vtable fn signatures. If mismatched, Rust's pointer cast rules apply silently — the macro does not enforce this, but the mismatch would be visible at the invocation site.
+
+**Note on `&mut self`:** This follows the existing hand-written pattern (e.g., `Palette::reset(&mut self)`). Using `&mut self` creates a mutable reference from what is often a raw pointer, which could theoretically violate aliasing rules. This is acceptable for this project since all callers are already in `unsafe` blocks working with raw game memory, and the `vcall!` macro remains available for raw-pointer-only dispatch.
+
+### 3. Vtable Replacement (`vtable_replace!`)
+
+A declarative macro that expands to executable code for use inside `install()` functions:
+
+```rust
+pub fn install() -> Result<(), String> {
+    unsafe {
+        vtable_replace!(PaletteVtable at va::PALETTE_VTABLE {
+            slot set_mode => my_set_mode,
+            slot init => my_init,
+        })?;
+    }
+    Ok(())
+}
+```
+
+**Expanded code** (for `slot 2 => my_set_mode` — pure replace, no original saved):
+
+```rust
+{
+    let vtable_ptr = $crate::rebase::rb(va::PALETTE_VTABLE) as *mut u32;
+    let slot_count = core::mem::size_of::<PaletteVtable>() / 4;
+    $crate::vtable::patch_vtable(vtable_ptr, slot_count, |vt| {
+        // Slot 2: pure replace
+        let slot = vt.add(2);
+        *slot = my_set_mode as *const () as u32;
+    })
+}
+```
+
+**Expanded code** (for `slot 3 [originals::INIT] => my_init` — replace + save original):
+
+```rust
+{
+    let vtable_ptr = $crate::rebase::rb(va::PALETTE_VTABLE) as *mut u32;
+    let slot_count = core::mem::size_of::<PaletteVtable>() / 4;
+    $crate::vtable::patch_vtable(vtable_ptr, slot_count, |vt| {
+        // Slot 3: save original, then replace
+        let slot = vt.add(3);
+        originals::INIT.store(*slot, core::sync::atomic::Ordering::Relaxed);
+        *slot = my_init as *const () as u32;
+    })
+}
+```
+
+**Calling the original:** User defines statics in a visible scope and passes them via `[static]` syntax:
+
+```rust
+mod originals {
+    pub static INIT: core::sync::atomic::AtomicU32 =
+        core::sync::atomic::AtomicU32::new(0);
+}
+
+vtable_replace!(PaletteVtable at va::PALETTE_VTABLE {
+    slot 2 => my_set_mode,                          // no original needed
+    slot 3 [originals::INIT] => my_init,            // save original
+})?;
+
+// In the replacement:
+unsafe extern "thiscall" fn my_init(this: *mut Palette) {
+    log!("init()");
+    let orig: unsafe extern "thiscall" fn(*mut Palette) =
+        core::mem::transmute(originals::INIT.load(Ordering::Relaxed));
+    orig(this);
+}
+```
+
+The `[static_name]` syntax is optional — if omitted, no original is saved (pure replacement, no call-through). The macro does NOT generate inaccessible statics.
+
+**Slot index resolution:** Slot indices are specified explicitly in the macro call. This is compile-time, simple, and the indices are directly visible in the vtable definition above.
+
+**Size derivation:** The `size` parameter is NOT required — the macro computes it as `size_of::<VtableType>() / 4` from the vtable struct type, which already encodes the correct size via `#[vtable(size = N)]`.
+
+Revised syntax:
+```rust
+vtable_replace!(PaletteVtable at va::PALETTE_VTABLE {
+    slot 2 => my_set_mode,                         // pure replace, original discarded
+    slot 3 [originals::INIT] => my_init,           // replace + save original to static
+})?;
+```
+
+### 4. New Types in `openwa-core::registry`
+
+```rust
+/// Metadata for a single vtable slot
+pub struct VtableSlotEntry {
+    pub index: u32,
+    pub name: &'static str,
+    pub doc: &'static str,
+}
+
+/// Metadata for a vtable struct
+pub struct VtableInfo {
+    pub struct_name: &'static str,
+    pub class_name: &'static str,
+    pub ghidra_va: u32,
+    pub slot_count: u32,
+    pub slots: &'static [VtableSlotEntry],
+}
+
+impl VtableInfo {
+    pub fn slot_by_name(&self, name: &str) -> Option<&VtableSlotEntry> { ... }
+    pub fn slot_by_index(&self, index: u32) -> Option<&VtableSlotEntry> { ... }
+}
+
+/// Trait implemented by #[derive(Vtable)] structs
+pub trait HasVtableRegistry {
+    fn vtable_info() -> &'static VtableInfo;
+}
+
+/// Inventory collection wrapper
+pub struct VtableRegistration {
+    pub info: &'static VtableInfo,
+}
+inventory::collect!(VtableRegistration);
+
+/// Query API
+pub fn vtable_info_for(struct_name: &str) -> Option<&'static VtableInfo> { ... }
+pub fn all_vtable_info() -> impl Iterator<Item = &'static VtableInfo> { ... }
+```
+
+### 5. `vtable::patch_vtable` Helper
+
+Move/generalize the existing vtable patching logic from `display.rs` into a shared utility:
+
+```rust
+// openwa-core::vtable (new module)
+
+/// Temporarily makes a vtable writable, calls the patcher, restores protection.
+/// Returns Err if VirtualProtect fails.
+pub unsafe fn patch_vtable(
+    vtable_ptr: *mut u32,
+    slot_count: usize,
+    patcher: impl FnOnce(*mut u32),
+) -> Result<(), String> {
+    let size = slot_count * 4;
+    let mut old_protect = 0u32;
+    if VirtualProtect(vtable_ptr as _, size, PAGE_READWRITE, &mut old_protect) == 0 {
+        return Err("VirtualProtect failed".into());
+    }
+    patcher(vtable_ptr);
+    VirtualProtect(vtable_ptr as _, size, old_protect, &mut old_protect);
+    Ok(())
+}
+```
+
+This already exists in `display.rs` — factor it out.
+
+## File Changes
+
+| File | Change |
+|------|--------|
+| `crates/openwa-derive/src/lib.rs` | Add `#[vtable(...)]` proc macro (~150 lines) |
+| `crates/openwa-core/src/registry.rs` | Add `VtableInfo`, `VtableSlotEntry`, `HasVtableRegistry`, `VtableRegistration`, query API (~60 lines) |
+| `crates/openwa-core/src/vtable.rs` | New module: `patch_vtable` helper (factored from display.rs) |
+| `crates/openwa-core/src/macros.rs` | Add `vtable_replace!` macro (~40 lines) |
+| `crates/openwa-core/src/lib.rs` | Add `pub mod vtable;`, re-export `Vtable` derive |
+
+## Migration: PaletteVtable (first target)
+
+1. Rewrite `PaletteVtable` in `display/palette.rs` to use `#[vtable(...)]`
+2. Add `bind_PaletteVtable!(Palette, vtable)` — replaces 3 manual wrapper methods
+3. Remove the `define_addresses!` entry for `PALETTE_VTABLE_MAYBE` (now in derive attribute)
+4. Verify `vcall!(pal, set_mode, 7)` still works (struct layout identical)
+5. Run replay tests
+
+## Migration Order (after Palette)
+
+1. `InputCtrlVtable` (1 slot) — trivial
+2. `MapViewVtable` (2 slots) — trivial
+3. `SoundEmitterVTable` (12 slots, 5 known)
+4. `DisplayBaseVtable` (32 slots, all typed)
+5. `DSSoundVtable` (24 slots)
+6. `DDDisplayVtable` (38 slots)
+7. `CTaskWormVTable` (20+ slots)
+
+## Verification
+
+- `cargo build -p openwa-core` — types compile
+- `cargo test -p openwa-core` — existing tests pass
+- `cargo build -p openwa-wormkit --release` — DLL builds
+- `.\run-tests.ps1` — replay tests pass (no desync from layout changes)
+- Validate introspection: `vtable_info_for("PaletteVtable")` returns correct slot metadata