refactor: rename mis-labeled DisplayGfx slot 33 to GetSpriteFrameForBlit

Slot 33 (0x5237C0) was historically called LoadSpriteComplex everywhere —
in the vtable definition, the address registry, the inner-helper names
(SPRITE_COMPLEX_SPRITE_PATH / SPRITE_COMPLEX_BANK_PATH), the doc strings
on SpriteBank/DisplayBase, and the "NOT ported because complex usercall"
rationale. It is not a load function. It's the per-blit frame lookup that
BlitSprite (slot 19) calls on every sprite render: clamps an animation
value, finds the matching frame entry in the sprite's frame table,
lazily decompresses the frame surface, and returns *DisplayBitGrid +
bounding box.

Cascade renames:

vtable slot load_sprite_complex → get_sprite_frame_for_blit
Ghidra fn LoadSpriteComplex → DisplayGfx__GetSpriteFrameForBlit
Ghidra fn FUN_004FAD30 (alias → Sprite__GetFrameForBlit
SPRITE_COMPLEX_SPRITE_PATH)
Ghidra fn FUN_004F9710 (alias → SpriteBank__GetFrameForBlit
SPRITE_COMPLEX_BANK_PATH)

Replace render.rs's raw `vtable_ptr.add(33)` transmute in `blit_sprite`
with the typed `DisplayGfx::get_sprite_frame_for_blit_raw(...)` wrapper
generated by the #[vtable] macro — much harder to mis-call now that the
slot has a real signature instead of nine `u32` placeholders. Also fix
the cascading "load complex" wording in SpriteBank/DisplayBase docs and
the Ghidra plate comments on all three renamed functions.

All 15 headless replay tests pass.

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

crates/openwa-core/src/address.rs

@@ -93,8 +93,8 @@ pub mod va {
     pub use crate::render::sprite::sprite::SPRITE_BANK_VTABLE;
     pub use crate::render::sprite::sprite::{
         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,
+        LOAD_SPRITE_FROM_VFS, PROCESS_SPRITE, SPRITE_BANK_GET_FRAME_FOR_BLIT, SPRITE_BANK_GET_INFO,
+        SPRITE_BANK_INIT, SPRITE_GET_FRAME_FOR_BLIT, SPRITE_GET_INFO, SPRITE_VTABLE,
     };
 
     crate::define_addresses! {

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

@@ -41,7 +41,8 @@ pub struct DisplayBase<V: Vtable = *const DisplayBaseVtable> {
     // Points to Sprite objects (0x70 bytes, vtable 0x66418C). Checked by IsSpriteLoaded/GetSpriteInfo.
     pub sprite_ptrs: [*mut Sprite; 0x400],
     // +0x2008..0x3008: per-slot SpriteBank* pointers (0x400 entries), zeroed by ctor.
-    // Points to SpriteBank objects (0x17C bytes). Fallback path in GetSpriteInfo/LoadSpriteComplex.
+    // Points to SpriteBank objects (0x17C bytes). Fallback path in
+    // GetSpriteInfo and GetSpriteFrameForBlit (vtable slot 33).
     pub sprite_banks: [*mut SpriteBank; 0x400],
     // +0x3008..0x3018: gap (0x10 bytes, 4 u32s: indices 0xC02..0xC05)
     pub _gap_3008: [u32; 4],

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

@@ -274,22 +274,49 @@ pub struct DisplayVtable {
     /// Returns 1 if the sprite exists in any of the three sprite arrays.
     #[slot(32)]
     pub is_sprite_loaded: fn(this: *mut DisplayGfx, id: i32) -> u32,
-    /// load sprite with complex params (0x5237C0, RET 0x24)
+    /// look up a sprite frame's surface and metadata for blitting
+    /// (0x5237C0, RET 0x24) — `DisplayGfx::GetSpriteFrameForBlit`.
     ///
-    /// 9 stack params. Dual-path loading depending on layer type.
+    /// **Not a "load" function** despite the historic mis-name. Called every
+    /// frame from `BlitSprite` (slot 19) to resolve a sprite ID + animation
+    /// value into a renderable frame: clamps the animation value, looks up
+    /// the matching frame entry in the sprite's frame table, lazily
+    /// decompresses the frame's surface via `FUN_004FA950`, and returns
+    /// the surface pointer plus the frame's bounding box.
+    ///
+    /// Dispatches via the two arrays at `DisplayGfx + 0x1008` (Sprite*)
+    /// and `DisplayGfx + 0x2008` (SpriteBank*) — both lookups go through
+    /// the same outputs:
+    ///
+    /// | Output                         | Meaning                                          |
+    /// |--------------------------------|--------------------------------------------------|
+    /// | return value                   | `*mut DisplayBitGrid` — decompressed frame surface |
+    /// | `out_w`, `out_h`               | full sprite cell width / height (for centering)  |
+    /// | `out_left`/`top`/`right`/`bot` | frame bounding box within the cell               |
+    /// | `out_anim_frac`                | sub-frame interpolation value (Fixed16) or 0     |
+    ///
+    /// `Sprite*` path → `Sprite__GetFrameForBlit` (FUN_004FAD30, ESI=sprite).
+    /// `SpriteBank*` path → `SpriteBank__GetFrameForBlit` (FUN_004F9710,
+    /// ESI=bank). Both inner helpers use ESI for the receiver in a complex
+    /// usercall convention, which is why this slot has not been ported yet —
+    /// it would require porting the FrameCache and the surface decompression
+    /// helper (`FUN_004FA950` / `FUN_005B29E0`) first.
+    ///
+    /// `BlitSprite` calls this directly via `vtable[33]` today; see
+    /// `replacements/render.rs::blit_sprite`.
     #[slot(33)]
-    pub load_sprite_complex: fn(
+    pub get_sprite_frame_for_blit: fn(
         this: *mut DisplayGfx,
-        layer: i32,
-        p3: u32,
-        p4: u32,
-        p5: u32,
-        p6: u32,
-        p7: u32,
-        p8: u32,
-        p9: u32,
-        p10: u32,
-    ) -> u32,
+        sprite_id: u32,
+        anim_value: u32,
+        out_w: *mut i32,
+        out_h: *mut i32,
+        out_left: *mut i32,
+        out_top: *mut i32,
+        out_right: *mut i32,
+        out_bottom: *mut i32,
+        out_anim_frac: *mut u32,
+    ) -> *mut DisplayBitGrid,
     /// load .fnt bitmap font into a font slot (0x523560, RET 0x10)
     #[slot(34)]
     pub load_font: fn(
@@ -2047,9 +2074,13 @@ pub unsafe fn load_sprite_by_layer(
     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.
+// GetSpriteFrameForBlit (vtable slot 33, 0x5237C0) is NOT ported — it is
+// hot-path though, called from our own `blit_sprite` (slot 19) on every
+// sprite render via the raw vtable pointer. The two inner helpers
+// (Sprite__GetFrameForBlit at 0x4FAD30, SpriteBank__GetFrameForBlit at
+// 0x4F9710) use ESI for the sprite/bank receiver in a usercall convention
+// that's impractical to bridge directly. Porting requires first porting
+// the FrameCache + decompression chain (FUN_004FA950 → FUN_005B29E0).
 
 // =========================================================================
 // Font loading

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

@@ -104,8 +104,8 @@ const _: () = assert!(core::mem::offset_of!(Sprite, raw_frame_header_ptr) == 0x6
 /// Created by LoadSpriteEx (0x523310): allocated 0x17C bytes, first 0x15C zeroed,
 /// then constructed and initialized via FUN_004f95a0.
 ///
-/// Used by GetSpriteInfo (0x523500) and LoadSpriteComplex (0x5237C0) as the
-/// fallback path when sprite_ptrs[id] is null.
+/// Used by GetSpriteInfo (0x523500) and GetSpriteFrameForBlit (0x5237C0,
+/// vtable slot 33) as the fallback path when sprite_ptrs[id] is null.
 #[repr(C)]
 pub struct SpriteBank {
     /// 0x00: Vtable pointer (0x664180, 3 slots)
@@ -266,9 +266,13 @@ crate::define_addresses! {
         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;
+        /// `Sprite__GetFrameForBlit` — usercall on Sprite* (ESI=sprite).
+        /// Looks up an animation frame in a Sprite, lazily decompresses its
+        /// surface, and returns the frame metadata. Called by
+        /// `DisplayGfx::GetSpriteFrameForBlit` (slot 33) for sprite_ptrs IDs.
+        fn/Usercall SPRITE_GET_FRAME_FOR_BLIT = 0x004F_AD30;
+        /// `SpriteBank__GetFrameForBlit` — usercall on SpriteBank* (ESI=bank).
+        /// Same as above but for SpriteBank-backed sprite IDs (sprite_banks).
+        fn/Usercall SPRITE_BANK_GET_FRAME_FOR_BLIT = 0x004F_9710;
     }
 }

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

@@ -756,7 +756,6 @@ unsafe extern "thiscall" fn blit_sprite(
     sprite_flags: u32,
     palette: u32,
 ) {
-    use openwa_core::bitgrid::DisplayBitGrid;
     use openwa_core::render::display::gfx::DisplayGfx;
     use openwa_core::render::display::vtable as display_vtable;
 
@@ -891,43 +890,21 @@ unsafe extern "thiscall" fn blit_sprite(
     }
 
     // ---------------------------------------------------------------
-    // Sprite data lookup via vtable[33]
+    // Sprite frame lookup via DisplayGfx::GetSpriteFrameForBlit (slot 33).
     // ---------------------------------------------------------------
-    let vtable_ptr = *(this as *const *const u32);
-    let slot33_addr = *vtable_ptr.add(33);
-
-    // vtable[33] is thiscall with 9 stack params (RET 0x24).
-    // Output semantics (traced from ASM ESP offsets through LEA/PUSH sequence):
-    //   param 3 -> sprite full width (for centering)
-    //   param 4 -> sprite full height (for centering)
-    //   param 5 -> render rect LEFT
-    //   param 6 -> render rect TOP (overwrites palette on original stack!)
-    //   param 7 -> render rect RIGHT
-    //   param 8 -> render rect BOTTOM
-    //   param 9 -> unknown (unused)
+    // Resolves the sprite ID + animation value into the actual decompressed
+    // frame surface plus its bounding box and full sprite-cell dimensions
+    // (used below for centering and clipped blits).
     let mut out_sprite_w: i32 = 0;
     let mut out_sprite_h: i32 = 0;
     let mut out_rect_left: i32 = 0;
     let mut out_rect_top: i32 = 0;
     let mut out_rect_right: i32 = 0;
     let mut out_rect_bottom: i32 = 0;
-    let mut out_unknown: u32 = 0;
-
-    let fn33: unsafe extern "thiscall" fn(
-        *mut DisplayGfx,
-        u32,
-        u32,
-        *mut i32,
-        *mut i32,
-        *mut i32,
-        *mut i32,
-        *mut i32,
-        *mut i32,
-        *mut u32,
-    ) -> *mut DisplayBitGrid = core::mem::transmute(slot33_addr as usize);
-
-    let mut sprite_surface = fn33(
-        this,
+    let mut out_anim_frac: u32 = 0;
+
+    let mut sprite_surface = DisplayGfx::get_sprite_frame_for_blit_raw(
+        gfx,
         sprite_id,
         pal,
         &mut out_sprite_w,
@@ -936,7 +913,7 @@ unsafe extern "thiscall" fn blit_sprite(
         &mut out_rect_top,
         &mut out_rect_right,
         &mut out_rect_bottom,
-        &mut out_unknown,
+        &mut out_anim_frac,
     );
 
     if sprite_surface.is_null() {
@@ -1474,9 +1451,10 @@ unsafe extern "cdecl" fn wa_load_sprite_from_vfs(
 
 static mut LOAD_SPRITE_FROM_VFS_ADDR: u32 = 0;
 
-// LoadSpriteComplex (slot 33) is NOT ported — its internal functions
-// (0x4FAD30, 0x4F9710) use ESI for sprite/bank pointers in complex
-// usercall conventions that are impractical to bridge.
+// GetSpriteFrameForBlit (slot 33) is NOT ported — see the docstring on
+// `DisplayVtable::get_sprite_frame_for_blit` in openwa-core for the full
+// rationale. Our `blit_sprite` (slot 19) above calls it via the bound
+// vtable wrapper on every sprite render.
 
 unsafe extern "thiscall" fn load_sprite_by_layer(
     this: *mut DisplayGfx,