feat: port DisplayGfx::LoadSprite (slot 31) and improve Sprite struct

- Port load_sprite vtable method: Rust validation/bookkeeping with
ConstructSprite in pure Rust, delegating VFS loading to WA bridge
- Embed DisplayBitGrid as a proper struct field in Sprite instead of
raw _unknown_38 bytes, with offset assertions
- Type Sprite::context_ptr as *mut SpriteCache instead of *mut u8
- Add construct_sprite() in openwa-core (pure Rust port of 0x4FAA30)
- Update ConstructSprite hook in DLL to use typed bitgrid fields
- Re-export SpriteVtable from sprite module
- Add address constants for sprite loading helper functions

DisplayGfx now at 27/34 non-stub vtable slots ported.

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

crates/openwa-core/src/address.rs

@@ -92,8 +92,9 @@ pub mod va {
     };
     pub use crate::render::sprite::sprite::SPRITE_BANK_VTABLE;
     pub use crate::render::sprite::sprite::{
-        CONSTRUCT_SPRITE, DESTROY_SPRITE, LOAD_SPRITE_FROM_VFS, PROCESS_SPRITE,
-        SPRITE_BANK_GET_INFO, SPRITE_GET_INFO, SPRITE_VTABLE,
+        CONSTRUCT_SPRITE, DESTROY_SPRITE, FREE_SPRITE_OBJECT, LOAD_SPRITE_BY_NAME,
+        LOAD_SPRITE_FROM_VFS, PROCESS_SPRITE, SPRITE_BANK_GET_INFO, SPRITE_BANK_INIT,
+        SPRITE_COMPLEX_BANK_PATH, SPRITE_COMPLEX_SPRITE_PATH, SPRITE_GET_INFO, SPRITE_VTABLE,
     };
 
     crate::define_addresses! {

crates/openwa-core/src/render/display/vtable.rs

@@ -1,5 +1,7 @@
 use crate::fixed::Fixed;
 use crate::render::display::line_draw::Vertex;
+use crate::render::SpriteCache;
+use crate::wa_alloc::wa_malloc_struct_zeroed;
 
 /// DisplayVtable — vtable for the display/rendering subsystem (DisplayGfx).
 ///
@@ -306,7 +308,7 @@ use super::gfx::DisplayGfx;
 use super::line_draw;
 use crate::bitgrid::DisplayBitGrid;
 use crate::render::palette::PaletteContext;
-use crate::render::sprite::{Sprite, SpriteBank};
+use crate::render::sprite::{Sprite, SpriteBank, SpriteVtable};
 
 /// Port of DisplayGfx::GetDimensions (vtable slot 1, 0x56A460).
 ///
@@ -807,8 +809,7 @@ pub unsafe extern "thiscall" fn draw_polyline(
 /// # Safety
 /// `this` must be a valid `*mut DisplayGfx`.
 pub unsafe extern "thiscall" fn is_sprite_loaded(this: *mut DisplayGfx, id: i32) -> u32 {
-    let id_u = id as u32;
-    if id_u.wrapping_sub(1) >= 0x3FF {
+    if !is_valid_sprite_id(id) {
         return 0;
     }
 
@@ -823,6 +824,18 @@ pub unsafe extern "thiscall" fn is_sprite_loaded(this: *mut DisplayGfx, id: i32)
     }
 }
 
+/// Check if a sprite ID is in the valid range [1, 0x3FF].
+#[inline]
+fn is_valid_sprite_id(id: i32) -> bool {
+    (1..=0x3FF).contains(&id)
+}
+
+/// Check if a layer ID is in the valid range [1, 3].
+#[inline]
+fn is_valid_layer(layer: u32) -> bool {
+    (1..=3).contains(&layer)
+}
+
 /// Port of DisplayGfx::GetSpriteInfo (vtable slot 6, 0x523500).
 ///
 /// Looks up sprite metadata for `layer` (valid: 1..=0x3FF). Checks
@@ -1538,3 +1551,181 @@ pub unsafe extern "thiscall" fn set_layer_visibility(
         (*this).base.layer_visibility[layer as usize] = 0;
     }
 }
+
+// =========================================================================
+// Sprite loading methods
+// =========================================================================
+
+/// Construct a Sprite in-place — pure Rust port of ConstructSprite (0x4FAA30).
+///
+/// Sets vtable, embedded BitGrid sub-object, and context pointer.
+/// All other fields are expected to be zeroed by the caller's allocation.
+///
+/// # Safety
+/// `sprite` must point to a zeroed `Sprite`-sized allocation.
+pub unsafe fn construct_sprite(sprite: *mut Sprite, sprite_cache: *mut SpriteCache) {
+    use crate::bitgrid::{BitGridDisplayVtable, BIT_GRID_DISPLAY_VTABLE};
+    use crate::rebase::rb;
+
+    (*sprite).vtable = rb(va::SPRITE_VTABLE) as *const SpriteVtable;
+    (*sprite).context_ptr = sprite_cache;
+
+    // Initialize embedded DisplayBitGrid sub-object
+    (*sprite).bitgrid.vtable = rb(BIT_GRID_DISPLAY_VTABLE) as *const BitGridDisplayVtable;
+    (*sprite).bitgrid.external_buffer = 1; // sprite doesn't own pixel data
+    (*sprite).bitgrid.cells_per_unit = 8; // 8bpp pixel buffer
+}
+
+/// Port of DisplayGfx::LoadSprite (vtable slot 31, 0x523400).
+///
+/// Loads a Sprite from VFS into the sprite table. Allocates a Sprite object,
+/// constructs it, and loads data via LoadSpriteFromVfs. On success, stores
+/// in sprite_ptrs[id] and updates layer metadata.
+///
+/// The `flag` parameter controls max_frames clamping on the loaded sprite.
+///
+/// # Safety
+/// `this` must be a valid `*mut DisplayGfx`.
+/// `load_sprite_from_vfs` must be a valid function pointer to 0x4FAAF0.
+pub unsafe fn load_sprite(
+    this: *mut DisplayGfx,
+    layer: u32,
+    id: u32,
+    flag: u32,
+    _gfx: *mut u8,
+    _name: *const core::ffi::c_char,
+    load_sprite_from_vfs: unsafe extern "cdecl" fn(
+        sprite: *mut Sprite,
+        gfx: *mut u8,
+        name: *const core::ffi::c_char,
+        layer_ctx: u32,
+    ) -> i32,
+) -> i32 {
+    // Bit 23 set = already loaded sentinel
+    if id & 0x80_0000 != 0 {
+        return 1;
+    }
+
+    if !is_valid_layer(layer) {
+        return 0;
+    }
+    let base = &mut (*this).base;
+    if base.layer_contexts[layer as usize] == 0 {
+        return 0;
+    }
+    if !is_valid_sprite_id(id as i32) {
+        return 0;
+    }
+
+    // Already loaded?
+    if is_sprite_loaded(this, id as i32) != 0 {
+        return 0;
+    }
+
+    let sprite = wa_malloc_struct_zeroed::<Sprite>();
+    if sprite.is_null() {
+        return 0;
+    }
+    construct_sprite(sprite, base.sprite_cache);
+
+    // Load from VFS
+    let layer_ctx = base.layer_contexts[layer as usize];
+    let result = load_sprite_from_vfs(sprite, _gfx, _name, layer_ctx);
+    if result == 0 {
+        // Load failed — destroy sprite via vtable[0]
+        if !sprite.is_null() {
+            let dtor = (*(*sprite).vtable).destructor;
+            dtor(sprite, 1);
+        }
+        return 0;
+    }
+
+    // Store in sprite table
+    let base = &mut (*this).base;
+    base.sprite_ptrs[id as usize] = sprite;
+    base.sprite_layers[id as usize] = layer;
+    base.layer_visibility[layer as usize] += 1;
+
+    // Update max_frames on the sprite if flag is set
+    if flag != 0 {
+        let sprite = base.sprite_ptrs[id as usize];
+        let id_u16 = id as u16;
+        if id_u16 != 0 && id_u16 < (*sprite).max_frames {
+            (*sprite).max_frames = id_u16;
+        }
+        (*sprite)._unknown_18 = (id >> 16) as u16;
+    }
+
+    1
+}
+
+/// Port of DisplayGfx::LoadSpriteByLayer (vtable slot 37, 0x56A4C0).
+///
+/// Simplified sprite loading that stores into DisplayGfx::sprite_table
+/// (offset 0x3DD4) instead of DisplayBase::sprite_ptrs. Allocates a raw
+/// 0x70-byte object, partially initializes it (NOT via ConstructSprite),
+/// then loads via FUN_005733b0.
+///
+/// # Safety
+/// `this` must be a valid `*mut DisplayGfx`.
+/// `load_fn` must be a valid function pointer to FUN_005733b0.
+/// `free_fn` must be a valid function pointer to FUN_0056a2f0.
+pub unsafe fn load_sprite_by_layer(
+    this: *mut DisplayGfx,
+    layer: u32,
+    id: u32,
+    gfx: *mut u8,
+    name: *const core::ffi::c_char,
+    load_fn: unsafe extern "cdecl" fn(
+        sprite: *mut u8,
+        gfx: *mut u8,
+        id: u32,
+        name: *const core::ffi::c_char,
+    ) -> i32,
+    free_fn: unsafe extern "cdecl" fn(sprite: *mut u8),
+) -> i32 {
+    // Bit 23 set = already loaded sentinel
+    if id & 0x80_0000 != 0 {
+        return 1;
+    }
+
+    // Call set_active_layer (vtable slot 5) — already ported Rust
+    set_active_layer(this, layer as i32);
+
+    if !is_valid_sprite_id(id as i32) {
+        return 0;
+    }
+
+    // Already loaded?
+    if is_sprite_loaded(this, id as i32) != 0 {
+        return 1;
+    }
+
+    // Allocate 0x70 bytes + 0x20 guard (matching WA_MallocMemset behavior)
+    use crate::wa_alloc::wa_malloc_zeroed;
+    let sprite = wa_malloc_zeroed(0x90);
+    if sprite.is_null() {
+        return 0;
+    }
+
+    // Partial init (NOT ConstructSprite — different from load_sprite)
+    *(sprite.add(0x58) as *mut *mut DisplayGfx) = this;
+    *(sprite.add(0x66) as *mut u16) = 0;
+    *(sprite.add(0x6C) as *mut u32) = 0;
+    *(sprite.add(0x54) as *mut u32) = 0;
+
+    // Load via FUN_005733b0
+    let result = load_fn(sprite, gfx, id, name);
+    if result == 0 {
+        free_fn(sprite);
+        return 0;
+    }
+
+    // Store in sprite_table (DisplayGfx offset 0x3DD4)
+    (*this).sprite_table[id as usize] = sprite as u32;
+    1
+}
+
+// LoadSpriteComplex (vtable slot 33, 0x5237C0) is NOT ported — the internal
+// dispatch functions (0x4FAD30, 0x4F9710) use ESI for sprite/bank pointers
+// in complex usercall conventions that are impractical to bridge.

crates/openwa-core/src/render/sprite/mod.rs

@@ -4,4 +4,4 @@ pub mod sprite;
 pub mod sprite_id;
 
 pub use spr::{ParsedSprite, SprError, SprHeader};
-pub use sprite::{Sprite, SpriteBank, SpriteFrame, SpriteId};
+pub use sprite::{Sprite, SpriteBank, SpriteFrame, SpriteId, SpriteVtable};

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

@@ -1,3 +1,5 @@
+use crate::render::SpriteCache;
+
 // Re-export SpriteId from its own module to keep this file focused on struct layouts.
 pub use super::sprite_id::SpriteId;
 
@@ -39,7 +41,7 @@ pub struct Sprite {
     /// 0x00: Vtable pointer (0x66418C, 8 slots)
     pub vtable: *const SpriteVtable,
     /// 0x04: Context/parent pointer (ECX from ConstructSprite)
-    pub context_ptr: *mut u8,
+    pub context_ptr: *mut SpriteCache,
     /// 0x08: Unknown
     pub _unknown_08: u16,
     /// 0x0A: Animation frames per second
@@ -74,11 +76,10 @@ pub struct Sprite {
     pub secondary_frame_count: u16,
     /// 0x32: Padding
     pub _pad_32: u16,
-    /// 0x34: Embedded BitGrid vtable pointer (0x664144, set by ConstructSprite).
-    /// Part of a BitGrid sub-object within the Sprite.
-    pub bitgrid_vtable: *mut u8,
-    /// 0x38-0x5F: Unknown fields
-    pub _unknown_38: [u8; 0x28],
+    /// 0x34: Embedded DisplayBitGrid sub-object (0x2C bytes).
+    /// ConstructSprite sets vtable=0x664144, external_buffer=1, cells_per_unit=8.
+    /// Populated further by ProcessSprite with pixel data pointers.
+    pub bitgrid: crate::bitgrid::DisplayBitGrid,
     /// 0x60: Pointer to raw frame header data
     pub raw_frame_header_ptr: *mut u8,
     /// 0x64: Pointer to bitmap pixel data
@@ -90,6 +91,8 @@ pub struct Sprite {
 }
 
 const _: () = assert!(core::mem::size_of::<Sprite>() == 0x70);
+const _: () = assert!(core::mem::offset_of!(Sprite, bitgrid) == 0x34);
+const _: () = assert!(core::mem::offset_of!(Sprite, raw_frame_header_ptr) == 0x60);
 
 /// SpriteBank — indexed sprite container (0x17C bytes).
 ///
@@ -194,5 +197,18 @@ crate::define_addresses! {
     class "SpriteBank" {
         /// SpriteBank__GetInfo — usercall EAX=layer, ECX=bank*, ESI=out_width, 2 stack params
         fn/Usercall SPRITE_BANK_GET_INFO = 0x004F_98C0;
+        /// SpriteBank__Init — usercall, initializes from VFS resource
+        fn/Usercall SPRITE_BANK_INIT = 0x004F_95A0;
+    }
+
+    class "DisplayGfx_Sprite" {
+        /// Load sprite from VFS by name — usercall(EDI=sprite, ECX=gfx) + stack(id, name), RET 0x8
+        fn/Usercall LOAD_SPRITE_BY_NAME = 0x0057_33B0;
+        /// Free sprite object (with sub-object cleanup) — usercall(EDI=sprite), plain RET
+        fn/Usercall FREE_SPRITE_OBJECT = 0x0056_A2F0;
+        /// Sprite-path dispatch for LoadSpriteComplex — usercall on Sprite*
+        fn/Usercall SPRITE_COMPLEX_SPRITE_PATH = 0x004F_AD30;
+        /// SpriteBank-path dispatch for LoadSpriteComplex — usercall on SpriteBank*
+        fn/Usercall SPRITE_COMPLEX_BANK_PATH = 0x004F_9710;
     }
 }

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

@@ -1559,6 +1559,59 @@ unsafe extern "cdecl" fn wa_font_draw_text(
     );
 }
 
+// =========================================================================
+// Sprite loading vtable method wrappers
+// =========================================================================
+
+/// Thiscall wrapper for DisplayGfx::LoadSprite (vtable slot 31, 0x523400).
+unsafe extern "thiscall" fn load_sprite(
+    this: *mut DisplayGfx,
+    layer: u32,
+    id: u32,
+    flag: u32,
+    gfx: *mut u8,
+    name: *const core::ffi::c_char,
+) -> i32 {
+    display_vtable::load_sprite(this, layer, id, flag, gfx, name, wa_load_sprite_from_vfs)
+}
+
+/// Bridge to LoadSpriteFromVfs (0x4FAAF0).
+/// Usercall: ECX=gfx, EAX=name, stack(sprite, layer_ctx), RET 0x8.
+///
+/// Verified from caller at 0x523489:
+///   ECX ← layer_contexts[layer] (gfx/VFS context)... wait, re-checked:
+///   ECX ← gfx param, EAX ← name param.
+///   Stack: sprite (EDI from ConstructSprite), layer_ctx.
+#[unsafe(naked)]
+unsafe extern "cdecl" fn wa_load_sprite_from_vfs(
+    _sprite: *mut openwa_core::render::sprite::Sprite,
+    _gfx: *mut u8,
+    _name: *const core::ffi::c_char,
+    _layer_ctx: u32,
+) -> i32 {
+    core::arch::naked_asm!(
+        // cdecl: +4=sprite, +8=gfx, +12=name, +16=layer_ctx
+        "mov ecx, [esp+8]",         // gfx → ECX
+        "mov eax, [esp+12]",        // name → EAX
+        "push dword ptr [esp+16]",  // layer_ctx
+        "push dword ptr [esp+8]",   // sprite (shifted +4 by push)
+        "call [{ADDR}]",            // RET 0x8 cleans 2 stack params
+        "ret",
+        ADDR = sym LOAD_SPRITE_FROM_VFS_ADDR,
+    );
+}
+
+static mut LOAD_SPRITE_FROM_VFS_ADDR: u32 = 0;
+
+// LoadSpriteByLayer (vtable slot 37, 0x56A4C0) is NOT ported — the internal
+// loader FUN_005733b0 is a 379-instruction DirectDraw surface creator with
+// complex usercall conventions and caller-frame reads. Left as original WA code.
+
+// LoadSpriteComplex (slot 33) and LoadSpriteByLayer (slot 37) are NOT ported —
+// their internal functions (FUN_005733b0, FUN_004FAD30, FUN_004F9710) have
+// complex usercall conventions with caller-frame reads and DirectDraw surface
+// creation. Left as original WA code.
+
 // ---------------------------------------------------------------------------
 // Display installation
 // ---------------------------------------------------------------------------
@@ -1594,6 +1647,9 @@ fn install_display() -> Result<(), String> {
             let _ = log_line("[Display]   Headless: patched slot 0 (destructor) -> Rust");
         })?;
 
+        // Initialize bridge address statics for sprite loading
+        LOAD_SPRITE_FROM_VFS_ADDR = rb(va::LOAD_SPRITE_FROM_VFS);
+
         // Patch DisplayGfx vtable (0x66A218): replace ported methods with Rust.
         vtable_replace!(DisplayVtable, va::DISPLAY_GFX_VTABLE, {
             get_dimensions      => display_vtable::get_dimensions,
@@ -1617,13 +1673,14 @@ fn install_display() -> Result<(), String> {
             set_camera_offset   => display_vtable::set_camera_offset,
             set_clip_rect       => display_vtable::set_clip_rect,
             is_sprite_loaded    => display_vtable::is_sprite_loaded,
+            load_sprite          => load_sprite,
             draw_scaled_sprite  => draw_scaled_sprite,
             set_layer_visibility => display_vtable::set_layer_visibility,
             update_palette      => display_vtable::update_palette,
             set_font_palette    => set_font_palette,
             slot 19 => blit_sprite,
         })?;
-        let _ = log_line("[Display]   DisplayGfx: patched 26 methods -> Rust");
+        let _ = log_line("[Display]   DisplayGfx: patched 28 methods -> Rust");
     }
 
     Ok(())

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

@@ -7,8 +7,8 @@
 use openwa_core::address::va;
 use openwa_core::rebase::rb;
 use openwa_core::render::palette::PaletteContext;
-use openwa_core::render::sprite::sprite::SpriteVtable;
 use openwa_core::render::sprite::{Sprite, SpriteFrame};
+use openwa_core::render::SpriteCache;
 
 use crate::hook::{self, usercall_trampoline};
 
@@ -19,18 +19,19 @@ use crate::hook::{self, usercall_trampoline};
 usercall_trampoline!(fn trampoline_construct_sprite; impl_fn = construct_sprite_impl;
     regs = [eax, ecx]);
 
-unsafe extern "cdecl" fn construct_sprite_impl(sprite: *mut Sprite, context: *mut u8) {
-    // Zero the entire 0x70-byte struct first
+unsafe extern "cdecl" fn construct_sprite_impl(sprite: *mut Sprite, context: *mut SpriteCache) {
+    use openwa_core::bitgrid::{BitGridDisplayVtable, BIT_GRID_DISPLAY_VTABLE};
+    use openwa_core::render::sprite::SpriteVtable;
+
     core::ptr::write_bytes(sprite as *mut u8, 0, core::mem::size_of::<Sprite>());
 
     (*sprite).vtable = rb(va::SPRITE_VTABLE) as *const SpriteVtable;
     (*sprite).context_ptr = context;
-    (*sprite).bitgrid_vtable = rb(va::BIT_GRID_DISPLAY_VTABLE) as *mut u8;
 
-    // BitGrid sub-object fields (within _unknown_38)
-    let p = sprite as *mut u8;
-    *(p.add(0x38) as *mut u32) = 1;
-    *(p.add(0x40) as *mut u32) = 8;
+    // Embedded DisplayBitGrid sub-object at +0x34
+    (*sprite).bitgrid.vtable = rb(BIT_GRID_DISPLAY_VTABLE) as *const BitGridDisplayVtable;
+    (*sprite).bitgrid.external_buffer = 1;
+    (*sprite).bitgrid.cells_per_unit = 8;
 }
 
 // ---------------------------------------------------------------------------