Going-Commando/crates/gc-formats/src/tie.rs

//! Tie: instanced static props -- the environment sitting on the terrain.
//!
//! Spec: `docs/formats/tie.md`.
//!
//! A *class* is one prop shape (a crate, a pipe run, a railing); *instances*
//! place copies of it in the level. The class tables live in the core index and
//! the geometry sits in `core_data`, addressed by byte offset.
//!
//! # What is decoded here, and what is not
//!
//! The reference's class header is 0x80 bytes. RAC2 agrees with it only over
//! the first `0x48`: the per-LOD packet offsets, the three LOD distances and
//! `o_class` all check out on every class on every level. From `0x48` on, the
//! RAC1 fields do **not** describe RAC2 data -- `lod_info` reads back as noise,
//! and `packet_count` and `texture_count` are zero on every class examined.
//!
//! So this module decodes the part that is verified and stops there. Guessing
//! the remainder would repeat the pattern this project keeps running into: a
//! field order that produces plausible output and is wrong.
//!
//! Evidence for what is decoded, over 320 classes across five levels:
//!
//! * `o_class` at `0x44` equals the core index's class number: **320 of 320**.
//!   A coincidence is not a plausible explanation for that.
//! * the LOD distances are ordered `0 < near < mid < far`: 315 of 320. The
//!   five exceptions are not yet explained and are worth chasing.

use crate::buf::{Buf, Result};

/// Bytes of a tie class header that RAC2 and RAC1 agree on.
pub const TIE_CLASS_HEADER_MATCHED: usize = 0x48;

/// A tie class header, decoded as far as the two games agree.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct TieClassHeader {
    /// `0x00`: packet data offsets for LOD 0 (highest detail), 1 and 2.
    ///
    /// Meaning confirmed only by being small, ordered and inside the lump; the
    /// packet structure itself is not decoded yet.
    pub packets: [i32; 3],
    /// `0x10`, `0x14`, `0x18`: LOD switch distances in world units.
    pub near_dist: f32,
    pub mid_dist: f32,
    pub far_dist: f32,
    /// `0x44`: the class's own number.
    ///
    /// Matches the core index's `o_class` for the class, which is what makes
    /// the header base trustworthy.
    pub o_class: i32,
}

impl TieClassHeader {
    /// Parse the agreed-on prefix. Needs `TIE_CLASS_HEADER_MATCHED` bytes.
    pub fn parse(bytes: &[u8]) -> Result<TieClassHeader> {
        let mut b = Buf::new(bytes);
        let mut packets = [0i32; 3];
        for slot in packets.iter_mut() {
            *slot = b.i32("tie packet offset")?;
        }
        // 0x0c: the 64 light-slot normals offset. Read past, not decoded.
        b.skip(4, "tie normals offset")?;
        let near_dist = b.f32("tie near distance")?;
        let mid_dist = b.f32("tie mid distance")?;
        let far_dist = b.f32("tie far distance")?;
        // 0x1c..0x44: the word TieProc reuses as a per-frame counter, the LOD
        // packet counts, the texture count, ad-gifs, the bounding sphere and
        // the class scale. None of it matches RAC2 yet.
        b.skip(0x44 - 0x1c, "tie class fields not decoded yet")?;
        let o_class = b.i32("tie class number")?;
        Ok(TieClassHeader {
            packets,
            near_dist,
            mid_dist,
            far_dist,
            o_class,
        })
    }

    /// The LOD this class draws at a view depth, or `None` past its far
    /// distance.
    pub fn lod_for_depth(&self, depth: f32) -> Option<usize> {
        if depth < self.near_dist {
            Some(0)
        } else if depth < self.mid_dist {
            Some(1)
        } else if depth < self.far_dist {
            Some(2)
        } else {
            None
        }
    }
}

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

    /// A header as measured on level 0's first tie class.
    fn header() -> Vec<u8> {
        let mut v = vec![0u8; TIE_CLASS_HEADER_MATCHED];
        for (i, x) in [256i32, 20_592, 26_048].iter().enumerate() {
            v[i * 4..i * 4 + 4].copy_from_slice(&x.to_le_bytes());
        }
        for (i, x) in [12.0f32, 25.0, 40.0].iter().enumerate() {
            let o = 0x10 + i * 4;
            v[o..o + 4].copy_from_slice(&x.to_le_bytes());
        }
        v[0x44..0x48].copy_from_slice(&2592i32.to_le_bytes());
        v
    }

    #[test]
    fn parses_the_measured_prefix() {
        let h = TieClassHeader::parse(&header()).unwrap();
        assert_eq!(h.packets, [256, 20_592, 26_048]);
        assert_eq!(h.near_dist, 12.0);
        assert_eq!(h.mid_dist, 25.0);
        assert_eq!(h.far_dist, 40.0);
        assert_eq!(h.o_class, 2592);
    }

    #[test]
    fn a_short_header_is_an_error_not_a_panic() {
        assert!(TieClassHeader::parse(&[0u8; 0x20]).is_err());
        assert!(TieClassHeader::parse(&[]).is_err());
    }

    #[test]
    fn lod_bands_follow_the_three_distances() {
        let h = TieClassHeader::parse(&header()).unwrap();
        assert_eq!(h.lod_for_depth(5.0), Some(0));
        assert_eq!(h.lod_for_depth(20.0), Some(1));
        assert_eq!(h.lod_for_depth(30.0), Some(2));
        assert_eq!(h.lod_for_depth(50.0), None);
    }
}