Download crates/openwa-core/src/render/sprite/spr.rs from nmarshall/wormz-a: direct link, hf CLI and curl.
- Browser
- Download file 17.9 kB
-
https://huggingface.co/nmarshall/wormz-a/resolve/main/crates/openwa-core/src/render/sprite/spr.rs
- Command line
-
hf download hf://nmarshall/wormz-a/crates/openwa-core/src/render/sprite/spr.rs
-
curl -L -o spr.rs https://huggingface.co/nmarshall/wormz-a/resolve/main/crates/openwa-core/src/render/sprite/spr.rs
17.9 kB
| //! `.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 hook | |
| //! replacements in openwa-dll. | |
| use crate::render::sprite::SpriteFrame; | |
| /// Errors from `.spr` parsing. | |
| 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. | |
| 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 ProcessSprite hook replacement 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; | |
| if data.len() < cursor { | |
| return Err(SprError::TooShort { | |
| expected: cursor, | |
| actual: data.len(), | |
| }); | |
| } | |
| } | |
| // 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; | |
| if data.len() < bitmap_offset { | |
| return Err(SprError::TooShort { | |
| expected: bitmap_offset, | |
| actual: data.len(), | |
| }); | |
| } | |
| 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, | |
| }) | |
| } | |
| /// A fully parsed `.spr` sprite with owned data. | |
| /// | |
| /// Contains raw RGB palette entries (not remapped to WA's display palette), | |
| /// raw bitmap pixel indices, and frame metadata. Suitable for standalone | |
| /// tooling, tests, and debugging. | |
| /// | |
| /// For hook replacements in openwa-dll, `parse_spr_header` is used directly | |
| /// with in-place buffer operations instead. | |
| pub struct ParsedSprite { | |
| /// Unknown field at sprite+0x08. | |
| pub unknown_08: u16, | |
| /// Animation frames per second. | |
| pub fps: u16, | |
| /// Sprite flags. | |
| pub flags: u16, | |
| /// Header flags from `.spr` file. | |
| pub header_flags: u16, | |
| /// Sprite width in pixels. | |
| pub width: u16, | |
| /// Sprite height in pixels. | |
| pub height: u16, | |
| /// Number of animation frames. | |
| pub frame_count: u16, | |
| /// Maximum frame count. | |
| pub max_frames: u16, | |
| /// Scale X (`(raw << 16) >> 5`), or 0 if not scaled. | |
| pub scale_x: u32, | |
| /// Scale Y (`(raw << 16) >> 5`), or 0 if not scaled. | |
| pub scale_y: u32, | |
| /// Whether the sprite uses scaling instead of animation. | |
| pub is_scaled: bool, | |
| /// RGB palette entries (3 bytes each). NOT remapped to display palette. | |
| pub palette: Vec<[u8; 3]>, | |
| /// Per-frame metadata (bounding box + bitmap offset). | |
| pub frames: Vec<SpriteFrame>, | |
| /// Secondary frame table (non-empty iff header_flags & 0x4000). | |
| pub secondary_frames: Vec<SpriteFrame>, | |
| /// Bitmap pixel data — 8-bit indices into the sprite's local palette. | |
| pub bitmap: Vec<u8>, | |
| /// Total data size from `.spr` header (for global counter updates). | |
| pub data_size: u32, | |
| } | |
| impl ParsedSprite { | |
| /// Parse a `.spr` file from raw bytes. | |
| /// | |
| /// Returns owned data with no WA runtime dependencies. | |
| pub fn parse(data: &[u8]) -> Result<Self, SprError> { | |
| let hdr = parse_spr_header(data)?; | |
| // Extract palette RGB triples | |
| let mut palette = Vec::with_capacity(hdr.palette_count as usize); | |
| let mut offset = hdr.palette_offset; | |
| for _ in 0..hdr.palette_count { | |
| palette.push([data[offset], data[offset + 1], data[offset + 2]]); | |
| offset += 3; | |
| } | |
| // Extract secondary frames | |
| let mut secondary_frames = Vec::new(); | |
| if hdr.secondary_frame_count > 0 { | |
| secondary_frames.reserve(hdr.secondary_frame_count as usize); | |
| let mut off = hdr.secondary_frame_offset; | |
| for _ in 0..hdr.secondary_frame_count { | |
| secondary_frames.push(read_sprite_frame(data, off)); | |
| off += 12; | |
| } | |
| } | |
| // Extract main frames | |
| let mut frames = Vec::with_capacity(hdr.frame_count as usize); | |
| let mut off = hdr.frame_meta_offset; | |
| for _ in 0..hdr.frame_count { | |
| frames.push(read_sprite_frame(data, off)); | |
| off += 12; | |
| } | |
| // Extract bitmap data | |
| let bitmap_end = data.len().min(hdr.bitmap_offset + hdr.bitmap_size); | |
| let bitmap = data[hdr.bitmap_offset..bitmap_end].to_vec(); | |
| Ok(ParsedSprite { | |
| unknown_08: hdr.unknown_08, | |
| fps: hdr.fps, | |
| flags: hdr.flags, | |
| header_flags: hdr.header_flags, | |
| width: hdr.width, | |
| height: hdr.height, | |
| frame_count: hdr.frame_count, | |
| max_frames: hdr.max_frames, | |
| scale_x: hdr.scale_x, | |
| scale_y: hdr.scale_y, | |
| is_scaled: hdr.is_scaled, | |
| palette, | |
| frames, | |
| secondary_frames, | |
| bitmap, | |
| data_size: hdr.data_size, | |
| }) | |
| } | |
| } | |
| /// Read a SpriteFrame from 12 bytes at the given offset. | |
| fn read_sprite_frame(data: &[u8], off: usize) -> SpriteFrame { | |
| SpriteFrame { | |
| bitmap_offset: u32::from_le_bytes([data[off], data[off + 1], data[off + 2], data[off + 3]]), | |
| start_x: u16::from_le_bytes([data[off + 4], data[off + 5]]), | |
| start_y: u16::from_le_bytes([data[off + 6], data[off + 7]]), | |
| end_x: u16::from_le_bytes([data[off + 8], data[off + 9]]), | |
| end_y: u16::from_le_bytes([data[off + 10], data[off + 11]]), | |
| } | |
| } | |
| 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 | |
| } | |
| 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); | |
| } | |
| 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); | |
| } | |
| 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); | |
| } | |
| fn parse_too_short() { | |
| assert!(parse_spr_header(&[0; 4]).is_err()); | |
| } | |
| fn parsed_sprite_single_frame() { | |
| let mut data = make_spr(4, 4, 3, 1); | |
| // Fill palette with known RGB values | |
| data[12] = 0xFF; | |
| data[13] = 0x00; | |
| data[14] = 0x00; // entry 0: red | |
| data[15] = 0x00; | |
| data[16] = 0xFF; | |
| data[17] = 0x00; // entry 1: green | |
| data[18] = 0x00; | |
| data[19] = 0x00; | |
| data[20] = 0xFF; // entry 2: blue | |
| let parsed = ParsedSprite::parse(&data).unwrap(); | |
| assert_eq!(parsed.width, 4); | |
| assert_eq!(parsed.height, 4); | |
| assert_eq!(parsed.palette.len(), 3); | |
| assert_eq!(parsed.palette[0], [0xFF, 0x00, 0x00]); | |
| assert_eq!(parsed.palette[1], [0x00, 0xFF, 0x00]); | |
| assert_eq!(parsed.palette[2], [0x00, 0x00, 0xFF]); | |
| assert_eq!(parsed.frames.len(), 1); | |
| assert_eq!(parsed.bitmap.len(), 16); // 4*4 pixels | |
| } | |
| fn parsed_sprite_secondary_frames() { | |
| let mut data = Vec::new(); | |
| // Header | |
| data.extend_from_slice(&0u32.to_le_bytes()); // unused | |
| data.extend_from_slice(&0u32.to_le_bytes()); // data_size (fix later) | |
| data.extend_from_slice(&0x4000u16.to_le_bytes()); // header_flags: secondary frames | |
| data.extend_from_slice(&0u16.to_le_bytes()); // palette_count = 0 | |
| // Secondary frame table | |
| data.extend_from_slice(&2u16.to_le_bytes()); // 2 secondary frames | |
| // Align to 4 bytes | |
| while data.len() % 4 != 0 { | |
| data.push(0); | |
| } | |
| // 2 secondary SpriteFrame entries (12 bytes each) | |
| for _ in 0..2 { | |
| data.extend_from_slice(&[0u8; 12]); | |
| } | |
| // Main frame header | |
| data.extend_from_slice(&0u16.to_le_bytes()); // unknown_08 | |
| data.extend_from_slice(&15u16.to_le_bytes()); // fps | |
| data.extend_from_slice(&0u16.to_le_bytes()); // flags | |
| data.extend_from_slice(&8u16.to_le_bytes()); // width | |
| data.extend_from_slice(&8u16.to_le_bytes()); // height | |
| data.extend_from_slice(&1u16.to_le_bytes()); // frame_count | |
| while data.len() % 4 != 0 { | |
| data.push(0); | |
| } | |
| // 1 main SpriteFrame | |
| data.extend_from_slice(&0u32.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(&8u16.to_le_bytes()); // end_x | |
| data.extend_from_slice(&8u16.to_le_bytes()); // end_y | |
| // Bitmap (8*8 = 64 bytes) | |
| data.resize(data.len() + 64, 0); | |
| // Fix data_size | |
| let total = (data.len() - 4) as u32; | |
| data[4..8].copy_from_slice(&total.to_le_bytes()); | |
| let parsed = ParsedSprite::parse(&data).unwrap(); | |
| assert_eq!(parsed.secondary_frames.len(), 2); | |
| assert_eq!(parsed.frames.len(), 1); | |
| assert_eq!(parsed.header_flags, 0x4000); | |
| } | |
| } | |