roxlap_formats/
sprite.rs

1//! KV6 sprite — a parsed [`Kv6`] paired with a world-space pose.
2//!
3//! Mirror of voxlap's `vx5sprite` (``) for the kv6
4//! case (`flags & SPRITE_FLAG_KFA == 0`). Pure data — owns the
5//! [`Kv6`] voxel grid plus the four `point3d` fields voxlap calls
6//! `p` (pivot position), `s` (x-basis), `h` (y-basis), `f`
7//! (z-basis), and the bitfield `flags`.
8//!
9//! Rendering lives in `roxlap-core` (`draw_sprite`); this module
10//! only models the data shape so downstream tools (file
11//! converters, model inspectors, asset pipelines) can build and
12//! manipulate sprites without depending on the full renderer.
13//!
14//! Voxlap's 64-byte layout, for reference:
15//!
16//! ```text
17//! point3d p;       // position
18//! int32_t flags;   // bit 0: 0=normal shading
19//!                  // bit 1: 0=kv6data, 1=kfatype
20//!                  // bit 2: 0=normal, 1=invisible
21//!                  // bit 3: 0=z-tested, 1=overlay (no-z)
22//! point3d s;       // x-basis (kv6data.xsiz direction)
23//! kv6data *voxnum; // (or kfatype *kfaptr if flag bit 1 set)
24//! point3d h;       // y-basis
25//! int32_t kfatim;
26//! point3d f;       // z-basis
27//! int32_t okfatim;
28//! ```
29
30use crate::kv6::Kv6;
31
32/// Voxlap's sprite-flags bit 0: disable normal-based face shading.
33pub const SPRITE_FLAG_NO_SHADING: u32 = 1 << 0;
34/// Voxlap's sprite-flags bit 1: voxnum points at a `kfatype`
35/// (animated). When clear (default), points at a `kv6data`.
36pub const SPRITE_FLAG_KFA: u32 = 1 << 1;
37/// Voxlap's sprite-flags bit 2: skip rendering entirely.
38pub const SPRITE_FLAG_INVISIBLE: u32 = 1 << 2;
39/// Voxlap's sprite-flags bit 3: render without z-buffer test.
40pub const SPRITE_FLAG_NO_Z: u32 = 1 << 3;
41
42/// A KV6 voxel sprite positioned in world space.
43///
44/// Mirror of voxlap's `vx5sprite` for the kv6 case
45/// (`flags & SPRITE_FLAG_KFA == 0`; see [`SPRITE_FLAG_KFA`]).
46/// Owns its [`Kv6`] by value. `p` / `s` / `h` / `f` are voxlap's
47/// per-axis world-space basis: `s` is the `kv6.xsiz` direction,
48/// `h` the `ysiz` direction, `f` the `zsiz` direction. For an
49/// axis-aligned sprite, `s = [1,0,0]`, `h = [0,1,0]`,
50/// `f = [0,0,1]`.
51#[derive(Debug, Clone)]
52pub struct Sprite {
53    /// Voxel data + bounding-box pivots. Loaded from a `.kv6`
54    /// file via [`crate::kv6::parse`] or built procedurally.
55    pub kv6: Kv6,
56    /// World-space position of the sprite's pivot (xpiv, ypiv,
57    /// zpiv inside the kv6 maps to this point).
58    pub p: [f32; 3],
59    /// World-space basis vector for the kv6's local +x. Length
60    /// scales the sprite along that axis (typically `1.0` for
61    /// unit-scale).
62    pub s: [f32; 3],
63    /// World-space basis vector for the kv6's local +y.
64    pub h: [f32; 3],
65    /// World-space basis vector for the kv6's local +z.
66    pub f: [f32; 3],
67    /// Voxlap-style flags bitfield. See [`SPRITE_FLAG_NO_SHADING`],
68    /// [`SPRITE_FLAG_KFA`], [`SPRITE_FLAG_INVISIBLE`],
69    /// [`SPRITE_FLAG_NO_Z`].
70    pub flags: u32,
71    /// Voxel-material id (TV stage) applied uniformly to this sprite's
72    /// voxels — indexes the renderer's global
73    /// [`MaterialTable`](crate::material::MaterialTable) for opacity + blend
74    /// mode. `0` (the default) is opaque, so an un-set sprite renders exactly
75    /// as before. See `PORTING-TRANSPARENCY.md`.
76    pub material: u8,
77    /// Per-instance opacity multiplier (TV stage), `0..=255` (`255` =
78    /// unscaled, the default). Scales the material's alpha so an effect can
79    /// fade out by cheap per-frame updates without re-uploading its volume.
80    pub alpha_mul: u8,
81    /// Per-voxel material colour map (TV.3): `(rgb, material_id)` pairs that
82    /// classify this model's voxels into materials by colour — a mixed model
83    /// (opaque frame + glass, bottle + potion). **Empty** (the default) means
84    /// the whole sprite uses [`material`](Self::material) uniformly (the TV.1
85    /// path). See [`crate::material::material_for_color`].
86    pub material_map: Vec<(u32, u8)>,
87}
88
89impl Sprite {
90    /// Convenience constructor for an axis-aligned sprite at
91    /// world position `pos`. Basis is identity, flags = 0
92    /// (kv6 + normal shading + visible + z-tested).
93    ///
94    /// # Examples
95    ///
96    /// ```
97    /// use roxlap_formats::kv6::Kv6;
98    /// use roxlap_formats::sprite::Sprite;
99    ///
100    /// # let kv6 = Kv6 {
101    /// #     xsiz: 1, ysiz: 1, zsiz: 1,
102    /// #     xpiv: 0.5, ypiv: 0.5, zpiv: 0.5,
103    /// #     voxels: vec![], xlen: vec![0], ylen: vec![vec![0]],
104    /// #     palette: None,
105    /// # };
106    /// // ... after `let kv6 = kv6::parse(&bytes)?;` or similar:
107    /// let sprite = Sprite::axis_aligned(kv6, [1024.0, 1024.0, 100.0]);
108    /// assert_eq!(sprite.flags, 0);
109    /// assert_eq!(sprite.s, [1.0, 0.0, 0.0]);
110    /// ```
111    #[must_use]
112    pub fn axis_aligned(kv6: Kv6, pos: [f32; 3]) -> Self {
113        Self {
114            kv6,
115            p: pos,
116            s: [1.0, 0.0, 0.0],
117            h: [0.0, 1.0, 0.0],
118            f: [0.0, 0.0, 1.0],
119            flags: 0,
120            material: 0,
121            alpha_mul: 255,
122            material_map: Vec::new(),
123        }
124    }
125
126    /// Carve a sphere out of this sprite's voxel model, controlling
127    /// the colour of the interior the cut exposes. Thin delegate to
128    /// [`Kv6::carve_sphere_with_colfunc`] — `centre` / `radius`,
129    /// `solid`, and `colfunc` are all in **kv6-local** voxel
130    /// coordinates (the sprite pose `p`/`s`/`h`/`f` is untouched). See
131    /// that method for why the `solid` occupancy predicate is required.
132    pub fn carve_sphere_with_colfunc<S, C>(
133        &mut self,
134        centre: [i32; 3],
135        radius: u32,
136        solid: S,
137        colfunc: C,
138    ) where
139        S: Fn(i32, i32, i32) -> bool,
140        C: Fn(i32, i32, i32) -> u32,
141    {
142        self.kv6
143            .carve_sphere_with_colfunc(centre, radius, solid, colfunc);
144    }
145}
146
147#[cfg(test)]
148mod tests {
149    use super::*;
150
151    #[test]
152    fn carve_sphere_delegates_to_kv6_and_leaves_pose() {
153        const BASE: u32 = 0x8033_4455;
154        let kv6 = Kv6::from_fn_shaded(16, 16, 16, |_, _, _| Some(BASE));
155        let mut sprite = Sprite::axis_aligned(kv6, [10.0, 20.0, 30.0]);
156        let before = sprite.kv6.voxels.len();
157
158        sprite.carve_sphere_with_colfunc([8, 8, 8], 4, |_, _, _| true, |_, _, _| 0x8000_FF00);
159
160        // The hollowed-out shell has more surface voxels than the
161        // solid hull did, so the model definitely changed.
162        assert_ne!(sprite.kv6.voxels.len(), before);
163        // Pose untouched — carving is kv6-local only.
164        assert_eq!(sprite.p, [10.0, 20.0, 30.0]);
165        assert_eq!(sprite.s, [1.0, 0.0, 0.0]);
166    }
167}
roxlap_formats/sprite.rs

roxlap_formats/
sprite.rs
