onedrop_engine/

sprites.rs

//! Sprite (`MILK_IMG.INI`) state and lifecycle.
//!
//! Holds the parsed sprite definitions ([`SpriteDef`]), an active
//! list of running sprite instances ([`ActiveSprite`]), and per-frame
//! state evaluation. Each active sprite owns its own
//! [`MilkEvaluator`] so per-frame equations can write to local
//! `x, y, sx, sy, rot, blendmode, a, r, g, b, done` variables without
//! leaking into the preset evaluator or sibling sprites.
//!
//! The engine ticks the manager each frame after the preset's
//! `per_frame` block (so sprites can read fresh `q1..q32` /
//! `bass / mid / treb` if needed via shared context state, copied in
//! by the engine) and produces a list of [`SpriteRenderInstance`]s the
//! renderer turns into textured quads.

use onedrop_eval::MilkEvaluator;
use onedrop_parser::SpriteDef;
use std::collections::HashMap;
use std::path::{Path, PathBuf};

/// Blend modes the GPU pipeline understands. MD2 specced more
/// (decal, overlay, multiply, …) but corpus sprites overwhelmingly
/// use Alpha or Additive — the renderer's two pipelines cover both.
/// Unknown / unsupported `blendmode` values from the per-frame eval
/// snap to `Alpha`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SpriteBlendMode {
    /// Standard alpha blend (`src.a, 1 - src.a`).
    Alpha,
    /// Additive (`one, one`) — useful for glow / particle effects.
    Additive,
}

/// Per-frame snapshot of one active sprite, fed to the renderer.
/// The renderer turns this into a quad draw via `sprite_pipeline`.
#[derive(Debug, Clone, Copy)]
pub struct SpriteRenderInstance {
    /// Index into the engine's sprite texture pool. The renderer
    /// owns the actual `wgpu::Texture` for each slot.
    pub texture_index: u32,
    /// Centre in normalised screen coords `[0, 1]`, top-left origin.
    pub x: f32,
    pub y: f32,
    /// Per-axis scale relative to the sprite's native pixel size.
    /// `1.0` = native, `2.0` = twice as wide / tall, etc.
    pub sx: f32,
    pub sy: f32,
    /// Rotation in radians, clockwise.
    pub rot: f32,
    /// Tint colour (premultiplied by `a` at draw time).
    pub rgba: [f32; 4],
    /// Blend pipeline to pick. See [`SpriteBlendMode`].
    pub blend: SpriteBlendMode,
    /// `true` on the *one* frame a `burn=1` sprite is finishing: the
    /// renderer is expected to draw it into `render_texture` so it
    /// feeds back through the warp loop. The manager drops the
    /// sprite immediately after.
    pub burn: bool,
}

/// One running sprite instance.
struct ActiveSprite {
    /// Index into [`SpriteManager::defs`] — used to recover the
    /// texture index without re-walking the def list each frame.
    def_index: usize,
    /// Per-instance variable state. The init block runs once on
    /// spawn; per_frame runs every tick.
    eval: MilkEvaluator,
    /// `true` after the first per_frame tick — used to gate the
    /// init block, which mustn't re-run.
    initialised: bool,
    /// Frames since spawn. Exposed to the equations as `frame`.
    frame: u32,
    /// Burn-pending: set on the tick the sprite's `done` variable
    /// goes truthy AND the def had `burn=1`. The renderer reads
    /// this on the *next* render to draw the sprite into
    /// `render_texture` once, then the manager prunes it.
    burn_pending: bool,
    /// `true` once `done` is set and we've already emitted the burn
    /// (if any). Pruned at end-of-frame.
    finished: bool,
}

/// Sprite system: definitions + active instances.
pub struct SpriteManager {
    /// Parsed `MILK_IMG.INI` entries indexed by load order. The
    /// public API targets entries by slot (1-based, matching the
    /// section headers); [`slot_to_index`] converts.
    defs: Vec<SpriteDef>,
    /// Slot → defs-vector position map. Sparse, since users can
    /// author `[img01]` then jump to `[img50]`.
    slot_to_index: HashMap<u32, usize>,
    /// Active sprites — drawn in spawn order so later spawns paint
    /// over earlier ones.
    active: Vec<ActiveSprite>,
    /// Cursor for "cycle to next" (the `K` keybind). Walks the
    /// slot list mod `defs.len()`.
    cycle_cursor: usize,
}

impl Default for SpriteManager {
    fn default() -> Self {
        Self::new()
    }
}

impl SpriteManager {
    pub fn new() -> Self {
        Self {
            defs: Vec::new(),
            slot_to_index: HashMap::new(),
            active: Vec::new(),
            cycle_cursor: 0,
        }
    }

    /// Load a freshly-parsed set of sprite definitions, replacing
    /// any previous load. Doesn't touch the active list — running
    /// sprites keep their `def_index`-back-reference until they
    /// finish naturally, even though the def is gone (we re-resolve
    /// the texture each frame in case the renderer reloaded).
    pub fn load_defs(&mut self, defs: Vec<SpriteDef>) {
        self.slot_to_index.clear();
        for (i, d) in defs.iter().enumerate() {
            self.slot_to_index.insert(d.slot, i);
        }
        self.defs = defs;
        self.cycle_cursor = 0;
    }

    /// Number of loaded sprite definitions (NOT the active count).
    pub fn def_count(&self) -> usize {
        self.defs.len()
    }

    /// Number of sprites currently being drawn each frame.
    pub fn active_count(&self) -> usize {
        self.active.len()
    }

    /// Spawn a sprite by INI slot. Returns `false` if the slot
    /// isn't loaded. Multiple spawns of the same slot stack — that
    /// matches MD2 behaviour and lets users build up effects by
    /// hammering the key.
    pub fn spawn_slot(&mut self, slot: u32) -> bool {
        let Some(&idx) = self.slot_to_index.get(&slot) else {
            return false;
        };
        self.spawn_index(idx);
        true
    }

    fn spawn_index(&mut self, idx: usize) {
        let mut eval = MilkEvaluator::new();
        // Seed the per-sprite variables with MD2's defaults.
        let ctx = eval.context_mut();
        ctx.set("x", 0.5);
        ctx.set("y", 0.5);
        ctx.set("sx", 1.0);
        ctx.set("sy", 1.0);
        ctx.set("rot", 0.0);
        ctx.set("flipx", 0.0);
        ctx.set("flipy", 0.0);
        ctx.set("repeatx", 1.0);
        ctx.set("repeaty", 1.0);
        ctx.set("blendmode", 0.0);
        ctx.set("a", 1.0);
        ctx.set("r", 1.0);
        ctx.set("g", 1.0);
        ctx.set("b", 1.0);
        ctx.set("done", 0.0);
        self.active.push(ActiveSprite {
            def_index: idx,
            eval,
            initialised: false,
            frame: 0,
            burn_pending: false,
            finished: false,
        });
    }

    /// `K` keybind: load the next sprite slot in cyclic order.
    pub fn cycle_next(&mut self) -> Option<u32> {
        if self.defs.is_empty() {
            return None;
        }
        let idx = self.cycle_cursor % self.defs.len();
        let slot = self.defs[idx].slot;
        self.cycle_cursor = (idx + 1) % self.defs.len();
        self.spawn_index(idx);
        Some(slot)
    }

    /// `Shift+K`: pick a slot at random. The caller passes the RNG
    /// seed so we stay deterministic in tests.
    pub fn spawn_random(&mut self, seed: u64) -> Option<u32> {
        if self.defs.is_empty() {
            return None;
        }
        // Tiny LCG — keeps us off the `rand` dep for one call site.
        let mut x = seed
            .wrapping_mul(6364136223846793005)
            .wrapping_add(1442695040888963407);
        x ^= x >> 33;
        let idx = (x as usize) % self.defs.len();
        let slot = self.defs[idx].slot;
        self.spawn_index(idx);
        Some(slot)
    }

    /// `Ctrl+T` and `Delete`: drop every active sprite immediately.
    pub fn clear(&mut self) {
        self.active.clear();
    }

    /// `Delete` variant that only removes the most recent sprite
    /// (last-in-first-out). Returns `true` when something was
    /// removed so the GUI can suppress redundant Delete events on
    /// an already-empty list.
    pub fn pop_most_recent(&mut self) -> bool {
        self.active.pop().is_some()
    }

    /// Advance every active sprite by one frame. Returns the list
    /// of [`SpriteRenderInstance`]s for the renderer.
    ///
    /// `time` is the engine's global clock (seconds, monotonic).
    /// `q_snapshot` is the preset's `q1..q32` after the preset's
    /// `per_frame` block runs, exposed so sprite equations can
    /// piggyback on the preset's audio-reactive computations.
    pub fn tick(&mut self, time: f32, q_snapshot: &[f32; 32]) -> Vec<SpriteRenderInstance> {
        let mut out = Vec::with_capacity(self.active.len());
        for s in self.active.iter_mut() {
            // Push the shared context: `time`, `frame`, `q1..q32`.
            // Per-sprite vars carry across frames inside the
            // evaluator's local scope.
            {
                let ctx = s.eval.context_mut();
                ctx.set_time(time as f64);
                ctx.set_frame(s.frame as f64);
                for (i, q) in q_snapshot.iter().enumerate() {
                    ctx.set(&format!("q{}", i + 1), *q as f64);
                }
            }
            // Init runs once.
            if !s.initialised {
                if let Some(def) = self.defs.get(s.def_index)
                    && !def.init.is_empty()
                {
                    let _ = s.eval.eval(&def.init);
                }
                s.initialised = true;
            }
            // Per-frame.
            if let Some(def) = self.defs.get(s.def_index)
                && !def.per_frame.is_empty()
            {
                let _ = s.eval.eval(&def.per_frame);
            }
            // Read back the snapshot.
            let ctx = s.eval.context();
            let x = ctx.get("x").unwrap_or(0.5) as f32;
            let y = ctx.get("y").unwrap_or(0.5) as f32;
            let sx = ctx.get("sx").unwrap_or(1.0) as f32;
            let sy = ctx.get("sy").unwrap_or(1.0) as f32;
            let rot = ctx.get("rot").unwrap_or(0.0) as f32;
            let blend_int = ctx.get("blendmode").unwrap_or(0.0) as i32;
            let r = ctx.get("r").unwrap_or(1.0) as f32;
            let g = ctx.get("g").unwrap_or(1.0) as f32;
            let b = ctx.get("b").unwrap_or(1.0) as f32;
            let a = ctx.get("a").unwrap_or(1.0).clamp(0.0, 1.0) as f32;
            let done = ctx.get("done").unwrap_or(0.0) != 0.0;

            let blend = match blend_int {
                2 => SpriteBlendMode::Additive,
                _ => SpriteBlendMode::Alpha,
            };

            let def = self.defs.get(s.def_index);
            // `def_index` survives a `load_defs` swap by index but
            // there's a chance the new INI shrinks the vector below
            // the old index. Pretend the sprite is finished in
            // that case so we don't try to draw with a stale
            // pointer.
            let texture_index = def.map(|_| s.def_index as u32).unwrap_or(u32::MAX);
            let burn_flag = def.map(|d| d.burn).unwrap_or(false);

            // Lifecycle decision.
            if done && burn_flag && !s.burn_pending {
                // First "I'm done" tick on a burn sprite — let the
                // renderer paint it into `render_texture` this
                // frame; finish next frame.
                s.burn_pending = true;
                s.finished = true;
            } else if done {
                s.finished = true;
            }

            // Emit the render instance — clamp colour now so the
            // GPU sees premultiplied alpha-safe values.
            let rgba = [
                (r * a).clamp(0.0, 1.0),
                (g * a).clamp(0.0, 1.0),
                (b * a).clamp(0.0, 1.0),
                a,
            ];
            // Always emit while alive — even the burn frame goes out
            // as a render so the texture lands somewhere visible.
            if texture_index != u32::MAX {
                out.push(SpriteRenderInstance {
                    texture_index,
                    x,
                    y,
                    sx,
                    sy,
                    rot,
                    rgba,
                    blend,
                    burn: s.burn_pending,
                });
            }

            s.frame = s.frame.saturating_add(1);
        }
        // Prune finished sprites (burn ones get one frame to render).
        self.active.retain(|s| !s.finished);
        out
    }

    /// Borrow the parsed defs — useful for the renderer's texture
    /// loader (resolve `img=` strings against an XDG sprite dir).
    pub fn defs(&self) -> &[SpriteDef] {
        &self.defs
    }

    /// Path the engine expects sprite assets to live under, relative
    /// to a sprite-bank root. Pure helper, no I/O.
    pub fn resolve_img_path(root: &Path, def: &SpriteDef) -> PathBuf {
        root.join(&def.img)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn def(slot: u32, img: &str, per_frame: &str, burn: bool) -> SpriteDef {
        SpriteDef {
            slot,
            img: img.into(),
            init: String::new(),
            per_frame: per_frame.into(),
            burn,
        }
    }

    #[test]
    fn spawn_and_cycle_walks_defs_in_order() {
        let mut mgr = SpriteManager::new();
        mgr.load_defs(vec![
            def(1, "a.png", "x=0.25;", false),
            def(2, "b.png", "x=0.75;", false),
        ]);
        assert_eq!(mgr.cycle_next(), Some(1));
        assert_eq!(mgr.cycle_next(), Some(2));
        assert_eq!(mgr.cycle_next(), Some(1));
        assert_eq!(mgr.active_count(), 3);
    }

    #[test]
    fn tick_evaluates_per_frame_and_emits_render() {
        let mut mgr = SpriteManager::new();
        mgr.load_defs(vec![def(1, "a.png", "x=0.25; y=0.75;", false)]);
        mgr.spawn_slot(1);
        let instances = mgr.tick(0.0, &[0.0; 32]);
        assert_eq!(instances.len(), 1);
        let i = &instances[0];
        assert!((i.x - 0.25).abs() < 1e-6);
        assert!((i.y - 0.75).abs() < 1e-6);
    }

    #[test]
    fn done_drops_sprite_next_frame() {
        let mut mgr = SpriteManager::new();
        mgr.load_defs(vec![def(1, "a.png", "done=1;", false)]);
        mgr.spawn_slot(1);
        let _ = mgr.tick(0.0, &[0.0; 32]);
        // After tick, sprite is marked finished → pruned.
        assert_eq!(mgr.active_count(), 0);
    }

    #[test]
    fn burn_sprite_emits_one_render_with_burn_flag() {
        let mut mgr = SpriteManager::new();
        mgr.load_defs(vec![def(1, "a.png", "done=1;", true)]);
        mgr.spawn_slot(1);
        let instances = mgr.tick(0.0, &[0.0; 32]);
        assert_eq!(instances.len(), 1);
        assert!(instances[0].burn, "burn=1 + done=1 should set burn flag");
        // Pruned at end of tick.
        assert_eq!(mgr.active_count(), 0);
    }

    #[test]
    fn blendmode_two_maps_to_additive() {
        let mut mgr = SpriteManager::new();
        mgr.load_defs(vec![def(1, "a.png", "blendmode=2;", false)]);
        mgr.spawn_slot(1);
        let i = mgr.tick(0.0, &[0.0; 32]);
        assert_eq!(i[0].blend, SpriteBlendMode::Additive);
    }

    #[test]
    fn unknown_blendmode_falls_back_to_alpha() {
        let mut mgr = SpriteManager::new();
        mgr.load_defs(vec![def(1, "a.png", "blendmode=42;", false)]);
        mgr.spawn_slot(1);
        let i = mgr.tick(0.0, &[0.0; 32]);
        assert_eq!(i[0].blend, SpriteBlendMode::Alpha);
    }

    #[test]
    fn clear_drops_everything() {
        let mut mgr = SpriteManager::new();
        mgr.load_defs(vec![def(1, "a.png", "", false), def(2, "b.png", "", false)]);
        mgr.spawn_slot(1);
        mgr.spawn_slot(2);
        mgr.spawn_slot(1);
        assert_eq!(mgr.active_count(), 3);
        mgr.clear();
        assert_eq!(mgr.active_count(), 0);
    }

    #[test]
    fn pop_most_recent_lifo() {
        let mut mgr = SpriteManager::new();
        mgr.load_defs(vec![
            def(1, "a.png", "x=0.1;", false),
            def(2, "b.png", "x=0.9;", false),
        ]);
        mgr.spawn_slot(1);
        mgr.spawn_slot(2);
        assert!(mgr.pop_most_recent());
        assert_eq!(mgr.active_count(), 1);
        assert!(mgr.pop_most_recent());
        assert!(!mgr.pop_most_recent());
    }

    #[test]
    fn spawn_unknown_slot_returns_false() {
        let mut mgr = SpriteManager::new();
        mgr.load_defs(vec![def(1, "a.png", "", false)]);
        assert!(!mgr.spawn_slot(99));
        assert_eq!(mgr.active_count(), 0);
    }
}