onedrop_parser/

milk_img_ini.rs

//! Parser for `MILK_IMG.INI` — MilkDrop's sprite definition file.
//!
//! The MilkDrop sprite system (key `K`) loads up to 100 indexed sprites
//! from a single INI file. Each sprite entry references an image file
//! and carries an `init` block plus up to 8 per-frame equation blocks
//! (`code_1`..`code_8`). At runtime the per-frame block updates the
//! sprite's `x, y, sx, sy, rot, blendmode, a, r, g, b, …` variables,
//! and the renderer draws a textured quad accordingly.
//!
//! File shape (lifted from `winamp_milkdrop_help.txt`):
//!
//! ```text
//! [img01]
//! img=sprite.tga
//! init_1=foo = 0.5;
//! code_1=x = .5 + sin(time)*.3;
//! code_2=y = .5 + cos(time)*.3;
//! code_3=
//! ...
//! code_8=
//! burn=0
//!
//! [img02]
//! img=other.png
//! ...
//! ```
//!
//! Per-frame variable contract (the MilkDrop sprite VM exposes these
//! to the equations — names handled by the engine, not the parser):
//!
//! - `x, y`         : centre position in `[0, 1]` (top-left origin).
//! - `sx, sy`       : per-axis scale (1.0 = native sprite size).
//! - `rot`          : rotation in radians.
//! - `flipx, flipy` : 0/1 mirror toggles.
//! - `repeatx, repeaty`: tile counts for `> 1`; 1 = single quad.
//! - `blendmode`    : 0=alpha, 1=decal, 2=additive (others rarely used).
//! - `a, r, g, b`   : uniform tint (a alpha, rgb multiplier).
//! - `a1..a4, r1..r4, g1..g4, b1..b4`: per-corner colour (gradient).
//! - `time, frame`  : passthrough from the engine.
//! - `done`         : write 1 to mark the sprite for removal.
//!
//! The parser is liberal: unknown keys, bad section names, missing
//! `img=` fields are simply skipped (matching MD2's tolerant load),
//! returning whatever valid entries it could extract.

use crate::error::Result;

/// A single sprite slot parsed from a `[imgNN]` section.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct SpriteDef {
    /// 1-based slot index from the section header (`[img01]` → `1`).
    /// Slot 0 is reserved (MD2 used 1..=100). Indices are kept so the
    /// keymap UX can target a specific slot ("press `5` after `K`
    /// to load slot 5" was the historical chord on Windows).
    pub slot: u32,
    /// Image file name as referenced in the INI (`sprite.tga`).
    /// Loading + path resolution is the engine's responsibility —
    /// keeping the raw string here decouples the parser from disk
    /// I/O and lets tests assert on the parsed shape directly.
    pub img: String,
    /// Optional `init_1=` block: one-shot equations evaluated at
    /// sprite spawn. Empty string when absent.
    pub init: String,
    /// `code_1`..`code_8` per-frame equation blocks, joined into a
    /// single semicolon-delimited string. MD2's 8-slot split was
    /// purely a workaround for the 256-char-per-key limit of its
    /// INI parser; the evaluator sees them as one block.
    pub per_frame: String,
    /// `burn=1` makes the sprite render once into `render_texture`
    /// (so it feeds back through the warp loop) and then mark itself
    /// for removal on the next frame.
    pub burn: bool,
}

/// Parse a `MILK_IMG.INI` file body. Returns one [`SpriteDef`] per
/// `[imgNN]` section that carries a non-empty `img=` field. Sections
/// whose name doesn't match the expected pattern, sections with no
/// image, and unknown keys are silently dropped (matches MD2's
/// fail-open behaviour — a malformed entry shouldn't break the bank).
///
/// The returned vector is sorted by slot index ascending so callers
/// can index it without re-sorting; gaps in the slot range are
/// preserved (the index isn't densified).
pub fn parse_milk_img_ini(input: &str) -> Result<Vec<SpriteDef>> {
    let mut out: Vec<SpriteDef> = Vec::new();
    let mut current: Option<SpriteDef> = None;
    let mut code_blocks: [String; 8] = Default::default();

    let flush = |out: &mut Vec<SpriteDef>, mut def: SpriteDef, code: &mut [String; 8]| {
        // Stitch code_1..code_8 into one block at flush time. Drop
        // empty blocks so the evaluator doesn't see dangling `;`.
        let joined: Vec<&str> = code
            .iter()
            .map(|s| s.trim())
            .filter(|s| !s.is_empty())
            .collect();
        if !joined.is_empty() {
            def.per_frame = joined.join("; ");
        }
        *code = Default::default();
        if !def.img.is_empty() {
            out.push(def);
        }
    };

    for raw_line in input.lines() {
        // Strip comments. MD2 uses `;` AND `//`; either at start of
        // a line is a full-line comment. We don't strip inline
        // semicolons inside `code_N=` values — those are equation
        // separators, not comments.
        let line = raw_line.trim();
        if line.is_empty() || line.starts_with("//") {
            continue;
        }
        if line.starts_with(';') {
            // Section-leading ';' is a comment, but `code_1=a;b` has
            // semicolons as separators. Only strip when the entire
            // line starts with one.
            continue;
        }

        // Section header.
        if let Some(rest) = line.strip_prefix('[').and_then(|l| l.strip_suffix(']')) {
            // Flush previous section first.
            if let Some(def) = current.take() {
                flush(&mut out, def, &mut code_blocks);
            }
            // Parse the [imgNN] header. Accept `img01`, `IMG12`, etc.
            let lower = rest.to_ascii_lowercase();
            if let Some(num) = lower.strip_prefix("img") {
                if let Ok(slot) = num.trim_start_matches('0').parse::<u32>() {
                    current = Some(SpriteDef {
                        slot,
                        ..Default::default()
                    });
                } else if num.trim_start_matches('0').is_empty() {
                    // `[img00]` → slot 0 (technically reserved but accept).
                    current = Some(SpriteDef::default());
                }
            }
            continue;
        }

        // Key=value inside the current section.
        let Some(eq) = line.find('=') else { continue };
        let key = line[..eq].trim().to_ascii_lowercase();
        let value = line[eq + 1..].trim().to_string();
        let Some(def) = current.as_mut() else {
            continue;
        };

        match key.as_str() {
            "img" => def.img = value,
            "init_1" | "init" => def.init = value,
            "burn" => def.burn = value.trim() != "0" && !value.trim().is_empty(),
            other => {
                if let Some(idx_str) = other.strip_prefix("code_")
                    && let Ok(idx) = idx_str.parse::<usize>()
                    && (1..=8).contains(&idx)
                {
                    code_blocks[idx - 1] = value;
                }
                // Unknown keys are silently dropped (MD2 fail-open).
            }
        }
    }
    // Final section.
    if let Some(def) = current.take() {
        flush(&mut out, def, &mut code_blocks);
    }
    out.sort_by_key(|s| s.slot);
    Ok(out)
}

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

    #[test]
    fn parses_single_sprite_with_all_keys() {
        let input = "\
[img01]
img=stars.tga
init_1=foo=0.5;
code_1=x = .5 + sin(time)*.3;
code_2=y = .5 + cos(time)*.3;
burn=1
";
        let sprites = parse_milk_img_ini(input).unwrap();
        assert_eq!(sprites.len(), 1);
        assert_eq!(sprites[0].slot, 1);
        assert_eq!(sprites[0].img, "stars.tga");
        assert_eq!(sprites[0].init, "foo=0.5;");
        assert_eq!(
            sprites[0].per_frame,
            "x = .5 + sin(time)*.3;; y = .5 + cos(time)*.3;"
        );
        assert!(sprites[0].burn);
    }

    #[test]
    fn drops_sections_with_no_img() {
        // No `img=` line → silently dropped (MD2 fail-open).
        let input = "\
[img02]
code_1=x = .5;
";
        let sprites = parse_milk_img_ini(input).unwrap();
        assert!(sprites.is_empty());
    }

    #[test]
    fn sorts_by_slot_ascending() {
        let input = "\
[img03]
img=c.png
[img01]
img=a.png
[img02]
img=b.png
";
        let sprites = parse_milk_img_ini(input).unwrap();
        let slots: Vec<u32> = sprites.iter().map(|s| s.slot).collect();
        assert_eq!(slots, vec![1, 2, 3]);
    }

    #[test]
    fn empty_code_blocks_are_skipped_in_join() {
        let input = "\
[img01]
img=x.png
code_1=a=1;
code_3=b=2;
code_5=
";
        let sprites = parse_milk_img_ini(input).unwrap();
        // `code_2`, `code_4`, `code_5` are empty → only `a=1; b=2`
        // makes it through.
        assert_eq!(sprites[0].per_frame, "a=1;; b=2;");
    }

    #[test]
    fn comment_lines_and_unknown_keys_are_tolerated() {
        let input = "\
; this is a comment
// also a comment
[img05]
img=foo.png
weirdkey=ignore me
burn=0
";
        let sprites = parse_milk_img_ini(input).unwrap();
        assert_eq!(sprites.len(), 1);
        assert_eq!(sprites[0].slot, 5);
        assert!(!sprites[0].burn);
    }

    #[test]
    fn burn_is_truthy_on_any_nonzero_value() {
        let input = "\
[img01]
img=a.png
burn=1
[img02]
img=b.png
burn=yes
[img03]
img=c.png
burn=0
[img04]
img=d.png
";
        let sprites = parse_milk_img_ini(input).unwrap();
        assert!(sprites[0].burn);
        assert!(sprites[1].burn);
        assert!(!sprites[2].burn);
        assert!(!sprites[3].burn);
    }

    #[test]
    fn returns_empty_for_empty_input() {
        assert!(parse_milk_img_ini("").unwrap().is_empty());
    }
}