rakata_core/

detect.rs

use crate::ResourceType;

/// KotOR SFX-obfuscated WAV magic marker.
const SFX_WAV_MAGIC: [u8; 4] = [0xFF, 0xF3, 0x60, 0xC4];

#[cfg(feature = "tracing")]
macro_rules! trace_debug {
    ($($arg:tt)*) => {
        tracing::debug!($($arg)*);
    };
}

#[cfg(not(feature = "tracing"))]
macro_rules! trace_debug {
    ($($arg:tt)*) => {};
}

/// Detects a resource type from binary signature and optional extension hint.
///
/// Detection priority:
/// 1. Strong 8-byte signatures (`LTR V1.0`, `BWM V1.0`)
/// 2. KotOR WAV obfuscation marker
/// 3. 4-byte magic values
/// 4. Extension hint fallback
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(
        level = "debug",
        skip(bytes),
        fields(bytes_len = bytes.len(), extension_hint = extension_hint.unwrap_or(""))
    )
)]
pub fn detect_resource_type(bytes: &[u8], extension_hint: Option<&str>) -> ResourceType {
    let (detected, _reason) = if bytes.len() >= 8 && &bytes[..8] == b"LTR V1.0" {
        (ResourceType::Ltr, "magic_8_ltr")
    } else if bytes.len() >= 8 && &bytes[..4] == b"BWM " && &bytes[4..8] == b"V1.0" {
        (ResourceType::Bwm, "magic_8_bwm")
    } else if bytes.starts_with(&SFX_WAV_MAGIC) {
        (ResourceType::Wav, "sfx_wav_magic")
    } else if bytes.len() >= 4 {
        let first4 = [bytes[0], bytes[1], bytes[2], bytes[3]];
        if let Some(resource_type) = detect_by_first4(first4) {
            (resource_type, "magic_4")
        } else if let Some(ext) = extension_hint {
            (ResourceType::from_extension(ext), "extension_hint")
        } else {
            (ResourceType::Invalid, "no_match")
        }
    } else if let Some(ext) = extension_hint {
        (ResourceType::from_extension(ext), "extension_hint")
    } else {
        (ResourceType::Invalid, "no_match")
    };

    trace_debug!(
        detected = ?detected,
        reason = _reason,
        "resource detection complete"
    );
    detected
}

/// Maps a four-byte magic header to a known resource type.
fn detect_by_first4(first4: [u8; 4]) -> Option<ResourceType> {
    let detected = match &first4 {
        b"2DA " => ResourceType::TwoDa,
        b"TLK " => ResourceType::Tlk,
        b"ERF " => ResourceType::Erf,
        b"MOD " => ResourceType::Mod,
        b"SAV " => ResourceType::Sav,
        b"RIM " => ResourceType::Rim,
        b"BIF " => ResourceType::Bif,
        b"BZF " => ResourceType::Bzf,
        b"KEY " => ResourceType::Key,
        b"LIP " => ResourceType::Lip,
        b"SSF " => ResourceType::Ssf,
        b"NCS " => ResourceType::Ncs,
        b"DDS " => ResourceType::Dds,
        b"RIFF" => ResourceType::Wav,
        // The GFF magics are not listed here. Each is its type's extension
        // uppercased, so `ResourceType::GFF_BACKED` is the one declaration and
        // this consults it rather than repeating seventeen arms that would
        // then have somewhere to drift from.
        _ if ResourceType::GFF_BACKED
            .iter()
            .any(|kind| kind.gff_magic() == Some(first4)) =>
        {
            let detected = ResourceType::GFF_BACKED
                .iter()
                .copied()
                .find(|kind| kind.gff_magic() == Some(first4));
            trace_debug!(first4 = ?first4, detected = ?detected, "resource type detected");
            return detected;
        }
        _ => {
            trace_debug!(first4 = ?first4, "resource type not detected by first4 magic");
            return None;
        }
    };
    trace_debug!(detected = ?detected, "resource type detected by first4 magic");
    Some(detected)
}

#[cfg(test)]
mod tests {
    use super::detect_resource_type;
    use crate::ResourceType;

    #[test]
    fn detects_core_magic_headers() {
        assert_eq!(detect_resource_type(b"2DA V2.b", None), ResourceType::TwoDa);
        assert_eq!(detect_resource_type(b"TLK V3.0", None), ResourceType::Tlk);
        assert_eq!(detect_resource_type(b"RIM V1.0", None), ResourceType::Rim);
        assert_eq!(detect_resource_type(b"KEY V1  ", None), ResourceType::Key);
    }

    #[test]
    fn detects_erf_related_types() {
        assert_eq!(detect_resource_type(b"ERF V1.0", None), ResourceType::Erf);
        assert_eq!(detect_resource_type(b"MOD V1.0", None), ResourceType::Mod);
        assert_eq!(detect_resource_type(b"SAV V1.0", None), ResourceType::Sav);
    }

    #[test]
    fn detects_gff_generics_by_magic() {
        assert_eq!(detect_resource_type(b"UTC \0\0", None), ResourceType::Utc);
        assert_eq!(detect_resource_type(b"UTI \0\0", None), ResourceType::Uti);
        assert_eq!(detect_resource_type(b"ARE \0\0", None), ResourceType::Are);
        assert_eq!(detect_resource_type(b"FAC \0\0", None), ResourceType::Fac);
    }

    #[test]
    fn detects_wav_special_magic() {
        assert_eq!(
            detect_resource_type(&[0xFF, 0xF3, 0x60, 0xC4, 0, 0, 0, 0], None),
            ResourceType::Wav
        );
        assert_eq!(detect_resource_type(b"RIFFxxxx", None), ResourceType::Wav);
    }

    #[test]
    fn detects_ltr_and_bwm_via_strong_8_byte_signatures() {
        assert_eq!(detect_resource_type(b"LTR V1.0", None), ResourceType::Ltr);
        assert_eq!(detect_resource_type(b"BWM V1.0", None), ResourceType::Bwm);
    }

    #[test]
    fn mdl_mdx_detected_by_extension_only() {
        // MDL has no magic header (starts with 4 zero bytes, too ambiguous).
        // MDX is raw vertex data with no header at all.
        // Both rely on extension fallback from archive metadata or filenames.
        let mdl_bytes = [0u8; 16];
        assert_eq!(
            detect_resource_type(&mdl_bytes, Some("mdl")),
            ResourceType::Mdl
        );
        assert_eq!(
            detect_resource_type(&mdl_bytes, Some("mdx")),
            ResourceType::Mdx
        );
        // Without extension hint, these are undetectable.
        assert_eq!(
            detect_resource_type(&mdl_bytes, None),
            ResourceType::Invalid
        );
    }

    #[test]
    fn uses_extension_fallback_for_text_formats() {
        assert_eq!(
            detect_resource_type(b"random", Some("txi")),
            ResourceType::Txi
        );
        assert_eq!(
            detect_resource_type(b"random", Some(".vis")),
            ResourceType::Vis
        );
        assert_eq!(
            detect_resource_type(b"random", Some("lyt")),
            ResourceType::Lyt
        );
    }
}