rakata_formats/erf/

mod.rs

//! ERF/MOD/HAK binary reader and writer.
//!
//! This module provides a strict, roundtrip-safe implementation of the KotOR
//! ERF family container format. Compatibility mode can also parse legacy
//! non-canonical variants (for example `SAV ` headers).
//!
//! ## Shape of the container
//!
//! A fixed 160-byte header, a localized string block, then two parallel tables
//! -- keys and resources, both sized by `entry_count` -- and finally the
//! payload. Key `n` says what resource `n` is; resource `n` says where its
//! bytes live.
//!
//! Every block after the header is found by an offset read out of the header
//! rather than by following on from the block before it. That is why the blank
//! block some `.mod` files carry between the two tables costs a reader nothing:
//! trusting the offsets absorbs it, while assuming the tables are adjacent
//! reads garbage.
//!
//! Byte-level field maps for the header and both entry records live in
//! `docs/src/formats/archives/erf.md`, with the engine's own load sequence.

mod index;
mod layout;
mod reader;
mod rewrite;
mod writer;

pub use index::{ErfIndex, ErfIndexEntry};
pub use reader::{
    read_erf, read_erf_from_bytes, read_erf_from_bytes_with_options, read_erf_with_options,
    read_save_archive, read_save_archive_from_bytes,
};
pub use rewrite::{rewrite_erf, rewrite_erf_to_vec, ErfRewriteError};
pub use writer::{
    write_erf, write_erf_to_vec, write_erf_to_vec_with_options, write_erf_with_options,
    write_save_archive, write_save_archive_to_vec,
};

use thiserror::Error;

use rakata_core::{
    DecodeTextError, EncodeTextError, LanguageId, ResRef, ResRefError, ResourceTypeCode, StrRef,
    TextEncoding, MAX_RESREF_LEN,
};

use crate::binary::{self, DecodeBinary, EncodeBinary};

/// ERF-family binary header size.
const FILE_HEADER_SIZE: usize = 160;
/// Key table element size.
const KEY_ENTRY_SIZE: usize = 24;
/// Resource table element size.
const RESOURCE_ENTRY_SIZE: usize = 8;
/// Legacy MOD archives reserve an additional blank block between key and
/// resource tables.
const MOD_BLANK_BLOCK_ENTRY_SIZE: usize = 8;
/// ERF container version used by KotOR.
const ERF_VERSION_V10: [u8; 4] = *b"V1.0";
/// Compatibility-only ERF-family version accepted by some Aurora variants.
const ERF_VERSION_V11: [u8; 4] = *b"V1.1";
/// ERF localized-string and resref text encoding.
const ERF_TEXT_ENCODING: TextEncoding = TextEncoding::Windows1252;

/// Supported ERF-family container signatures.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ErfFileType {
    /// Generic ERF archive (`ERF `).
    Erf,
    /// Module archive (`MOD `).
    Mod,
    /// Save archive (`SAV `).
    ///
    /// This signature is not canonical for KotOR; the canonical save-game
    /// archive signature is `MOD `.
    Sav,
    /// Hak pack archive (`HAK `).
    Hak,
}

impl ErfFileType {
    fn from_fourcc(fourcc: [u8; 4]) -> Option<Self> {
        match &fourcc {
            b"ERF " => Some(Self::Erf),
            b"MOD " => Some(Self::Mod),
            b"SAV " => Some(Self::Sav),
            b"HAK " => Some(Self::Hak),
            _ => None,
        }
    }

    fn from_fourcc_with_mode(fourcc: [u8; 4], mode: ErfReadMode) -> Option<Self> {
        match mode {
            ErfReadMode::CanonicalK1 => match &fourcc {
                b"ERF " => Some(Self::Erf),
                b"MOD " => Some(Self::Mod),
                b"HAK " => Some(Self::Hak),
                _ => None,
            },
            ErfReadMode::CompatibilityAurora => Self::from_fourcc(fourcc),
        }
    }

    fn fourcc(self) -> [u8; 4] {
        match self {
            Self::Erf => *b"ERF ",
            Self::Mod => *b"MOD ",
            Self::Sav => *b"SAV ",
            Self::Hak => *b"HAK ",
        }
    }
}

/// Reader options for ERF/MOD/HAK parsing.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ErfReadOptions {
    /// Input-profile behavior for signature/version acceptance.
    pub input: ErfReadMode,
}

impl Default for ErfReadOptions {
    fn default() -> Self {
        Self {
            input: ErfReadMode::CanonicalK1,
        }
    }
}

/// Input-profile behavior for ERF-family readers.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub enum ErfReadMode {
    /// Canonical KotOR profile:
    /// - accepted signatures: `ERF `, `MOD `, `HAK `
    /// - accepted version: `V1.0`
    #[default]
    CanonicalK1,
    /// Compatibility profile for broader Aurora-style archives:
    /// - accepted signatures: `ERF `, `MOD `, `SAV `, `HAK `
    /// - accepted versions: `V1.0`, `V1.1`
    CompatibilityAurora,
}

/// Layout mode for MOD key/resource table spacing during writes.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub enum ModLayout {
    /// Write tightly packed MOD archives (keys immediately followed by resource table).
    #[default]
    Tight,
    /// Write legacy MOD archives with an 8-byte-per-entry zero block between
    /// key and resource tables.
    WithBlankBlock,
}

/// Writer options for ERF-family serialization.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct ErfWriteOptions {
    /// Layout policy used when writing `MOD ` archives.
    pub mod_layout: ModLayout,
    /// Output-profile behavior for serialized header signatures.
    pub output: ErfWriteMode,
}

impl Default for ErfWriteOptions {
    fn default() -> Self {
        Self {
            mod_layout: ModLayout::default(),
            output: ErfWriteMode::CanonicalK1,
        }
    }
}

/// Output-profile behavior for ERF-family writers.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub enum ErfWriteMode {
    /// Canonical KotOR profile:
    /// - save archives serialize with `MOD ` header magic.
    #[default]
    CanonicalK1,
    /// Compatibility profile:
    /// - preserves/emits `SAV ` header magic when selected by caller.
    CompatibilityAurora,
}

/// One localized ERF description entry.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ErfLocalizedString {
    /// Language ID.
    pub language_id: LanguageId,
    /// Localized text.
    pub text: String,
}

/// One resource entry stored in an ERF-family archive.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ErfResource {
    /// Resource name (up to 16 bytes on disk).
    pub resref: ResRef,
    /// The key exactly as the file spelled it, when this came from one.
    ///
    /// A [`ResRef`] folds case so a comparison is free, which is right for
    /// resolution and loses what the file said. The engine's own archives
    /// spell most keys uppercase, and `ExportFilesFromERF` takes an extracted
    /// file's name straight off the key, so folding on the way out renames
    /// every entry in a rewritten archive.
    ///
    /// `None` for an entry built rather than read, which has no original to
    /// keep and is written from [`Self::resref`]. Where both exist this wins:
    /// letting them disagree silently is the failure that carrying it avoids.
    pub name_as_read: Option<[u8; MAX_RESREF_LEN]>,
    /// Resource type code from the key table.
    ///
    /// Unknown numeric IDs are preserved as raw values.
    pub resource_type: ResourceTypeCode,
    /// Resource payload bytes.
    pub data: Vec<u8>,
}

/// In-memory ERF-family container.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Erf {
    /// Container signature.
    pub file_type: ErfFileType,
    /// Build year (`years since 1900`).
    pub build_year: u32,
    /// Build day of year (`1..=366`).
    pub build_day: u32,
    /// Description TLK string reference (`StrRef::invalid()` when absent).
    pub description_strref: StrRef,
    /// Reserved 116-byte block at header offset 0x2C--0x9F.
    ///
    /// Confirmed engine-dead by Ghidra analysis of `AddEncapsulatedContents`
    /// (0x0040f3c0): the full 160-byte header is read into a stack buffer but
    /// only offsets 0x00, 0x04, 0x10, and 0x18 are subsequently accessed.
    /// Preserved verbatim for lossless roundtrip; new files initialize to zero.
    pub reserved: [u8; 116],
    /// Localized description entries.
    pub localized_strings: Vec<ErfLocalizedString>,
    /// Ordered archive resources.
    pub resources: Vec<ErfResource>,
}

impl Erf {
    /// Creates an empty archive for `file_type`.
    pub fn new(file_type: ErfFileType) -> Self {
        Self {
            file_type,
            build_year: 0,
            build_day: 0,
            description_strref: StrRef::invalid(),
            reserved: [0u8; 116],
            localized_strings: Vec::new(),
            resources: Vec::new(),
        }
    }

    /// Appends one resource entry.
    pub fn push_resource(
        &mut self,
        resref: ResRef,
        resource_type: ResourceTypeCode,
        data: Vec<u8>,
    ) {
        self.resources.push(ErfResource {
            resref,
            name_as_read: None,
            resource_type,
            data,
        });
    }

    /// Returns the first matching resource payload.
    pub fn resource(&self, resref: &ResRef, resource_type: ResourceTypeCode) -> Option<&[u8]> {
        self.resources
            .iter()
            .find(|resource| resource.resref == *resref && resource.resource_type == resource_type)
            .map(|resource| resource.data.as_slice())
    }
}

impl DecodeBinary for Erf {
    type Error = ErfBinaryError;

    fn decode_binary(bytes: &[u8]) -> Result<Self, Self::Error> {
        read_erf_from_bytes(bytes)
    }
}

impl EncodeBinary for Erf {
    type Error = ErfBinaryError;

    fn encode_binary(&self) -> Result<Vec<u8>, Self::Error> {
        write_erf_to_vec(self)
    }
}

/// Errors produced while parsing or serializing ERF binary data.
#[derive(Debug, Error)]
pub enum ErfBinaryError {
    /// I/O read/write failure.
    #[error(transparent)]
    Io(#[from] std::io::Error),
    /// Header signature is not a supported ERF family type.
    #[error("invalid ERF magic: {0:?}")]
    InvalidMagic([u8; 4]),
    /// Header version is unsupported.
    #[error("invalid ERF version: {0:?}")]
    InvalidVersion([u8; 4]),
    /// Header/body layout is invalid or truncated.
    #[error("invalid ERF header: {0}")]
    InvalidHeader(String),
    /// Archive content is structurally invalid.
    #[error("invalid ERF data: {0}")]
    InvalidData(String),
    /// Value cannot fit on-disk integer width.
    #[error("value overflow while writing field `{0}`")]
    ValueOverflow(&'static str),
    /// Resource name validation failed during read.
    #[error("invalid resref at {context}: {source}")]
    InvalidResRef {
        /// Field context.
        context: String,
        /// Validation error details.
        #[source]
        source: ResRefError,
    },
    /// Text cannot be represented as ERF encoding.
    #[error("ERF text encoding failed for {context}: {source}")]
    TextEncoding {
        /// Value context.
        context: String,
        /// Encoding error details.
        #[source]
        source: EncodeTextError,
    },
    /// Text bytes cannot be decoded as ERF encoding.
    #[error("ERF text decoding failed for {context}: {source}")]
    TextDecoding {
        /// Value context.
        context: String,
        /// Decoding error details.
        #[source]
        source: DecodeTextError,
    },
}

impl From<binary::BinaryLayoutError> for ErfBinaryError {
    fn from(error: binary::BinaryLayoutError) -> Self {
        Self::InvalidHeader(error.to_string())
    }
}