feat: port DisplayGfx::GetSpriteFrameForBlit (slot 33) to pure Rust

This is the LAST in-game render bridge. With this slot ported, the
entire render pipeline of a normal Worms match runs on Rust code with
zero bridges into WA's render functions; only the renderer backend
itself (CompatRenderer / DDraw / OpenGL) and the shutdown destructor
(slot 0) remain.

Three function ports + two new leaf modules:

- `render::sprite::lzss::sprite_lzss_decode` — port of
`Sprite_LZSS_Decode` (0x5B29E0). LZSS-style decompressor with
palette LUT remapping. Key detail verified from the disassembly:
short backrefs encode `real_distance - 1` (the asm's `DEC ECX`
between the JZ and the read), but long backrefs encode the real
distance directly (the JZ jumps OVER the DEC). 6 unit tests cover
literal runs, both backref forms, length boundaries, the
terminator, and self-overlap RLE-style cases.

- `render::sprite::frame_cache::frame_cache_allocate` — port of
`FrameCache__Allocate` (0x4FA950). LRU ring-buffer allocator with
eviction notification via `vtable[1]` (`on_subframe_evicted`).
Notable correction to the prep-session blueprint: the entry header
has `frame_idx@+8` and `owner@+0xc` (not the other way around) —
verified from the function epilog where `[ESP+0x1c]→[EAX]` and
`[ESP+0x18]→[EAX+4]`. 3 unit tests cover single alloc, LRU
chaining, and eviction-with-wrap (using a mock owner vtable).

- `display::vtable::sprite_get_frame_for_blit` — port of
`Sprite__GetFrameForBlit` (0x4FAD30). All three frame-resolution
paths (scaled / round-to-nearest / truncating) plus the cached and
flat surface dispatch. Inlines the bitgrid update writes to match
the original asm's order at 0x4FAEA2..0x4FAEB7.

- `display::vtable::sprite_bank_get_frame_for_blit` — port of
`SpriteBank__GetFrameForBlit` (0x4F9710). The bank-side counterpart
with the 7-bit signed nibble extraction for scaled mode
(`(low7 << 16) >> 5`) and the bbox-table / subframe-cache lookups
using the bank-specific layouts from the pre-work commit. Critical
detail caught from disasm: `EAX = low - high` at 0x4F97AD (not
high - low). Note: this path is suspected dead in normal gameplay
— adding a `panic!()` and playing several turns of a regular
match did not trigger it. The path is still ported as a defensive
measure for any obscure game state we haven't sampled.

- `display::vtable::bitgrid_set_external_buffer` — port of
`DisplayBitGrid::SetExternalBuffer` (0x4F6470). Used by the bank
path to update the embedded `frame_bitgrid` at `bank + 0x130`.

- `display::vtable::get_sprite_frame_for_blit` — slot 33 dispatcher.
Validates `sprite_id` (1..=0x3FE), then forwards to the sprite
helper for `sprite_ptrs[id]` or the bank helper for
`sprite_banks[id]`. Wired via `vtable_replace!` in
`install_display`.

Verification:
- 135/135 unit tests pass (incl. 6 lzss + 3 frame_cache).
- 15/15 headless replay tests pass.
- Headful verification: user played a normal Worms match — sprite
animations, weapons, particles, fire/smoke/water all render
correctly. SpriteBank path was not triggered (see panic! note
above).

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

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

@@ -317,12 +317,20 @@ pub struct DisplayGfxVtable {
     /// | `out_left`/`top`/`right`/`bot` | frame bounding box within the cell               |
     /// | `out_anim_frac`                | sub-frame interpolation value (Fixed16) or 0     |
     ///
-    /// Currently still bridged: `BlitSprite` (slot 19) calls this through
-    /// the typed `get_sprite_frame_for_blit_raw` wrapper from
-    /// `replacements/render.rs::blit_sprite`. This is the **last** in-game
-    /// render bridge; everything else in the pipeline runs as native Rust.
+    /// **Ported.** Native Rust impl is [`get_sprite_frame_for_blit`]
+    /// in this file (Sprite path → [`sprite_get_frame_for_blit`],
+    /// SpriteBank path → [`sprite_bank_get_frame_for_blit`]). Wired via
+    /// `vtable_replace!` in `install_display`. With this slot ported,
+    /// the entire in-game render pipeline of a normal Worms match runs
+    /// on Rust code with zero bridges into WA's render functions.
     ///
-    /// # Porting blueprint
+    /// **SpriteBank path is suspected dead in normal gameplay** — adding
+    /// a `panic!()` to `sprite_bank_get_frame_for_blit` and playing
+    /// several turns of a normal match did not trigger it. The path is
+    /// still ported (per the disassembly) as a defensive measure for any
+    /// obscure game state we haven't sampled.
+    ///
+    /// # Porting blueprint (kept for archival reference)
     ///
     /// ## Dispatcher (slot 33 itself, 0x5237C0, RET 0x24)
     ///
@@ -847,7 +855,9 @@ use super::gfx::DisplayGfx;
 use super::line_draw;
 use crate::bitgrid::{BitGrid, DisplayBitGrid};
 use crate::render::palette::PaletteContext;
-use crate::render::sprite::{Sprite, SpriteBank, SpriteVtable};
+use crate::render::sprite::{
+    frame_cache::frame_cache_allocate, lzss::sprite_lzss_decode, Sprite, SpriteBank, SpriteVtable,
+};
 
 /// Port of DisplayGfx::GetDimensions (vtable slot 1, 0x56A460).
 ///
@@ -1487,6 +1497,424 @@ unsafe fn sprite_info_from_bank(
     crate::rebase::rb(SPRITE_STRING)
 }
 
+/// Pure-Rust port of `Sprite__GetFrameForBlit` (0x4FAD30).
+///
+/// Resolves an animation value to a frame within `sprite`, lazily
+/// decompresses its surface via [`frame_cache_allocate`] +
+/// [`sprite_lzss_decode`] if the sprite uses the cached path
+/// (`header_flags & 0x4000`), updates `sprite.bitgrid` to point at the
+/// resulting pixel data, and returns a pointer to that embedded bitgrid.
+///
+/// Mirrors the original WA usercall (`ESI=this, EAX=out_anim_frac,
+/// EDX=anim_value, stack=(out_w, out_h, out_left, out_top, out_right,
+/// out_bottom)`) as a regular Rust function — the slot 33 dispatcher
+/// shuffles its caller's args into this signature.
+///
+/// # Safety
+///
+/// All output pointers must be valid for writes. `sprite` must point at a
+/// fully-constructed [`Sprite`] (i.e. `frame_meta_ptr` populated and, for
+/// the cached path, `subframe_cache_table` and `bitmap_data_ptr` set).
+unsafe fn sprite_get_frame_for_blit(
+    sprite: *mut Sprite,
+    mut anim_value: u32,
+    out_anim_frac: *mut 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 DisplayBitGrid {
+    let flags = (*sprite).flags;
+
+    // ── Step 1: clamp `anim_value` ───────────────────────────────────
+    if flags & 1 != 0 {
+        // Use-as-is mode: just truncate to 16 bits.
+        anim_value &= 0xFFFF;
+    } else {
+        // Signed clamp to [0, 0xFFFF].
+        let signed = anim_value as i32;
+        if signed < 0 {
+            anim_value = 0;
+        } else if signed >= 0x10000 {
+            anim_value = 0xFFFF;
+        }
+    }
+
+    // ── Step 2: ping-pong ────────────────────────────────────────────
+    if flags & 2 != 0 {
+        anim_value &= 0xFFFF;
+        anim_value = anim_value.wrapping_mul(2);
+        if anim_value >= 0x10000 {
+            anim_value = 0x1FFFE - anim_value;
+        }
+    }
+
+    // ── Step 3: frame index resolution ───────────────────────────────
+    let frame_idx: u32 = if (*sprite).is_scaled != 0 {
+        // Scaled mode: linearly interpolate between scale_x and scale_y
+        // by the (Fixed16) anim_value, write the interpolated result to
+        // *out_anim_frac. Always use frame 0 in this mode.
+        let scale_x = (*sprite).scale_x as i32;
+        let scale_y = (*sprite).scale_y as i32;
+        let diff = scale_y.wrapping_sub(scale_x);
+        // Original asm: `IMUL EDX; SHRD EAX, EDX, 0x10` — 32×32 → 64
+        // signed multiply with `>> 16` (Fixed16). The multiplicand is the
+        // raw `anim_value` interpreted as a signed 32-bit integer (after
+        // the clamp/ping-pong above it's always in [0, 0xFFFF], so the
+        // sign bit is clear).
+        let prod = (diff as i64).wrapping_mul((anim_value as i32) as i64);
+        let interp = ((prod >> 16) as i32).wrapping_add(scale_x);
+        *out_anim_frac = interp as u32;
+        0
+    } else if (*sprite).frame_round_mode & 1 != 0 {
+        // Round-to-nearest mode: `((max_frames * anim_value) + 0x8000) >> 16`,
+        // with the special case that if rounding produces `frame_idx ==
+        // max_frames` we wrap back to 0 (avoids reading past the table).
+        let max_frames = (*sprite).max_frames as i32;
+        let prod = max_frames.wrapping_mul(anim_value as i32);
+        let f = (prod.wrapping_add(0x8000) >> 16) as u32;
+        *out_anim_frac = 0;
+        if f == max_frames as u32 {
+            0
+        } else {
+            f
+        }
+    } else {
+        // Truncating mode.
+        let max_frames = (*sprite).max_frames as i32;
+        let prod = max_frames.wrapping_mul(anim_value as i32);
+        *out_anim_frac = 0;
+        (prod >> 16) as u32
+    };
+
+    // ── Step 4: read frame metadata + sprite cell dimensions ─────────
+    let frame_meta = (*sprite).frame_meta_ptr.add(frame_idx as usize);
+    let start_x = (*frame_meta).start_x as i16 as i32;
+    let start_y = (*frame_meta).start_y as i16 as i32;
+    let end_x = (*frame_meta).end_x as i16 as i32;
+    let end_y = (*frame_meta).end_y as i16 as i32;
+    *out_left = start_x;
+    *out_top = start_y;
+    *out_right = end_x;
+    *out_bottom = end_y;
+    *out_w = (*sprite).width as i32;
+    *out_h = (*sprite).height as i32;
+    let frame_w = end_x - start_x;
+    let frame_h = end_y - start_y;
+
+    // ── Step 5: surface address (flat or cached/decompressed) ────────
+    let surface_addr: *mut u8 = if (*sprite).header_flags & 0x4000 == 0 {
+        // Flat path: bytes are already-decoded raw pixels in the load
+        // buffer.
+        let bitmap_offset = (*frame_meta).bitmap_offset;
+        (*sprite).bitmap_data_ptr.add(bitmap_offset as usize)
+    } else {
+        // Cached path: bitmap_offset is split into a signed-byte
+        // subframe index (high byte) and a pixel offset (low 24 bits).
+        let bitmap_offset = (*frame_meta).bitmap_offset;
+        let subframe_idx_signed = ((bitmap_offset >> 24) as i8) as i32;
+
+        // The original asm uses MOVSX byte ptr [EAX+EDI+3] then a *12
+        // lea — i.e. negative subframe indices index *backward* from the
+        // table base. Mirror via `offset(isize)`.
+        let entry = (*sprite)
+            .subframe_cache_table
+            .offset(subframe_idx_signed as isize);
+
+        if (*entry).decoded_ptr.is_null() {
+            // Allocate from the per-SpriteCache FrameCache and decompress.
+            let context_ptr = (*sprite).context_ptr;
+            let decoded_size = (*entry).decoded_size;
+            let decoded = frame_cache_allocate(
+                decoded_size,
+                context_ptr,
+                sprite as *mut core::ffi::c_void,
+                subframe_idx_signed as u32,
+            );
+            (*entry).decoded_ptr = decoded;
+            let src = (*sprite)
+                .bitmap_data_ptr
+                .add((*entry).compressed_offset as usize);
+            sprite_lzss_decode(decoded, src, (*sprite).palette_data_ptr);
+        }
+
+        let pixel_offset = (bitmap_offset & 0xFF_FFFF) as usize;
+        (*entry).decoded_ptr.add(pixel_offset)
+    };
+
+    // ── Step 6: update embedded bitgrid (only if external_buffer != 0)
+    let bitgrid = &raw mut (*sprite).bitgrid;
+    if (*bitgrid).external_buffer != 0 {
+        // Order copied from the asm at 0x4FAEA2..0x4FAEB7. Equivalent
+        // to `bitgrid_set_external_buffer(bitgrid, surface, frame_w,
+        // frame_w, frame_h)` — see SpriteBank path which calls the
+        // shared `DisplayBitGrid::SetExternalBuffer` helper.
+        (*bitgrid).clip_bottom = frame_h as u32;
+        (*bitgrid).clip_right = frame_w as u32;
+        (*bitgrid).clip_top = 0;
+        (*bitgrid).clip_left = 0;
+        (*bitgrid).row_stride = frame_w as u32;
+        (*bitgrid).data = surface_addr;
+        (*bitgrid).height = frame_h as u32;
+        (*bitgrid).width = frame_w as u32;
+    }
+
+    bitgrid
+}
+
+/// Pure-Rust port of `DisplayBitGrid::SetExternalBuffer` (0x4F6470).
+///
+/// Sets a `DisplayBitGrid`'s data pointer, dimensions, row stride, and
+/// clip rect (full-rect: `(0, 0, width, height)`). Returns `false` if the
+/// bitgrid's `external_buffer` flag is currently zero (i.e. it owns its
+/// own buffer and the caller has no business swapping it out).
+///
+/// Used by the SpriteBank path of slot 33 to point the bank's embedded
+/// `frame_bitgrid` (at `bank + 0x130`) at the freshly-decompressed
+/// subframe pixels. Inlined manually in the Sprite path because that one
+/// uses `frame_w` for both `width` and `row_stride`.
+#[inline]
+unsafe fn bitgrid_set_external_buffer(
+    bitgrid: *mut DisplayBitGrid,
+    data: *mut u8,
+    row_stride: u32,
+    width: u32,
+    height: u32,
+) -> bool {
+    if (*bitgrid).external_buffer == 0 {
+        return false;
+    }
+    (*bitgrid).data = data;
+    (*bitgrid).row_stride = row_stride;
+    (*bitgrid).width = width;
+    (*bitgrid).height = height;
+    (*bitgrid).clip_left = 0;
+    (*bitgrid).clip_top = 0;
+    (*bitgrid).clip_right = width;
+    (*bitgrid).clip_bottom = height;
+    true
+}
+
+/// Pure-Rust port of `SpriteBank__GetFrameForBlit` (0x4F9710).
+///
+/// SpriteBank-side counterpart of [`sprite_get_frame_for_blit`]: walks
+/// the bank's `index_table` to map `sprite_id` to a frame in
+/// `frame_table`, resolves the animation value to a sub-frame index in
+/// `bbox_table`, lazily decompresses the corresponding subframe via
+/// [`frame_cache_allocate`] + [`sprite_lzss_decode`], updates the
+/// embedded `frame_bitgrid` (at `bank + 0x130`), and returns a pointer
+/// to it. Returns null on any validation failure (null `frame_table` or
+/// out-of-range `entry_idx`).
+///
+/// Note the structural differences from the Sprite path:
+/// - Animation metadata lives in [`SpriteBankFrame`]
+///   (`flags/width/height/base_frame_idx/scale_or_count`) instead of
+///   `Sprite::flags`/`max_frames`/`scale_*`.
+/// - Out-`w`/`h` come from the per-frame `width`/`height`, NOT from a
+///   sprite-wide cell dimension.
+/// - The bbox table is a separate array of [`SpriteBankBboxEntry`] at
+///   `bank + 0x18`, with `subframe_idx` at `+0` (low u16 of what would
+///   be `SpriteFrame::bitmap_offset`) and `decoded_offset` at `+2`.
+/// - The subframe cache uses [`SpriteBankSubframeCache`] with
+///   `decoded_ptr` at `+8` (vs `+4` in `SpriteSubframeCache`).
+/// - The LUT for LZSS is the inline 256-byte `palette_lut` at
+///   `bank + 0x30`, not a separately-allocated palette pointer.
+/// - The bitgrid update goes through `bitgrid_set_external_buffer`
+///   instead of inline writes.
+///
+/// # Safety
+///
+/// `bank` must point at a valid, fully-parsed [`SpriteBank`]. Output
+/// pointers must be writable.
+#[allow(clippy::too_many_arguments)]
+unsafe fn sprite_bank_get_frame_for_blit(
+    bank: *mut SpriteBank,
+    sprite_id: u32,
+    mut anim_value: u32,
+    out_anim_frac: *mut 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 DisplayBitGrid {
+    // ── Index lookup + bounds check ──────────────────────────────────
+    let entry_idx = *(*bank)
+        .index_table
+        .offset((sprite_id as i32 - (*bank).base_id) as isize);
+    if (*bank).frame_table.is_null() || entry_idx < 0 || entry_idx >= (*bank).frame_count {
+        return core::ptr::null_mut();
+    }
+    let frame = (*bank).frame_table.add(entry_idx as usize);
+    let frame_flags = (*frame).flags;
+
+    // ── Clamp anim_value ─────────────────────────────────────────────
+    if frame_flags & 1 != 0 {
+        anim_value &= 0xFFFF;
+    } else {
+        let signed = anim_value as i32;
+        if signed < 0 {
+            anim_value = 0;
+        } else if signed >= 0x10000 {
+            anim_value = 0xFFFF;
+        }
+    }
+
+    // ── Ping-pong ────────────────────────────────────────────────────
+    if frame_flags & 2 != 0 {
+        anim_value &= 0xFFFF;
+        anim_value = anim_value.wrapping_mul(2);
+        if anim_value >= 0x10000 {
+            anim_value = 0x1FFFE - anim_value;
+        }
+    }
+
+    // ── Frame index resolution ───────────────────────────────────────
+    let scale_or_count = (*frame).scale_or_count;
+    let base_frame_idx = (*frame).base_frame_idx;
+
+    let resolved_idx: u32 = if scale_or_count & 0x8000 != 0 {
+        // Scaled mode: low/high 7-bit nibbles of `scale_or_count` form a
+        // signed Fixed16 pair. The asm extracts both via:
+        //   `value = (low_or_high_7 << 16) >> 5` (signed)
+        // i.e. shift the 7-bit value into the high half, sign-extend
+        // from bit 22, then shift right by 5 → effective `<< 11` with
+        // sign extension from bit 6 of the original 7-bit value.
+        let low7 = scale_or_count & 0x7F;
+        let high7 = (scale_or_count >> 8) & 0x7F;
+        let low_val = (((low7 as u32) << 16) as i32) >> 5;
+        let high_val = (((high7 as u32) << 16) as i32) >> 5;
+        // Note: the asm computes `EAX = low - high` (NOT high - low) —
+        // verified at 0x4F97AD `SUB EAX, EDI` where EAX = low_val and
+        // EDI = high_val.
+        let diff = low_val.wrapping_sub(high_val);
+        let prod = (diff as i64).wrapping_mul((anim_value as i32) as i64);
+        let interp = ((prod >> 16) as i32).wrapping_add(high_val);
+        *out_anim_frac = interp as u32;
+        // Scaled mode uses `base_frame_idx` directly as the bbox index.
+        base_frame_idx as u32
+    } else {
+        // Non-scaled mode: subframe_idx = ((scale_or_count * anim_value) >> 16)
+        // + base_frame_idx. *out_anim_frac = 0.
+        let prod = (scale_or_count as i32).wrapping_mul(anim_value as i32);
+        *out_anim_frac = 0;
+        ((prod >> 16) as u32).wrapping_add(base_frame_idx as u32)
+    };
+
+    // ── Read bbox metadata ───────────────────────────────────────────
+    let bbox = (*bank).bbox_table.add(resolved_idx as usize);
+    *out_left = (*bbox).start_x as i32;
+    *out_top = (*bbox).start_y as i32;
+    *out_right = (*bbox).end_x as i32;
+    *out_bottom = (*bbox).end_y as i32;
+    // out_w/out_h come from the per-frame width/height, NOT the bbox.
+    *out_w = (*frame).width as i32;
+    *out_h = (*frame).height as i32;
+    let frame_w = (*out_right - *out_left) as u32;
+    let frame_h = (*out_bottom - *out_top) as u32;
+
+    // ── Subframe cache lookup + lazy decompress ──────────────────────
+    let subframe_idx = (*bbox).subframe_idx as u32;
+    let entry = (*bank).subframe_cache_table.add(subframe_idx as usize);
+
+    if (*entry).decoded_ptr.is_null() {
+        let context_ptr = (*bank).context_ptr;
+        let decoded_size = (*entry).decoded_size;
+        let decoded = frame_cache_allocate(
+            decoded_size,
+            context_ptr,
+            bank as *mut core::ffi::c_void,
+            subframe_idx,
+        );
+        (*entry).decoded_ptr = decoded;
+        let src = (*bank)
+            .bitmap_data_ptr
+            .add((*entry).compressed_offset as usize) as *mut u8;
+        // Bank LUT is the inline 256-byte palette_lut at bank+0x30.
+        let lut = (&raw const (*bank).palette_lut) as *const u8;
+        sprite_lzss_decode(decoded, src, lut);
+    }
+
+    // ── Update embedded bitgrid via SetExternalBuffer ────────────────
+    //
+    // Surface address = bbox.decoded_offset + entry.decoded_ptr.
+    let surface = (*entry).decoded_ptr.add((*bbox).decoded_offset as usize);
+    let bitgrid = &raw mut (*bank).frame_bitgrid;
+    bitgrid_set_external_buffer(bitgrid, surface, frame_w, frame_w, frame_h);
+    bitgrid
+}
+
+/// Port of `DisplayGfx::GetSpriteFrameForBlit` (vtable slot 33, 0x5237C0).
+///
+/// Thin dispatcher: validates `sprite_id`, then forwards to either
+/// [`sprite_get_frame_for_blit`] (for `sprite_ptrs`-backed IDs) or
+/// [`sprite_bank_get_frame_for_blit`] (for `sprite_banks`-backed IDs).
+/// Returns null if neither table has an entry for the ID.
+///
+/// See the slot 33 docstring on
+/// [`DisplayGfxVtable::get_sprite_frame_for_blit`] for the original
+/// usercall convention and the full body breakdown.
+///
+/// # Safety
+///
+/// `this` must be a valid `*mut DisplayGfx`. All output pointers must
+/// be writable.
+#[allow(clippy::too_many_arguments)]
+pub unsafe extern "thiscall" fn get_sprite_frame_for_blit(
+    this: *mut DisplayGfx,
+    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 {
+    // Validity check: sprite_id - 1 must be < 0x3FE (so 1..=0x3FE).
+    if sprite_id.wrapping_sub(1) >= 0x3FE {
+        return core::ptr::null_mut();
+    }
+
+    let base = &mut (*this).base;
+    let sprite = base.sprite_ptrs[sprite_id as usize];
+    if !sprite.is_null() {
+        return sprite_get_frame_for_blit(
+            sprite,
+            anim_value,
+            out_anim_frac,
+            out_w,
+            out_h,
+            out_left,
+            out_top,
+            out_right,
+            out_bottom,
+        );
+    }
+
+    let bank = base.sprite_banks[sprite_id as usize];
+    if !bank.is_null() {
+        return sprite_bank_get_frame_for_blit(
+            bank,
+            sprite_id,
+            anim_value,
+            out_anim_frac,
+            out_w,
+            out_h,
+            out_left,
+            out_top,
+            out_right,
+            out_bottom,
+        );
+    }
+
+    core::ptr::null_mut()
+}
+
 /// Port of DisplayGfx::DrawViaCallback (vtable slot 21, 0x56B7C0).
 ///
 /// Acquires the render lock, applies camera offset to fixed-point coordinates,

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

@@ -0,0 +1,362 @@
+//! LRU ring-buffer allocator for sprite subframe payloads.
+//!
+//! Pure-Rust port of `FrameCache__Allocate` (0x4FA950). The shared
+//! [`FrameCache`] holds decompressed pixel data for the most recently
+//! requested sprite/sprite-bank subframes. When the buffer fills, the
+//! oldest entry is evicted and its owner is notified via
+//! `vtable[1]` (`on_subframe_evicted`) so it can clear its
+//! `decoded_ptr` and re-request decompression on the next render.
+//!
+//! Each allocated entry has a 16-byte header ([`FrameCacheEntry`]) followed
+//! inline by the payload bytes. The returned pointer is the payload start
+//! (`entry + 0x10`).
+//!
+//! See the slot 33 docstring in [`crate::render::display::vtable`] for the
+//! full reverse-engineering notes and the `Sprite__GetFrameForBlit` /
+//! `SpriteBank__GetFrameForBlit` callers.
+
+use core::ffi::c_void;
+use core::ptr::null_mut;
+
+#[cfg(test)]
+use crate::render::display::base::FrameCache;
+use crate::render::display::base::FrameCacheEntry;
+use crate::render::SpriteCache;
+
+/// Eviction callback signature — `vtable[1]` of both `Sprite` and
+/// `SpriteBank`. Called when the oldest entry is being dropped from the
+/// LRU ring buffer; the callback clears the owner's per-subframe
+/// `decoded_ptr` so the next render re-decompresses.
+///
+/// `this` is `victim.owner`. `subframe_idx` is `victim.frame_idx` (the
+/// caller's third stack arg from when the entry was allocated). `payload`
+/// is `victim + 0x10` — the payload start, which the original asm pushes
+/// but neither callback uses.
+type EvictCallback =
+    unsafe extern "thiscall" fn(this: *mut c_void, subframe_idx: u32, payload: *mut u8);
+
+/// Pure-Rust port of `FrameCache__Allocate` (0x4FA950).
+///
+/// Allocates `entry_size` bytes of payload from the [`FrameCache`] reached
+/// via `(*context_ptr).frame_cache`. On success, returns a pointer to the
+/// payload start. On contention, evicts the oldest live entry (notifying
+/// its owner via `vtable[1]`) and retries.
+///
+/// # Layout details
+///
+/// - The header allocation occupies `pad = ((entry_size + 8 + 0xb) & ~3)`
+///   bytes total (= `entry_size + 8` rounded up to a 4-byte stride after
+///   adding 11 bytes of slack).
+/// - The `payload_size` field stored in the entry header is
+///   `entry_size + 8` (NOT padded — the original asm computes the padded
+///   stride only for advancing `write_head`, never stores it).
+/// - On the long-backref `entry_count` cleanup branch where the new head
+///   becomes null, the original asm clears `wrap_marker` and `write_head`
+///   to 0 — the buffer is now empty and the next alloc starts from the
+///   beginning.
+///
+/// # Calling convention
+///
+/// The original is a usercall: `EAX = entry_size`, stack args
+/// `(context_ptr, owner, frame_idx)`. The Rust port takes these as
+/// regular params; callers should pass the same values.
+///
+/// # Safety
+///
+/// - `context_ptr` must point at a valid `SpriteCache` whose `frame_cache`
+///   field references a `FrameCache` initialized via `FUN_004fa860`
+///   (with a non-null `buffer` of at least `entry_size + 0x13` bytes).
+/// - `owner` must point at an object whose first field is a vtable
+///   pointer with `vtable[1]` matching [`EvictCallback`]. In practice
+///   this is `*mut Sprite` or `*mut SpriteBank`, both of whose
+///   `on_subframe_evicted` callbacks share the signature.
+/// - `entry_size` must be small enough to fit in the buffer
+///   (`entry_size + 0x13 <= capacity`); otherwise this loops forever.
+pub unsafe fn frame_cache_allocate(
+    entry_size: u32,
+    context_ptr: *mut SpriteCache,
+    owner: *mut c_void,
+    frame_idx: u32,
+) -> *mut u8 {
+    let payload_size = entry_size + 8;
+    let pad = (entry_size + 0x13) & !3;
+
+    loop {
+        let fc = (*context_ptr).frame_cache;
+        let write = (*fc).write_head;
+        let wrap = (*fc).wrap_marker;
+        let end = write + pad;
+
+        // Decide where (if anywhere) the new entry can go in this pass.
+        let placed_offset: Option<u32> = if write < wrap {
+            // Case A: write_head sits behind wrap_marker (a previously
+            // wrapped buffer). Allocation succeeds iff it doesn't reach
+            // wrap_marker.
+            if end <= wrap {
+                Some(write)
+            } else {
+                None
+            }
+        } else {
+            // Case B: write_head ahead of wrap_marker. Allocation
+            // succeeds iff it fits before the end of the buffer; if it
+            // doesn't, try wrapping to offset 0 — that succeeds iff
+            // `pad <= wrap_marker` (head_entry isn't sitting in the
+            // [0, pad) range).
+            if end <= (*fc).capacity {
+                Some(write)
+            } else if pad <= wrap {
+                Some(0)
+            } else {
+                None
+            }
+        };
+
+        if let Some(offset) = placed_offset {
+            let entry_addr = (*fc).buffer.add(offset as usize);
+            let entry = entry_addr as *mut FrameCacheEntry;
+
+            (*entry).payload_size = payload_size;
+            (*entry).next = null_mut();
+
+            if !(*fc).tail_entry.is_null() {
+                (*(*fc).tail_entry).next = entry;
+            }
+            (*fc).tail_entry = entry;
+            if (*fc).head_entry.is_null() {
+                (*fc).head_entry = entry;
+            }
+            (*fc).entry_count += 1;
+            (*fc).write_head = offset + pad;
+
+            // Note: original asm writes frame_idx and owner AFTER the
+            // POPAD/POP sequence — this is functionally equivalent.
+            (*entry).frame_idx = frame_idx;
+            (*entry).owner = owner;
+
+            return entry_addr.add(0x10);
+        }
+
+        // ── Out of room: evict the oldest entry and retry ───────────
+        //
+        // The original asm reloads `fc` from `*(context_ptr + 4)` here
+        // (in case the eviction callback somehow rebinds it). In practice
+        // both real callbacks just clear a `decoded_ptr` field, but we
+        // mirror the reload exactly.
+        let fc = (*context_ptr).frame_cache;
+        let head = (*fc).head_entry;
+        if head.is_null() {
+            // Theoretically unreachable: an empty cache has wrap=write=0
+            // and thus must always fit; if it doesn't, `pad > capacity`
+            // and the original asm spins forever. We mirror that.
+            continue;
+        }
+
+        // Notify the owner that its subframe payload is being dropped.
+        // Both Sprite and SpriteBank vtable[1] callbacks share the same
+        // shape: thiscall(this, frame_idx, payload). The asm pushes
+        // `payload` first then `frame_idx` (so `frame_idx` is the first
+        // stack arg), with ECX = owner.
+        let victim_owner = (*head).owner;
+        let victim_frame_idx = (*head).frame_idx;
+        let victim_payload = (head as *mut u8).add(0x10);
+
+        // Read vtable[1] manually so we don't need to commit to either
+        // SpriteVtable or SpriteBankVtable as the callback's `this` type.
+        let vtable = *(victim_owner as *const *const u32);
+        let slot1 = *vtable.add(1);
+        let callback: EvictCallback = core::mem::transmute(slot1);
+        callback(victim_owner, victim_frame_idx, victim_payload);
+
+        // Reload fc and unlink the (just-notified) head entry.
+        let fc = (*context_ptr).frame_cache;
+        if (*fc).head_entry.is_null() {
+            continue;
+        }
+        let new_head = (*(*fc).head_entry).next;
+        (*fc).head_entry = new_head;
+        if new_head.is_null() {
+            // Last entry just removed — clear the bookkeeping back to
+            // the empty state.
+            (*fc).entry_count -= 1;
+            (*fc).tail_entry = null_mut();
+            (*fc).wrap_marker = 0;
+            (*fc).write_head = 0;
+        } else {
+            // wrap_marker tracks where the head entry now sits within
+            // the buffer (as a byte offset from `buffer`).
+            (*fc).entry_count -= 1;
+            (*fc).wrap_marker = (new_head as u32).wrapping_sub((*fc).buffer as u32);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use core::mem::MaybeUninit;
+
+    /// A minimal owner whose vtable[1] increments a counter when invoked.
+    #[repr(C)]
+    struct MockOwner {
+        vtable: *const MockVtable,
+        evict_count: u32,
+        last_idx: u32,
+    }
+
+    #[repr(C)]
+    struct MockVtable {
+        slot_0: usize,
+        slot_1: unsafe extern "thiscall" fn(*mut c_void, u32, *mut u8),
+    }
+
+    unsafe extern "thiscall" fn mock_evict(this: *mut c_void, idx: u32, _payload: *mut u8) {
+        let owner = this as *mut MockOwner;
+        (*owner).evict_count += 1;
+        (*owner).last_idx = idx;
+    }
+
+    static MOCK_VTABLE: MockVtable = MockVtable {
+        slot_0: 0,
+        slot_1: mock_evict,
+    };
+
+    /// Build a freshly-zeroed FrameCache with a heap-allocated buffer.
+    /// Returns the cache (heap-allocated, must be freed by the caller).
+    fn make_cache(capacity: u32) -> (*mut SpriteCache, *mut FrameCache, *mut u8) {
+        let buf = unsafe {
+            let layout = core::alloc::Layout::from_size_align(capacity as usize, 4).unwrap();
+            std::alloc::alloc_zeroed(layout)
+        };
+        let fc = Box::leak(Box::new(unsafe {
+            MaybeUninit::<FrameCache>::zeroed().assume_init()
+        })) as *mut FrameCache;
+        unsafe {
+            (*fc).buffer = buf;
+            (*fc).capacity = capacity;
+        }
+        let sc = Box::leak(Box::new(unsafe {
+            MaybeUninit::<SpriteCache>::zeroed().assume_init()
+        })) as *mut SpriteCache;
+        unsafe {
+            (*sc).frame_cache = fc;
+        }
+        (sc, fc, buf)
+    }
+
+    fn free_cache(sc: *mut SpriteCache, fc: *mut FrameCache, buf: *mut u8, capacity: u32) {
+        unsafe {
+            let layout = core::alloc::Layout::from_size_align(capacity as usize, 4).unwrap();
+            std::alloc::dealloc(buf, layout);
+            drop(Box::from_raw(fc));
+            drop(Box::from_raw(sc));
+        }
+    }
+
+    /// Single allocation: header + payload, returns payload start.
+    #[test]
+    fn alloc_single() {
+        let (sc, fc, buf) = make_cache(0x1000);
+        let mut owner = MockOwner {
+            vtable: &MOCK_VTABLE,
+            evict_count: 0,
+            last_idx: 0,
+        };
+        unsafe {
+            let p = frame_cache_allocate(0x100, sc, &mut owner as *mut _ as *mut c_void, 7);
+
+            // Returned pointer is buffer + 0x10
+            assert_eq!(p, buf.add(0x10));
+
+            // Header fields written
+            let entry = buf as *mut FrameCacheEntry;
+            assert_eq!((*entry).payload_size, 0x100 + 8);
+            assert!((*entry).next.is_null());
+            assert_eq!((*entry).frame_idx, 7);
+            assert_eq!((*entry).owner, &mut owner as *mut _ as *mut c_void);
+
+            // Cache bookkeeping
+            assert_eq!((*fc).head_entry, entry);
+            assert_eq!((*fc).tail_entry, entry);
+            assert_eq!((*fc).entry_count, 1);
+            // pad = ((entry_size + 0x13) & ~3) = ((0x100 + 0x13) & ~3) = 0x110
+            assert_eq!((*fc).write_head, 0x110);
+        }
+        free_cache(sc, fc, buf, 0x1000);
+    }
+
+    /// Two allocations chain into the LRU list.
+    #[test]
+    fn alloc_two_chain() {
+        let (sc, fc, buf) = make_cache(0x1000);
+        let mut owner = MockOwner {
+            vtable: &MOCK_VTABLE,
+            evict_count: 0,
+            last_idx: 0,
+        };
+        unsafe {
+            let owner_ptr = &mut owner as *mut _ as *mut c_void;
+            let _p1 = frame_cache_allocate(0x100, sc, owner_ptr, 1);
+            let _p2 = frame_cache_allocate(0x100, sc, owner_ptr, 2);
+
+            let e1 = buf as *mut FrameCacheEntry;
+            let e2 = buf.add(0x110) as *mut FrameCacheEntry;
+            assert_eq!((*e1).next, e2);
+            assert!((*e2).next.is_null());
+            assert_eq!((*fc).head_entry, e1);
+            assert_eq!((*fc).tail_entry, e2);
+            assert_eq!((*fc).entry_count, 2);
+            assert_eq!((*fc).write_head, 0x220);
+        }
+        free_cache(sc, fc, buf, 0x1000);
+    }
+
+    /// Eviction: fill the buffer, then a third alloc that won't fit
+    /// triggers eviction of the oldest entry and re-uses its space at
+    /// the start of the buffer (after wrap).
+    #[test]
+    fn alloc_triggers_eviction_and_wrap() {
+        // pad = 0x110 per entry. Capacity 0x300 → two entries fit at
+        // [0..0x110, 0x110..0x220]. A third 0x100 alloc would need
+        // [0x220..0x330] which exceeds capacity → must evict + wrap.
+        let (sc, fc, buf) = make_cache(0x300);
+        let mut owner = MockOwner {
+            vtable: &MOCK_VTABLE,
+            evict_count: 0,
+            last_idx: 0,
+        };
+        unsafe {
+            let owner_ptr = &mut owner as *mut _ as *mut c_void;
+            let _p1 = frame_cache_allocate(0x100, sc, owner_ptr, 1);
+            let _p2 = frame_cache_allocate(0x100, sc, owner_ptr, 2);
+
+            // Sanity: wrap_marker is still 0 (no eviction yet).
+            assert_eq!((*fc).wrap_marker, 0);
+            assert_eq!((*fc).write_head, 0x220);
+
+            let p3 = frame_cache_allocate(0x100, sc, owner_ptr, 3);
+
+            // Eviction was called once with the first entry's frame_idx.
+            assert_eq!(owner.evict_count, 1);
+            assert_eq!(owner.last_idx, 1);
+
+            // After evicting entry 1, head_entry advanced to entry 2;
+            // wrap_marker = (entry 2 offset) = 0x110.
+            assert_eq!((*fc).wrap_marker, 0x110);
+
+            // Third alloc wrapped to offset 0 (where entry 1 used to be);
+            // p3 should be buf + 0x10.
+            assert_eq!(p3, buf.add(0x10));
+
+            // Bookkeeping: 2 live entries (entry 2, entry 3), entry 3 is tail.
+            assert_eq!((*fc).entry_count, 2);
+            let e2 = buf.add(0x110) as *mut FrameCacheEntry;
+            let e3 = buf as *mut FrameCacheEntry;
+            assert_eq!((*fc).head_entry, e2);
+            assert_eq!((*fc).tail_entry, e3);
+            assert_eq!((*e2).next, e3);
+            assert!((*e3).next.is_null());
+        }
+        free_cache(sc, fc, buf, 0x300);
+    }
+}

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

@@ -0,0 +1,275 @@
+//! LZSS-style decompressor with palette LUT remapping for sprite subframes.
+//!
+//! Pure-Rust port of `Sprite_LZSS_Decode` (0x5B29E0). Used by
+//! [`Sprite__GetFrameForBlit`](super::sprite) and `SpriteBank__GetFrameForBlit`
+//! to lazily decompress sprite subframe pixel data into a `FrameCache`
+//! payload.
+//!
+//! ## Format
+//!
+//! The decoder consumes a stream of source bytes from `src`. Each iteration
+//! reads one byte and dispatches:
+//!
+//! - **Literal** (`src[0] & 0x80 == 0`): emit `lut[src[0]]` to `dst`,
+//!   advance `src` by 1, advance `dst` by 1.
+//!
+//! - **Control** (`src[0] & 0x80 != 0`): the control word is `src[0..2]`,
+//!   interpreted as `(src[0] << 8) | src[1]`.
+//!     - `distance = control & 0x7FF` (11-bit back-reference offset).
+//!     - `nibble = (src[0] >> 3) & 0xF`.
+//!
+//!     Three sub-forms:
+//!
+//!     1. **Short back-ref** (`nibble != 0`): copy `nibble + 2` bytes from
+//!        `dst - distance - 1` to `dst`. Range 3..=17. Advance `src` by 2.
+//!     2. **Long back-ref** (`nibble == 0`, `distance != 0`): read a third
+//!        byte at `src[2]`. Copy `src[2] + 18` bytes from `dst - distance`
+//!        (note the asymmetry — short refs use `-distance - 1`, long refs
+//!        use `-distance`). Range 18..=273. Advance `src` by 3.
+//!     3. **Terminator** (`nibble == 0`, `distance == 0`): exit the loop.
+//!
+//! **Encoding asymmetry**: the encoded `distance` field for a short
+//! back-ref is `real_distance - 1` (the asm's `DEC ECX` between the
+//! `JZ` and the read makes up the difference), but for a long back-ref
+//! it equals `real_distance` directly. The `JZ extended` jumps over
+//! the `DEC ECX` instruction. This was verified from the disassembly
+//! at 0x5B2A13/0x5B2A15 — there is no encoder-side fix-up that would
+//! normalize the two paths.
+//!
+//! ## LUT
+//!
+//! `lut` is a 256-byte palette translation table. For sprites it lives at
+//! `Sprite::palette_data_ptr` (`+0x68`); for sprite banks it's the inline
+//! `SpriteBank::palette_lut` (`+0x30`). Entry 0 is always `0` (transparent
+//! index); entries `1..=palette_count` are mapped runtime palette indices.
+//! See `feedback_layer_sprite_palette.md` for the off-by-one rationale.
+//!
+//! ## Buffer requirements
+//!
+//! - `src` must contain at least 3 bytes per control sequence (the original
+//!   reads `src[2]` unconditionally on the long-backref path).
+//! - `dst` must have already-written bytes at offsets `[-distance - 1, -1]`
+//!   for any short back-ref, or `[-distance, -1]` for any long back-ref.
+//!   Caller responsibility — the decoder does no bounds checking.
+//! - `lut` must point at a 256-byte buffer.
+//!
+//! The original WA function wraps its body in `PUSHAD`/`POPAD` so callers
+//! see no register clobber. The Rust port has no such concern.
+
+/// Decode an LZSS-compressed sprite subframe into `dst`, remapping each
+/// literal byte through `lut` first.
+///
+/// # Safety
+///
+/// - `dst` must point at a writable buffer large enough to hold the
+///   decompressed payload (caller-known via `SpriteSubframeCache::decoded_size`
+///   or `SpriteBankSubframeCache::decoded_size`).
+/// - `src` must contain a well-formed LZSS stream terminated by a
+///   zero-length zero-distance control word.
+/// - `lut` must point at a 256-byte palette translation table.
+/// - Back-references at `dst - distance - 1` (short) or `dst - distance`
+///   (long) must lie within the already-decoded portion of `dst`.
+pub unsafe fn sprite_lzss_decode(mut dst: *mut u8, mut src: *const u8, lut: *const u8) {
+    loop {
+        // ── Literal run ──────────────────────────────────────────────
+        let b: u8 = loop {
+            let b = *src;
+            if b & 0x80 != 0 {
+                break b;
+            }
+            *dst = *lut.add(b as usize);
+            src = src.add(1);
+            dst = dst.add(1);
+        };
+
+        // ── Control word ─────────────────────────────────────────────
+        // CX = src[0]<<8 | src[1]; distance = CX & 0x7FF.
+        let distance = (((b as u32) << 8) | (*src.add(1) as u32)) & 0x7FF;
+        let nibble = ((b as u32) >> 3) & 0xF;
+
+        if nibble != 0 {
+            // ── Short back-ref ───────────────────────────────────────
+            // Asm uses ECX = -distance - 1 for the entire run; copies
+            // happen as `*EDI = [ECX + EDI]` followed by `INC EDI`,
+            // which means each successive write reads one position later.
+            // The total length is `nibble + 2` bytes (range 3..=17).
+            //
+            // The original asm structure does 3 unconditional copies and
+            // then `(nibble - 1)` more in a loop. Equivalent to a flat
+            // loop of `nibble + 2` iterations.
+            let copy_offset = (distance as usize).wrapping_add(1);
+            let total = (nibble as usize) + 2;
+            for _ in 0..total {
+                *dst = *dst.sub(copy_offset);
+                dst = dst.add(1);
+            }
+            src = src.add(2);
+        } else {
+            // ── Terminator or long back-ref ──────────────────────────
+            if distance == 0 {
+                return;
+            }
+            // Long back-ref uses ECX = -distance (NOT decremented — the
+            // asm's `JZ extended` jumps OVER the `DEC ECX`). Length is
+            // `src[2] + 18` (range 18..=273).
+            let len = (*src.add(2) as usize) + 18;
+            let copy_offset = distance as usize;
+            for _ in 0..len {
+                *dst = *dst.sub(copy_offset);
+                dst = dst.add(1);
+            }
+            src = src.add(3);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::sprite_lzss_decode;
+
+    /// Identity LUT — `lut[i] == i`.
+    fn id_lut() -> [u8; 256] {
+        let mut l = [0u8; 256];
+        for i in 0..256 {
+            l[i] = i as u8;
+        }
+        l
+    }
+
+    /// Pure-literal stream of bytes 1..16, terminated.
+    #[test]
+    fn literals_only() {
+        let lut = id_lut();
+        // 16 literals + terminator (0x80, 0x00 → nibble=0, distance=0).
+        let mut src = vec![];
+        for i in 1..=16u8 {
+            src.push(i);
+        }
+        src.push(0x80);
+        src.push(0x00);
+
+        let mut dst = vec![0u8; 16];
+        unsafe {
+            sprite_lzss_decode(dst.as_mut_ptr(), src.as_ptr(), lut.as_ptr());
+        }
+        let expected: Vec<u8> = (1..=16u8).collect();
+        assert_eq!(dst, expected);
+    }
+
+    /// Literals routed through a non-identity LUT.
+    #[test]
+    fn literals_with_lut() {
+        let mut lut = id_lut();
+        lut[0x05] = 0xAA;
+        lut[0x10] = 0xBB;
+
+        let src: Vec<u8> = vec![0x05, 0x10, 0x80, 0x00];
+        let mut dst = vec![0u8; 2];
+        unsafe {
+            sprite_lzss_decode(dst.as_mut_ptr(), src.as_ptr(), lut.as_ptr());
+        }
+        assert_eq!(dst, vec![0xAA, 0xBB]);
+    }
+
+    /// Short back-ref: emit "ABC", then copy 3 bytes from `dst - 3`.
+    ///
+    /// **Encoding asymmetry**: short refs encode `real_distance - 1` (the
+    /// asm's `DEC ECX` adds the +1), while long refs encode the real
+    /// distance directly. So to back up 3 bytes, we encode `2` in the
+    /// distance bits.
+    #[test]
+    fn short_backref_basic() {
+        let lut = id_lut();
+        // nibble = 1 (length = 3), encoded distance = 2 (real = 3).
+        // src[0] = 0x80 | (1 << 3) | ((2 >> 8) & 0x7) = 0x88
+        // src[1] = 2 & 0xFF = 0x02
+        let src: Vec<u8> = vec![b'A', b'B', b'C', 0x88, 0x02, 0x80, 0x00];
+        let mut dst = vec![0u8; 6];
+        unsafe {
+            sprite_lzss_decode(dst.as_mut_ptr(), src.as_ptr(), lut.as_ptr());
+        }
+        assert_eq!(&dst, b"ABCABC");
+    }
+
+    /// Short back-ref length boundary: nibble = 15 → copies 17 bytes.
+    /// Encode `real_distance - 1 = 16` to back up 17 bytes.
+    #[test]
+    fn short_backref_max_length() {
+        let lut = id_lut();
+        // Pre-fill 17 unique bytes, then back-ref:
+        //   nibble = 15 (length 17), encoded distance = 16 (real = 17).
+        let mut src: Vec<u8> = (1..=17u8).collect();
+        // src[0] = 0x80 | (15 << 3) | ((16 >> 8) & 0x7) = 0xF8
+        // src[1] = 16 & 0xFF = 0x10
+        src.push(0xF8);
+        src.push(0x10);
+        src.push(0x80);
+        src.push(0x00);
+
+        let mut dst = vec![0u8; 34];
+        unsafe {
+            sprite_lzss_decode(dst.as_mut_ptr(), src.as_ptr(), lut.as_ptr());
+        }
+        let expected: Vec<u8> = (1..=17u8).chain(1..=17u8).collect();
+        assert_eq!(dst, expected);
+    }
+
+    /// Long back-ref: nibble = 0, distance != 0, length = src[2] + 18.
+    /// Note long-form uses `-distance` (NOT `-distance - 1`).
+    #[test]
+    fn long_backref_basic() {
+        let lut = id_lut();
+        // Pre-fill 20 bytes 1..20, then long back-ref:
+        //   nibble=0, distance=20 (so `-distance` reads dst[-20]=1, etc.)
+        //   src[2] = 0 → length = 18.
+        let mut src: Vec<u8> = (1..=20u8).collect();
+        // src[0] = 0x80 | (0 << 3) | ((20 >> 8) & 0x7) = 0x80
+        // src[1] = 20 & 0xFF = 0x14
+        // src[2] = 0 → length 18
+        src.push(0x80);
+        src.push(0x14);
+        src.push(0x00);
+        src.push(0x80);
+        src.push(0x00);
+
+        let mut dst = vec![0u8; 38];
+        unsafe {
+            sprite_lzss_decode(dst.as_mut_ptr(), src.as_ptr(), lut.as_ptr());
+        }
+        let expected: Vec<u8> = (1..=20u8).chain(1..=18u8).collect();
+        assert_eq!(dst, expected);
+    }
+
+    /// Self-overlapping short back-ref (RLE-style): emit one byte, then
+    /// short-copy with distance = 1 (which becomes `-distance - 1 = -2`,
+    /// a stride-2 read). This isn't classic RLE — verify against the
+    /// asm semantics, not against expectation.
+    ///
+    /// With dst = [X, _, _, ...] and copy_offset = 2:
+    ///   write 1: dst[1] = dst[1-2]  → reads dst[-1] (out of buffer!)
+    ///
+    /// So distance = 1 short-copies are unsafe. Test distance = 0 with the
+    /// nibble path, which `-1` → reads dst[-1]. Also unsafe.
+    /// Skip this test — both edge cases reach outside `dst` and only work
+    /// with valid pre-loaded backing.
+    #[test]
+    fn self_overlap_distance_zero_short() {
+        // Use distance = 0, nibble = 1 → copy_offset = 1, length = 3.
+        // Each iteration: dst[i] = dst[i - 1].
+        // With dst = [42, _, _, _]: yields [42, 42, 42, 42].
+        let lut = id_lut();
+        let src: Vec<u8> = vec![
+            42, // literal
+            // distance=0, nibble=1
+            // src[0] = 0x80 | (1<<3) | 0 = 0x88
+            // src[1] = 0x00
+            0x88, 0x00, // terminator
+            0x80, 0x00,
+        ];
+        let mut dst = vec![0u8; 4];
+        unsafe {
+            sprite_lzss_decode(dst.as_mut_ptr(), src.as_ptr(), lut.as_ptr());
+        }
+        assert_eq!(dst, vec![42, 42, 42, 42]);
+    }
+}

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

@@ -1,8 +1,12 @@
+pub mod frame_cache;
 pub mod gfx_dir;
+pub mod lzss;
 pub mod spr;
 pub mod sprite;
 pub mod sprite_id;
 
+pub use frame_cache::frame_cache_allocate;
+pub use lzss::sprite_lzss_decode;
 pub use spr::{ParsedSprite, SprError, SprHeader};
 pub use sprite::{
     Sprite, SpriteBank, SpriteBankBboxEntry, SpriteBankFrame, SpriteBankSubframeCache,

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

@@ -1358,6 +1358,7 @@ fn install_display() -> Result<(), String> {
             update_palette      => display_vtable::update_palette,
             set_font_palette    => display_vtable::set_font_palette,
             slot 19 => blit_sprite,
+            get_sprite_frame_for_blit => display_vtable::get_sprite_frame_for_blit,
             load_sprite_by_layer => load_sprite_by_layer,
             load_font            => load_font,
             load_font_extension  => load_font_extension,