feat: add .spr header parser with SprHeader and parse_spr_header()

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

@@ -1,10 +1,12 @@
 pub mod gfx_dir;
 pub mod landscape;
 pub mod queue;
+pub mod spr;
 pub mod sprite;
 pub mod turn_order;
 
 pub use landscape::{DirtyRect, PCLandscape};
+pub use spr::{SprError, SprHeader};
 pub use queue::{
     DrawBitmapGlobalCmd, DrawLineStripHeader, DrawPixelCmd, DrawPolygonHeader, DrawRectCmd,
     DrawScaledCmd, DrawSpriteCmd, DrawSpriteOffsetCmd, DrawTextboxLocalCmd, RenderQueue,

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

@@ -0,0 +1,288 @@
+//! `.spr` sprite format parser.
+//!
+//! WA's sprite format stores paletted animated sprites with per-frame metadata.
+//! This module provides both a clean Rust parser (`ParsedSprite`) for tooling
+//! and shared metadata extraction (`parse_spr_header`) used by WormKit hook
+//! replacements.
+
+/// Errors from `.spr` parsing.
+#[derive(Debug)]
+pub enum SprError {
+    /// Data too short to contain required fields.
+    TooShort {
+        expected: usize,
+        actual: usize,
+    },
+    /// Internal structure is inconsistent.
+    InvalidData(&'static str),
+}
+
+impl core::fmt::Display for SprError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            SprError::TooShort { expected, actual } => {
+                write!(f, "spr data too short: need {} bytes, got {}", expected, actual)
+            }
+            SprError::InvalidData(msg) => write!(f, "invalid spr data: {}", msg),
+        }
+    }
+}
+
+/// Parsed metadata and byte offsets into raw `.spr` data.
+///
+/// Produced by `parse_spr_header`. Contains all scalar fields and the byte
+/// offsets needed to locate palette, frame, and bitmap data within the raw
+/// buffer. No heap allocation — just arithmetic on the input slice.
+#[derive(Debug, Clone)]
+pub struct SprHeader {
+    /// Total payload size from `.spr` header (+0x04). Used for global counter.
+    pub data_size: u32,
+    /// Header flags from `.spr` (+0x08).
+    pub header_flags: u16,
+    /// Number of RGB palette entries.
+    pub palette_count: u16,
+    /// Unknown field stored at sprite+0x08.
+    pub unknown_08: u16,
+    /// Animation speed (frames per second).
+    pub fps: u16,
+    /// Sprite flags.
+    pub flags: u16,
+    /// Sprite width in pixels.
+    pub width: u16,
+    /// Sprite height in pixels.
+    pub height: u16,
+    /// Frame count (1 if scaled).
+    pub frame_count: u16,
+    /// Max frames (same as frame_count after processing).
+    pub max_frames: u16,
+    /// Scale X: `((raw >> 8 & 0x7F) << 16) >> 5`, or 0 if not scaled.
+    pub scale_x: u32,
+    /// Scale Y: `((raw & 0x7F) << 16) >> 5`, or 0 if not scaled.
+    pub scale_y: u32,
+    /// True if the frame_count word encoded scaling instead of a count.
+    pub is_scaled: bool,
+    /// Number of secondary frames (0 if header_flags & 0x4000 is clear).
+    pub secondary_frame_count: u16,
+    /// Byte offset of RGB palette data (3 bytes per entry).
+    pub palette_offset: usize,
+    /// Byte offset of secondary frame table (0 if none).
+    pub secondary_frame_offset: usize,
+    /// Byte offset of main SpriteFrame metadata array.
+    pub frame_meta_offset: usize,
+    /// Byte offset of bitmap pixel data.
+    pub bitmap_offset: usize,
+    /// Size of bitmap pixel data in bytes.
+    pub bitmap_size: usize,
+}
+
+/// Align `offset` up to the next 4-byte boundary.
+fn align4(offset: usize) -> usize {
+    (offset + 3) & !3
+}
+
+/// Parse `.spr` header and compute data region offsets.
+///
+/// This is a pure function with no WA dependencies. Both `ParsedSprite::parse`
+/// and the WormKit ProcessSprite hook build on this.
+pub fn parse_spr_header(data: &[u8]) -> Result<SprHeader, SprError> {
+    // Minimum: 4 (unused) + 4 (data_size) + 2 (header_flags) + 2 (palette_count) = 12
+    if data.len() < 12 {
+        return Err(SprError::TooShort { expected: 12, actual: data.len() });
+    }
+
+    let data_size = u32::from_le_bytes([data[4], data[5], data[6], data[7]]);
+    let header_flags = u16::from_le_bytes([data[8], data[9]]);
+    let palette_count = u16::from_le_bytes([data[10], data[11]]);
+
+    let palette_offset = 12; // 0x0C
+    let palette_end = palette_offset + palette_count as usize * 3;
+
+    if data.len() < palette_end {
+        return Err(SprError::TooShort { expected: palette_end, actual: data.len() });
+    }
+
+    let mut cursor = palette_end;
+
+    // Secondary frame table (if header_flags & 0x4000)
+    let mut secondary_frame_count: u16 = 0;
+    let mut secondary_frame_offset: usize = 0;
+
+    if header_flags & 0x4000 != 0 {
+        if data.len() < cursor + 2 {
+            return Err(SprError::TooShort { expected: cursor + 2, actual: data.len() });
+        }
+        secondary_frame_count = u16::from_le_bytes([data[cursor], data[cursor + 1]]);
+        cursor = align4(cursor + 2);
+        secondary_frame_offset = cursor;
+        cursor += secondary_frame_count as usize * 12;
+    }
+
+    // Main frame header (12 bytes)
+    if data.len() < cursor + 12 {
+        return Err(SprError::TooShort { expected: cursor + 12, actual: data.len() });
+    }
+
+    let unknown_08 = u16::from_le_bytes([data[cursor], data[cursor + 1]]);
+    let fps = u16::from_le_bytes([data[cursor + 2], data[cursor + 3]]);
+    let flags = u16::from_le_bytes([data[cursor + 4], data[cursor + 5]]);
+    let width = u16::from_le_bytes([data[cursor + 6], data[cursor + 7]]);
+    let height = u16::from_le_bytes([data[cursor + 8], data[cursor + 9]]);
+    let frame_count_raw = u16::from_le_bytes([data[cursor + 10], data[cursor + 11]]);
+
+    cursor += 12;
+
+    // Scale processing
+    let (frame_count, max_frames, scale_x, scale_y, is_scaled) =
+        if (frame_count_raw as i16) < 0 {
+            let sx = (((frame_count_raw >> 8) & 0x7F) as u32) << 16 >> 5;
+            let sy = ((frame_count_raw & 0x7F) as u32) << 16 >> 5;
+            (1u16, 1u16, sx, sy, true)
+        } else {
+            (frame_count_raw, frame_count_raw, 0u32, 0u32, false)
+        };
+
+    // Frame metadata (aligned to 4 bytes)
+    let frame_meta_offset = align4(cursor);
+    let bitmap_offset = frame_meta_offset + frame_count as usize * 12;
+
+    let bitmap_size = if data.len() > bitmap_offset {
+        data.len() - bitmap_offset
+    } else {
+        0
+    };
+
+    Ok(SprHeader {
+        data_size,
+        header_flags,
+        palette_count,
+        unknown_08,
+        fps,
+        flags,
+        width,
+        height,
+        frame_count,
+        max_frames,
+        scale_x,
+        scale_y,
+        is_scaled,
+        secondary_frame_count,
+        palette_offset,
+        secondary_frame_offset,
+        frame_meta_offset,
+        bitmap_offset,
+        bitmap_size,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Build a minimal single-frame .spr with given dimensions and palette.
+    fn make_spr(width: u16, height: u16, palette_count: u16, frame_count: u16) -> Vec<u8> {
+        let mut data = Vec::new();
+
+        // +0x00: unused magic
+        data.extend_from_slice(&0u32.to_le_bytes());
+        // +0x04: data_size (we'll fix up later)
+        let data_size_pos = data.len();
+        data.extend_from_slice(&0u32.to_le_bytes());
+        // +0x08: header_flags
+        data.extend_from_slice(&0u16.to_le_bytes());
+        // +0x0A: palette_entry_count
+        data.extend_from_slice(&palette_count.to_le_bytes());
+        // +0x0C: palette RGB entries (all zeros)
+        for _ in 0..palette_count {
+            data.extend_from_slice(&[0u8; 3]);
+        }
+
+        // Main frame header (12 bytes)
+        data.extend_from_slice(&0u16.to_le_bytes()); // unknown_08
+        data.extend_from_slice(&10u16.to_le_bytes()); // fps = 10
+        data.extend_from_slice(&0u16.to_le_bytes()); // flags
+        data.extend_from_slice(&width.to_le_bytes());
+        data.extend_from_slice(&height.to_le_bytes());
+        data.extend_from_slice(&frame_count.to_le_bytes());
+
+        // Align to 4 bytes
+        while data.len() % 4 != 0 {
+            data.push(0);
+        }
+
+        // Frame metadata (12 bytes per frame)
+        for i in 0..frame_count {
+            let offset = i as u32 * width as u32 * height as u32;
+            data.extend_from_slice(&offset.to_le_bytes()); // bitmap_offset
+            data.extend_from_slice(&0u16.to_le_bytes()); // start_x
+            data.extend_from_slice(&0u16.to_le_bytes()); // start_y
+            data.extend_from_slice(&width.to_le_bytes()); // end_x
+            data.extend_from_slice(&height.to_le_bytes()); // end_y
+        }
+
+        // Bitmap data (width * height * frame_count bytes)
+        let bitmap_bytes = width as usize * height as usize * frame_count as usize;
+        data.resize(data.len() + bitmap_bytes, 0);
+
+        // Fix up data_size (everything from +4 onward)
+        let total = (data.len() - 4) as u32;
+        data[data_size_pos..data_size_pos + 4].copy_from_slice(&total.to_le_bytes());
+
+        data
+    }
+
+    #[test]
+    fn parse_single_frame() {
+        let data = make_spr(32, 16, 4, 1);
+        let hdr = parse_spr_header(&data).unwrap();
+
+        assert_eq!(hdr.width, 32);
+        assert_eq!(hdr.height, 16);
+        assert_eq!(hdr.fps, 10);
+        assert_eq!(hdr.palette_count, 4);
+        assert_eq!(hdr.frame_count, 1);
+        assert!(!hdr.is_scaled);
+        assert_eq!(hdr.scale_x, 0);
+        assert_eq!(hdr.scale_y, 0);
+        assert_eq!(hdr.secondary_frame_count, 0);
+        assert_eq!(hdr.palette_offset, 12);
+        assert!(hdr.frame_meta_offset > 0);
+        assert!(hdr.bitmap_offset > hdr.frame_meta_offset);
+    }
+
+    #[test]
+    fn parse_multi_frame() {
+        let data = make_spr(8, 8, 2, 5);
+        let hdr = parse_spr_header(&data).unwrap();
+
+        assert_eq!(hdr.frame_count, 5);
+        assert_eq!(hdr.max_frames, 5);
+        // 5 frames * 12 bytes each = 60 bytes of frame metadata
+        assert_eq!(hdr.bitmap_offset - hdr.frame_meta_offset, 60);
+    }
+
+    #[test]
+    fn parse_scaled_sprite() {
+        // frame_count_raw = 0xA050: bit15 set, scale_x_raw = 0x20, scale_y_raw = 0x50
+        let mut data = make_spr(32, 32, 0, 1);
+        // Overwrite frame_count_raw in the main frame header
+        // palette_count = 0, so palette_end = 12
+        // main frame header starts at 12, frame_count is at offset 10 within it = byte 22
+        data[22] = 0x50; // low byte
+        data[23] = 0xA0; // high byte (bit 15 set)
+
+        let hdr = parse_spr_header(&data).unwrap();
+
+        assert!(hdr.is_scaled);
+        assert_eq!(hdr.frame_count, 1);
+        assert_eq!(hdr.max_frames, 1);
+        // scale_x = (0x20 << 16) >> 5 = 0x200000 >> 5 = 0x10000
+        assert_eq!(hdr.scale_x, (0x20u32 << 16) >> 5);
+        // scale_y = (0x50 << 16) >> 5 = 0x500000 >> 5 = 0x28000
+        assert_eq!(hdr.scale_y, (0x50u32 << 16) >> 5);
+    }
+
+    #[test]
+    fn parse_too_short() {
+        assert!(parse_spr_header(&[0; 4]).is_err());
+    }
+}