rakata_formats/bif/

mod.rs

//! BIF binary reader and writer.
//!
//! BIF (`BIFF`) files are archive containers referenced by KEY indexes.
//! Each entry stores only `(resource_id, type_id, payload)`; names/resrefs are
//! resolved through KEY metadata.
//!
//! ## Format Layout
//! ```text
//! +------------------------------+ 0x0000
//! | Header (20 bytes)            |
//! +------------------------------+ variable_table_offset
//! | Variable resource table      |
//! | 16 bytes * resource_count    |
//! +------------------------------+ (optional)
//! | Fixed resource table         |
//! | 20 bytes * fixed_count       |
//! +------------------------------+ offsets from table
//! | Resource payload blob        |
//! | (aligned to 4-byte boundary) |
//! +------------------------------+
//! ```
//!
//! ## Variable Resource Entry (16 bytes)
//! ```text
//! 0x00..0x04  resource_id  (u32)
//! 0x04..0x08  data_offset  (u32)
//! 0x08..0x0C  data_size    (u32)
//! 0x0C..0x10  type_id      (u32; validated to u16 range)
//! ```
//!
//! ## Fixed Resource Entry (20 bytes)
//! ```text
//! 0x00..0x04  resource_id  (u32)
//! 0x04..0x08  data_offset  (u32)
//! 0x08..0x0C  part_count   (u32)
//! 0x0C..0x10  data_size    (u32)
//! 0x10..0x14  type_id      (u32; validated to u16 range)
//! ```
//!
//! ## Compressed Variant (`.bzf`)
//!
//! The mobile ports ship the same archives with each payload individually
//! LZMA-compressed. The container is otherwise identical, which is the
//! awkward part: the signature is still `BIFF`, the header and tables are
//! byte-for-byte the same shape, and the KEY still names the file `.bif`.
//! Only the on-disk extension distinguishes them.
//!
//! ```text
//! +------------------------------+ 0x0000
//! | Header (20 bytes)            |  identical, signature still `BIFF`
//! +------------------------------+ variable_table_offset
//! | Variable resource table      |  data_size = UNCOMPRESSED length
//! +------------------------------+ offsets from table
//! | Payload: LZMA-alone stream   |  5-byte header, no length field
//! |   0x00      properties byte  |    packs (pb * 5 + lp) * 9 + lc
//! |   0x01..05  dictionary size  |    u32
//! |   0x05..    compressed data  |    ends with an end-of-stream marker
//! +------------------------------+
//! ```
//!
//! An entry's *packed* extent is not stored anywhere. It runs from the
//! entry's offset to wherever the next entry begins, with the last running
//! to the end of the file. The uncompressed length in the table is what the
//! decoder is told to produce.
//!
//! Notes:
//! - Vanilla KotOR BIFs typically use only variable-resource entries
//!   (`fixed_count == 0`), but files with fixed-table entries are accepted.
//! - Compressed archives are gated behind the crate feature `bzf` and read
//!   through [`BifIndex`](crate::bif::BifIndex), which takes the container kind from the caller
//!   rather than guessing it from content.

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

pub use index::{BifIndex, BifIndexEntry};
pub use reader::{
    read_bif, read_bif_from_bytes, read_bif_from_bytes_with_options, read_bif_with_options,
};
pub use writer::{write_bif, write_bif_to_vec};

use thiserror::Error;

use rakata_core::{ResourceId, ResourceTypeCode};

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

/// BIF header size in bytes.
const FILE_HEADER_SIZE: usize = 20;
/// Variable resource-table entry size.
const VARIABLE_ENTRY_SIZE: usize = 16;
/// Fixed resource-table entry size.
const FIXED_ENTRY_SIZE: usize = 20;
/// BIF file signature.
const BIF_MAGIC: [u8; 4] = *b"BIFF";
/// KotOR BIF version.
const BIF_VERSION_V10: [u8; 4] = *b"V1  ";
/// Alternate BIF version accepted by some tooling.
const BIF_VERSION_V11: [u8; 4] = *b"V1.1";
/// Size of the LZMA-alone header prefixing each compressed payload:
/// one properties byte plus a little-endian dictionary size.
#[cfg(feature = "bzf")]
const LZMA_ALONE_HEADER_SIZE: usize = 5;

/// BIF container kind.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub enum BifContainer {
    /// Uncompressed `BIFF` container.
    #[default]
    Biff,
    /// Compressed container: per-resource LZMA-alone payloads, table sizes
    /// still recording uncompressed lengths.
    Bzf,
}

/// One resource entry stored in a BIF archive.
#[derive(Debug, Clone, Eq)]
pub struct BifResource {
    /// Resource ID used by KEY table lookup.
    pub resource_id: ResourceId,
    /// Resource type code from the variable table.
    ///
    /// Unknown IDs are preserved losslessly.
    pub resource_type: ResourceTypeCode,
    /// Source table metadata for this resource entry.
    pub storage: BifResourceStorage,
    /// Resource payload bytes.
    pub data: Vec<u8>,
    /// Original byte offset of this resource in its source file.
    ///
    /// `Some` when read from a file; the writer uses this offset verbatim (filling any
    /// preceding gap with zero bytes) to preserve the exact on-disk layout.
    /// `None` for programmatically-constructed resources; the writer then uses its
    /// default 4-byte-aligned offset calculation.
    pub source_data_offset: Option<u32>,
}

impl PartialEq for BifResource {
    fn eq(&self, other: &Self) -> bool {
        self.resource_id == other.resource_id
            && self.resource_type == other.resource_type
            && self.storage == other.storage
            && self.data == other.data
        // source_data_offset is layout metadata, not semantic content; excluded from equality.
    }
}

/// Storage table kind for a [`BifResource`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum BifResourceStorage {
    /// Entry comes from the variable resource table.
    Variable,
    /// Entry comes from the fixed resource table.
    Fixed {
        /// Declared fixed part count from the fixed table entry.
        part_count: u32,
    },
}

/// In-memory BIF archive.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct Bif {
    /// On-disk container kind.
    pub container: BifContainer,
    /// Ordered resource entries.
    pub resources: Vec<BifResource>,
}

/// BIF reader option set.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct BifReadOptions {
    /// Input policy for accepted source variants.
    pub input: BifReadMode,
}

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

/// BIF reader input policy.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum BifReadMode {
    /// Accept only canonical vanilla K1 BIF variants.
    ///
    /// This mode requires `V1  ` and follows K1 runtime behavior by loading only
    /// variable-table entries.
    CanonicalK1,
    /// Accept broader Aurora-family BIF variants.
    ///
    /// This mode accepts `V1.1`.
    CompatibilityAurora,
}

impl Bif {
    /// Creates an empty BIF archive.
    pub fn new() -> Self {
        Self::default()
    }

    /// Appends one resource entry.
    pub fn push_resource(
        &mut self,
        resource_id: ResourceId,
        resource_type: ResourceTypeCode,
        data: Vec<u8>,
    ) {
        self.resources.push(BifResource {
            resource_id,
            resource_type,
            storage: BifResourceStorage::Variable,
            data,
            source_data_offset: None,
        });
    }

    /// Appends one fixed-table resource entry.
    pub fn push_fixed_resource(
        &mut self,
        resource_id: ResourceId,
        resource_type: ResourceTypeCode,
        part_count: u32,
        data: Vec<u8>,
    ) {
        self.resources.push(BifResource {
            resource_id,
            resource_type,
            storage: BifResourceStorage::Fixed { part_count },
            data,
            source_data_offset: None,
        });
    }

    /// Returns the first matching resource payload by resource ID.
    pub fn resource_by_id(&self, resource_id: ResourceId) -> Option<&[u8]> {
        self.resources
            .iter()
            .find(|resource| resource.resource_id == resource_id)
            .map(|resource| resource.data.as_slice())
    }
}

impl DecodeBinary for Bif {
    type Error = BifBinaryError;

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

impl EncodeBinary for Bif {
    type Error = BifBinaryError;

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

/// Errors produced while parsing or serializing BIF binary data.
#[derive(Debug, Error)]
pub enum BifBinaryError {
    /// I/O read/write failure.
    #[error(transparent)]
    Io(#[from] std::io::Error),
    /// Header signature is unsupported.
    #[error("invalid BIF magic: {0:?}")]
    InvalidMagic([u8; 4]),
    /// Header version is unsupported.
    #[error("invalid BIF version: {0:?}")]
    InvalidVersion([u8; 4]),
    /// BZF support is unavailable because the `bzf` crate feature is disabled.
    #[error("BZF support requires enabling the `bzf` feature on `rakata-formats`")]
    BzfFeatureDisabled,
    /// Header/body layout is invalid or truncated.
    #[error("invalid BIF header: {0}")]
    InvalidHeader(String),
    /// Archive content is structurally invalid.
    #[error("invalid BIF data: {0}")]
    InvalidData(String),
    /// Value cannot fit on-disk integer width.
    #[error("value overflow while writing field `{0}`")]
    ValueOverflow(&'static str),
}

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