feat: port slot 19 bitmap-sprite path to pure Rust

The slot-19 (BlitSprite) bitmap-sprite branch was the last in-game
caller of three usercall bridges to WA: GetBitmapSpriteInfo (0x573C50),
BlitBitmapClipped (0x56A700), and BlitBitmapTiled (0x56A7D0). After
this change, the only remaining in-game render bridge is slot 33
(GetSpriteFrameForBlit).

Type cleanups (lessons 14, 18: small typing wins are always welcome):

- LayerSprite renames `field_64`/`field_68`/`field_6a` to `flags`,
`cell_width: i16`, and `cell_height: i16`. Field semantics verified
against the GetBitmapSpriteInfo disassembly's reads of [EAX+0x64..0x6A].
- DisplayGfx::sprite_table retyped from `[u32; 0x400]` to
`[*mut LayerSprite; 0x400]`. Each non-null entry is the bitmap-sprite
object allocated by `load_sprite_by_layer` (slot 37).
- LayerSpriteFrame::bitmap_ptr() helper returns the trailing 12-byte
CBitmap block as `*mut CBitmap`. Lets us avoid duplicating the
vtable+surface+pad triple as a nested struct while keeping the
call-site type-safe.
- blit_bitmap_clipped_native promoted from `unsafe fn` to `pub` so
the DLL hook can call it directly.

New ports in `vtable.rs`:

- `blit_bitmap_tiled_native` — pure-Rust port of BlitBitmapTiled. The
two-loop alignment idiom (walk x by ±tile_width until x ≤ clip_x1)
was verified against the disassembly at 0x56A7DD..0x56A7F4. Then
loops `blit_bitmap_clipped_native` across `[clip_x1, clip_x2)`.
- `get_bitmap_sprite_info` — pure-Rust port of GetBitmapSpriteInfo.
Forward-mode and ping-pong frame index calculation, returns the
resolved frame's `*mut CBitmap` via `LayerSpriteFrame::bitmap_ptr`.

DLL `blit_sprite` now calls these three native functions directly
in the bitmap-sprite branch. Deletes ~95 lines of asm bridges
(`wa_get_bitmap_sprite_info`, `wa_blit_bitmap_clipped`,
`wa_blit_bitmap_tiled`) plus their three address constants
(`DISPLAY_GFX_GET_BITMAP_SPRITE_INFO`,
`DISPLAY_GFX_BLIT_BITMAP_CLIPPED`, `DISPLAY_GFX_BLIT_BITMAP_TILED`).

Verification: cargo build clean, 15/15 headless replay tests pass,
headful gameplay (HUD, weapon icons, scoreboard) confirmed visually
by user — graphics look perfect, no visible issues.

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

crates/openwa-core/src/address.rs

@@ -462,12 +462,6 @@ pub mod va {
         fn/Usercall DISPLAY_GFX_INIT = 0x0056_9D00;
         /// DisplayGfx vtable slot 19 — blit sprite
         fn/Thiscall DISPLAY_GFX_BLIT_SPRITE = 0x0056_B080;
-        /// DisplayGfx bitmap sprite info lookup — usercall(EAX=bitmap_obj, EDX=palette), RET 0x18
-        fn/Usercall DISPLAY_GFX_GET_BITMAP_SPRITE_INFO = 0x0057_3C50;
-        /// DisplayGfx bitmap blit (clipped) — usercall(EAX=this, EDX=width), RET 0x14
-        fn/Usercall DISPLAY_GFX_BLIT_BITMAP_CLIPPED = 0x0056_A700;
-        /// DisplayGfx bitmap blit (tiled) — usercall(EAX=initial_x, EDI=tile_width), RET 0x10
-        fn/Usercall DISPLAY_GFX_BLIT_BITMAP_TILED = 0x0056_A7D0;
         /// DisplayGfx flush render lock — releases lock, plain RET
         fn DISPLAY_GFX_FLUSH_RENDER_LOCK = 0x0056_A330;
         /// Streaming audio constructor

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

@@ -1,7 +1,7 @@
 use super::base::DisplayBase;
 use super::vtable::DisplayGfxVtable;
 use crate::bitgrid::DisplayBitGrid;
-use crate::render::sprite::sprite::CBitmap;
+use crate::render::sprite::sprite::{CBitmap, LayerSprite};
 use core::ffi::c_void;
 
 /// DisplayGfx — full display/graphics subsystem (derived from DisplayBase).
@@ -133,9 +133,11 @@ pub struct DisplayGfx {
     // =========================================================================
     // Sprite/bitmap table (0x3DD4 - 0x4DD7)
     // =========================================================================
-    /// 0x3DD4: Sprite table — 1024 DWORD entries, zeroed in DisplayGfx__Init.
-    /// Used for tracking loaded sprites/bitmaps by ID.
-    pub sprite_table: [u32; 0x400],
+    /// 0x3DD4: Bitmap-sprite table — 1024 entries, zeroed in DisplayGfx__Init.
+    /// Each non-null entry is a `LayerSprite` allocated by `load_sprite_by_layer`
+    /// (vtable slot 37). Read by `GetBitmapSpriteInfo` (slot's helper, used
+    /// by the bitmap-sprite branch of `BlitSprite` / slot 19).
+    pub sprite_table: [*mut LayerSprite; 0x400],
     // =========================================================================
     // Tile stream config (0x4DD4 - 0x4DF3)
     // =========================================================================

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

@@ -891,7 +891,7 @@ pub unsafe extern "thiscall" fn is_sprite_loaded(this: *mut DisplayGfx, id: i32)
     let base = &(*this).base;
     if !base.sprite_ptrs[id as usize].is_null()
         || !base.sprite_banks[id as usize].is_null()
-        || (*this).sprite_table[id as usize] != 0
+        || !(*this).sprite_table[id as usize].is_null()
     {
         1
     } else {
@@ -1772,11 +1772,12 @@ pub unsafe fn load_sprite_by_name(
             }
         }
 
-        // Read sprite metadata fields
+        // Read sprite metadata fields (in original WA's read order:
+        // field_60 first, then flags / cell_width / cell_height).
         GfxDirStream::read_raw(stream, sp.add(0x60), 4); // field_60
-        GfxDirStream::read_raw(stream, sp.add(0x64), 2); // field_64
-        GfxDirStream::read_raw(stream, sp.add(0x68), 2); // field_68
-        GfxDirStream::read_raw(stream, sp.add(0x6A), 2); // field_6a
+        GfxDirStream::read_raw(stream, sp.add(0x64), 2); // flags
+        GfxDirStream::read_raw(stream, sp.add(0x68), 2); // cell_width
+        GfxDirStream::read_raw(stream, sp.add(0x6A), 2); // cell_height
 
         // frame_count: zero first, then read
         (*sprite).frame_count = 0;
@@ -2034,7 +2035,7 @@ pub unsafe fn load_sprite_by_layer(
     }
 
     // Store in sprite_table (DisplayGfx offset 0x3DD4)
-    (*this).sprite_table[id as usize] = sprite as u32;
+    (*this).sprite_table[id as usize] = sprite;
 
     1
 }
@@ -2711,16 +2712,14 @@ unsafe fn cbitmap_blit_via_wrapper(
 /// render lock if held, and dispatches the actual blit through
 /// `cbitmap_blit_via_wrapper`.
 ///
-/// Used by ported slots 11 (`DrawTiledBitmap`) and 22 (`DrawTiledTerrain`).
-/// The original WA function at `0x56A700` still exists and is called by
-/// the slot-19 bitmap-sprite fallback path (`wa_blit_bitmap_clipped`) —
-/// see follow-up plan item 4. The address constant
-/// `DISPLAY_GFX_BLIT_BITMAP_CLIPPED` is kept until that path is ported.
+/// Used by ported slots 11 (`DrawTiledBitmap`), 22 (`DrawTiledTerrain`),
+/// and the bitmap-sprite branch of slot 19 (`BlitSprite`) via the DLL
+/// `blit_sprite` hook.
 ///
 /// # Safety
 /// `this` must be a valid `*mut DisplayGfx`. `surface` must be a valid
 /// `*mut CBitmap`. `g_RenderContext` must be initialized.
-unsafe fn blit_bitmap_clipped_native(
+pub unsafe fn blit_bitmap_clipped_native(
     this: *mut DisplayGfx,
     dst_x: i32,
     dst_y: i32,
@@ -2768,6 +2767,122 @@ unsafe fn blit_bitmap_clipped_native(
     );
 }
 
+/// Pure-Rust port of `DisplayGfx::BlitBitmapTiled` (`0x56A7D0`,
+/// usercall EAX=initial_x, EDI=tile_width).
+///
+/// Tiles `surface` horizontally across the visible clip range
+/// `[clip_x1, clip_x2)`. The function first walks `initial_x` by
+/// `±tile_width` until `x ≤ clip_x1`, then blits at `(x, dst_y),
+/// (x + tile_width, dst_y), …` until past `clip_x2`. Each blit goes
+/// through `blit_bitmap_clipped_native` with the same fixed `flags = 2`
+/// the original WA function uses.
+///
+/// Used by the bitmap-sprite branch of slot 19 (`BlitSprite`) when the
+/// `tiled` mode bit (high_flags bit 16) is set on the sprite.
+///
+/// # Safety
+/// `this` must be a valid `*mut DisplayGfx` with an initialized clip
+/// rect. `surface` must be a valid `*mut CBitmap`. `tile_width` must be
+/// positive (zero or negative would loop forever; matches the original).
+pub unsafe fn blit_bitmap_tiled_native(
+    this: *mut DisplayGfx,
+    initial_x: i32,
+    tile_width: i32,
+    dst_y: i32,
+    height: i32,
+    surface: *mut CBitmap,
+) {
+    let clip_x1 = (*this).base.clip_x1;
+    let clip_x2 = (*this).base.clip_x2;
+
+    // Walk to the largest x ≤ clip_x1 in the arithmetic sequence
+    // {initial_x ± k*tile_width} (matches the original's two-loop pattern
+    // at 0x56A7DD..0x56A7F4).
+    let mut x = initial_x;
+    while x < clip_x1 {
+        x += tile_width;
+    }
+    while x > clip_x1 {
+        x -= tile_width;
+    }
+
+    while x < clip_x2 {
+        blit_bitmap_clipped_native(this, x, dst_y, tile_width, height, surface, 2);
+        x += tile_width;
+    }
+}
+
+/// Pure-Rust port of `DisplayGfx::GetBitmapSpriteInfo` (`0x573C50`,
+/// usercall EAX=bitmap_obj, EDX=palette_or_anim).
+///
+/// Resolves an animation/palette value into a frame index for a
+/// `LayerSprite`, then writes the selected frame's bounding box and the
+/// sprite's full cell width/height to the output pointers and returns a
+/// pointer to the frame's `CBitmap` (the trailing 12 bytes of the
+/// `LayerSpriteFrame` entry).
+///
+/// `bitmap_obj.flags` (`LayerSprite +0x64`) controls interpretation of
+/// `palette_or_anim`:
+/// - bit 0 set: low 16 bits taken as-is (no clamp)
+/// - bit 0 clear: signed clamp to `[0, 0xFFFF]`
+/// - bit 1 set: ping-pong (bounce) iteration over `[0, frame_count)`
+/// - bit 1 clear: forward iteration
+///
+/// Used by the bitmap-sprite branch of slot 19 (`BlitSprite`).
+///
+/// # Safety
+/// `bitmap_obj` must be a valid `LayerSprite` with a populated
+/// `frame_array`. The output pointers must be writable.
+pub unsafe fn get_bitmap_sprite_info(
+    bitmap_obj: *mut LayerSprite,
+    palette_or_anim: 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,
+) -> *mut CBitmap {
+    let flags = (*bitmap_obj).flags as i32;
+
+    // Step 1: clamp / mask the palette_or_anim value into [0, 0xFFFF].
+    let pal: i32 = if flags & 1 != 0 {
+        (palette_or_anim & 0xFFFF) as i32
+    } else {
+        let p = palette_or_anim as i32;
+        p.max(0).min(0xFFFF)
+    };
+
+    // Step 2: compute frame index from frame_count and pal.
+    let frame_count = (*bitmap_obj).frame_count as i16 as i32;
+    let frame_idx = if flags & 2 != 0 {
+        // Ping-pong: scaled = ((2*frame_count - 1) * pal) >> 16
+        // If scaled >= frame_count, fold back: (2*frame_count - scaled) - 1.
+        let scaled = ((frame_count * 2 - 1) * pal) >> 16;
+        if scaled >= frame_count {
+            (frame_count * 2 - scaled) - 1
+        } else {
+            scaled
+        }
+    } else {
+        // Forward: idx = (frame_count * pal) >> 16
+        (frame_count * pal) >> 16
+    };
+
+    // Step 3: read the selected frame entry.
+    let frame = (*bitmap_obj).frame_array.offset(frame_idx as isize);
+
+    *out_left = (*frame).start_x as i32;
+    *out_top = (*frame).start_y as i32;
+    *out_right = (*frame).end_x as i32;
+    *out_bottom = (*frame).end_y as i32;
+
+    *out_w = (*bitmap_obj).cell_width as i32;
+    *out_h = (*bitmap_obj).cell_height as i32;
+
+    LayerSpriteFrame::bitmap_ptr(frame)
+}
+
 /// Pure-Rust port of `DisplayGfx::DrawTiledBitmap` (vtable slot 11,
 /// `0x56B8C0`).
 ///

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

@@ -184,6 +184,12 @@ pub struct SpriteBankVtable {
 
 /// Layer sprite — 0x70-byte object used by `load_sprite_by_layer` (vtable slot 37).
 ///
+/// Also used for the "bitmap sprite" path of `BlitSprite` (slot 19): the
+/// per-id pointers in `DisplayGfx::sprite_table` (`+0x3DD4`) point at
+/// `LayerSprite` instances. `DisplayGfx::GetBitmapSpriteInfo` reads
+/// `flags`, `frame_count`, `cell_width`, `cell_height`, and `frame_array`
+/// to resolve a frame index → frame metadata + `CBitmap` pointer.
+///
 /// Unlike `Sprite` (which has a vtable and is created via ConstructSprite), this
 /// is a raw allocation with partial init by the caller. Used for background layers
 /// (back.spr, layer.spr) which load DirectDraw surfaces directly from `.dir` files.
@@ -200,14 +206,18 @@ pub struct LayerSprite {
     pub palette_ctx: *mut PaletteContext,
     /// 0x60: Header field from stream (4 bytes).
     pub field_60: u32,
-    /// 0x64: Header field from stream (2 bytes).
-    pub field_64: u16,
+    /// 0x64: Animation/playback mode flags. Read by
+    /// `GetBitmapSpriteInfo` to decide how to interpret the
+    /// palette/anim parameter:
+    /// - bit 0: low 16 bits used as-is (no clamp)
+    /// - bit 1: ping-pong (bounce) frame iteration
+    pub flags: u16,
     /// 0x66: Frame count (zeroed, then read from stream).
     pub frame_count: u16,
-    /// 0x68: Header field from stream (2 bytes).
-    pub field_68: u16,
-    /// 0x6A: Header field from stream (2 bytes).
-    pub field_6a: u16,
+    /// 0x68: Sprite cell width in pixels (used for centering during blit).
+    pub cell_width: i16,
+    /// 0x6A: Sprite cell height in pixels (used for centering during blit).
+    pub cell_height: i16,
     /// 0x6C: Pointer to LayerSpriteFrame array (count stored at ptr[-4]).
     pub frame_array: *mut LayerSpriteFrame,
 }
@@ -272,6 +282,18 @@ pub struct LayerSpriteFrame {
 
 const _: () = assert!(core::mem::size_of::<LayerSpriteFrame>() == 0x14);
 
+impl LayerSpriteFrame {
+    /// Returns a pointer to the trailing 12-byte `CBitmap` block
+    /// (`bitmap_vtable`/`surface`/`_pad_10`) inside this entry. The
+    /// `CBitmap` layout is bit-identical to the trailing 12 bytes of
+    /// `LayerSpriteFrame`, so the value can be passed to any function
+    /// that takes `*mut CBitmap` (e.g., `blit_bitmap_clipped_native`).
+    #[inline]
+    pub fn bitmap_ptr(this: *mut Self) -> *mut CBitmap {
+        unsafe { (this as *mut u8).add(0x08) as *mut CBitmap }
+    }
+}
+
 crate::define_addresses! {
     class "CBitmap" {
         /// Vtable shared by [`CBitmap`] (12 bytes) and [`LayerSpriteFrame`]

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

@@ -808,19 +808,19 @@ unsafe extern "thiscall" fn blit_sprite(
     if arr1 == 0 && arr2 == 0 {
         // Bitmap sprite path — sprite is in the bitmap table at 0x3DD4.
         let bitmap_obj = (*gfx).sprite_table[sprite_id as usize];
-        if bitmap_obj == 0 {
+        if bitmap_obj.is_null() {
             return;
         }
 
-        // Get frame data and dimensions from bitmap sprite object
+        // Get frame data and dimensions from bitmap sprite object.
         let mut sprite_w: i32 = 0;
         let mut sprite_h: i32 = 0;
         let mut rect_left: i32 = 0;
         let mut rect_top: i32 = 0;
         let mut rect_right: i32 = 0;
         let mut rect_bottom: i32 = 0;
-        let frame_data = wa_get_bitmap_sprite_info(
-            bitmap_obj as *mut u8,
+        let frame_data = display_vtable::get_bitmap_sprite_info(
+            bitmap_obj,
             pal,
             &mut sprite_w,
             &mut sprite_h,
@@ -828,7 +828,6 @@ unsafe extern "thiscall" fn blit_sprite(
             &mut rect_top,
             &mut rect_right,
             &mut rect_bottom,
-            rb(openwa_core::address::va::DISPLAY_GFX_GET_BITMAP_SPRITE_INFO),
         );
         if frame_data.is_null() {
             return;
@@ -839,33 +838,18 @@ unsafe extern "thiscall" fn blit_sprite(
         let half_w = sprite_w / 2;
         let half_h = sprite_h / 2;
         let blit_h = rect_bottom - rect_top;
-
+        let dst_x = (x.0 >> 16) + (camera_x - half_w) + rect_left;
         let dst_y = (y.0 >> 16) + (camera_y - half_h) + rect_top;
 
         if (high_flags & 0x0001_0000) == 0 {
-            // Non-tiled: BlitBitmapClipped
-            let dst_x = (x.0 >> 16) + (camera_x - half_w) + rect_left;
-            wa_blit_bitmap_clipped(
-                this as *mut u8,
-                sprite_w as u32,
-                dst_x,
-                dst_y,
-                blit_h,
-                frame_data,
-                2,
-                rb(openwa_core::address::va::DISPLAY_GFX_BLIT_BITMAP_CLIPPED),
+            // Non-tiled: clipped blit at (dst_x, dst_y).
+            display_vtable::blit_bitmap_clipped_native(
+                gfx, dst_x, dst_y, sprite_w, blit_h, frame_data, 2,
             );
         } else {
-            // Tiled: BlitBitmapTiled
-            let dst_x = (x.0 >> 16) + (camera_x - half_w) + rect_left;
-            wa_blit_bitmap_tiled(
-                dst_x,
-                sprite_w,
-                this as *mut u8,
-                dst_y,
-                blit_h,
-                frame_data,
-                rb(openwa_core::address::va::DISPLAY_GFX_BLIT_BITMAP_TILED),
+            // Tiled: horizontal tile across the clip rect.
+            display_vtable::blit_bitmap_tiled_native(
+                gfx, dst_x, sprite_w, dst_y, blit_h, frame_data,
             );
         }
         return;
@@ -1136,93 +1120,6 @@ unsafe extern "thiscall" fn blit_sprite(
     );
 }
 
-// =========================================================================
-// Bitmap sprite bridges (naked asm for usercall conventions)
-// =========================================================================
-
-/// Call DisplayGfx__GetBitmapSpriteInfo (0x573C50).
-/// Usercall: EAX=bitmap_obj, EDX=palette, 6 stack params (output ptrs), RET 0x18.
-#[unsafe(naked)]
-unsafe extern "cdecl" fn wa_get_bitmap_sprite_info(
-    _bitmap_obj: *mut u8,
-    _palette: 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,
-    _target: u32,
-) -> *const u8 {
-    core::arch::naked_asm!(
-        "mov eax, [esp + 4]",        // bitmap_obj
-        "mov edx, [esp + 8]",        // palette
-        "mov ecx, [esp + 36]",       // target
-        "push dword ptr [esp + 32]", // out_bottom
-        "push dword ptr [esp + 32]", // out_right
-        "push dword ptr [esp + 32]", // out_top
-        "push dword ptr [esp + 32]", // out_left
-        "push dword ptr [esp + 32]", // out_h
-        "push dword ptr [esp + 32]", // out_w
-        "call ecx",                  // RET 0x18 cleans 6 params
-        "ret",
-    );
-}
-
-/// Call DisplayGfx__BlitBitmapClipped (0x56A700).
-/// Usercall: EAX=this, EDX=width, 5 stack params (dst_x, dst_y, height, frame_data, flags), RET 0x14.
-#[unsafe(naked)]
-unsafe extern "cdecl" fn wa_blit_bitmap_clipped(
-    _this: *mut u8,
-    _width: u32,
-    _dst_x: i32,
-    _dst_y: i32,
-    _height: i32,
-    _frame_data: *const u8,
-    _flags: u32,
-    _target: u32,
-) {
-    core::arch::naked_asm!(
-        "mov eax, [esp + 4]",        // this
-        "mov edx, [esp + 8]",        // width
-        "mov ecx, [esp + 32]",       // target
-        "push dword ptr [esp + 28]", // flags
-        "push dword ptr [esp + 28]", // frame_data
-        "push dword ptr [esp + 28]", // height
-        "push dword ptr [esp + 28]", // dst_y
-        "push dword ptr [esp + 28]", // dst_x
-        "call ecx",                  // RET 0x14 cleans 5 params
-        "ret",
-    );
-}
-
-/// Call DisplayGfx__BlitBitmapTiled (0x56A7D0).
-/// Usercall: EAX=initial_x, EDI=tile_width, 4 stack params (this, dst_y, height, frame_data), RET 0x10.
-#[unsafe(naked)]
-unsafe extern "cdecl" fn wa_blit_bitmap_tiled(
-    _initial_x: i32,
-    _tile_width: i32,
-    _this: *mut u8,
-    _dst_y: i32,
-    _height: i32,
-    _frame_data: *const u8,
-    _target: u32,
-) {
-    core::arch::naked_asm!(
-        "push edi",
-        "mov eax, [esp + 8]",        // initial_x
-        "mov edi, [esp + 12]",       // tile_width
-        "mov ecx, [esp + 32]",       // target (offset +4 from push edi)
-        "push dword ptr [esp + 28]", // frame_data
-        "push dword ptr [esp + 28]", // height
-        "push dword ptr [esp + 28]", // dst_y
-        "push dword ptr [esp + 28]", // this
-        "call ecx",                  // RET 0x10 cleans 4 params
-        "pop edi",
-        "ret",
-    );
-}
-
 /// Thiscall wrapper for DisplayGfx::DrawScaledSprite (slot 20).
 ///
 /// Computes coordinates in core, then dispatches the blit via blit_impl.