frostbite-formats 0.1.0

Read and write the Frostbite containers and resources of skate. (2025): TOCs, bundles, CAS, EBX documents, shaders, meshes, physics, .fbmod mods
Documentation
//! Frostbite's native DB (binary object tree): `layout.toc` (behind the TOC envelope) and the chunk metadata of a
//! bundle manifest. A node is a type tag (bit 7: unnamed), a name, then a container (1 list, 2 object: varint size,
//! children, optional terminator), a sized blob (7 string, 19 blob) or a fixed-size value.

use crate::toc::{ENVELOPE, MAGIC};
use crate::{Rd, Result, bad, latin1};

const W: &str = "native db";

/// A node of the native DB tree: a type tag, an optional name, and either children (lists and objects), a payload
/// (strings, blobs and fixed-size values) or neither.
#[derive(Clone, Debug, PartialEq, Eq, Default)]
pub struct Node {
    /// The type tag: the low 5 bits of the stored tag byte (1 list, 2 object, 7 string, 19 blob, 8 and 11 four-byte values, and so on). 0 marks the end of a container.
    pub ty: u8,
    /// Whether the node has a name: bit 7 of the tag byte is clear.
    pub named: bool,
    /// Whether a container's children ended with an explicit zero tag, so that writing it back reproduces the bytes.
    pub terminated: bool,
    /// The node's name as Latin-1 text; empty when the node is unnamed.
    pub name: String,
    /// The stored bytes of a string, blob or fixed-size value (a string keeps its zero terminator); empty for containers.
    pub payload: Vec<u8>,
    /// The nodes of a list or object, in stored order; empty for other types.
    pub children: Vec<Node>,
}

impl Node {
    /// The named child `key` of an object, if there is one.
    pub fn field(&self, key: &str) -> Option<&Node> {
        self.children.iter().find(|c| c.named && c.name == key)
    }
    /// A string node's text without its terminator.
    pub fn text(&self) -> String {
        let t = self.payload.strip_suffix(&[0]).unwrap_or(&self.payload);
        t.iter().map(|&b| char::from(b)).collect()
    }
    /// The value of a 32-bit integer node (type 8), `None` for any other node.
    pub fn u32(&self) -> Option<u32> {
        match (self.ty, self.payload.as_slice()) {
            (8, &[a, b, c, d]) => Some(u32::from_le_bytes([a, b, c, d])),
            _ => None,
        }
    }
}

fn fixed_size(ty: u8) -> Option<usize> {
    Some(match ty {
        6 => 1,
        8 | 11 => 4,
        9 | 12 => 8,
        15 => 16,
        16 => 20,
        _ => return None,
    })
}

fn varint(r: &Rd, mut pos: usize) -> Result<(usize, usize)> {
    let (mut v, mut shift) = (0usize, 0u32);
    loop {
        let b = r.u8(pos)?;
        pos = pos.saturating_add(1);
        if shift > 56 {
            return Err(bad(W, pos, "varint too long: expected at most 9 bytes"));
        }
        v |= usize::from(b & 127) << shift;
        if b & 128 == 0 {
            return Ok((v, pos));
        }
        shift = shift.saturating_add(7);
    }
}

/// How deep containers may nest: the game's files nest a handful of levels, and the reader recurses once per level, so a
/// file of nested lists must be refused, not left to overflow the stack.
pub const MAX_DEPTH: usize = 64;

/// One node at `pos`; the position after it.
pub fn read_node(data: &[u8], pos: usize) -> Result<(Node, usize)> {
    read_at(data, pos, 0)
}

fn read_at(data: &[u8], pos: usize, depth: usize) -> Result<(Node, usize)> {
    let r = Rd::new(data, W);
    let tag = r.u8(pos)?;
    let mut pos = pos.saturating_add(1);
    let mut n = Node {
        ty: tag & 31,
        ..Node::default()
    };
    if n.ty == 0 {
        return Ok((n, pos));
    }
    n.named = tag & 128 == 0;
    if n.named {
        n.name = r.cstr(pos)?;
        // one byte a character (Latin-1): the bytes read, not the UTF-8 length of the String they became
        pos = pos.saturating_add(n.name.chars().count()).saturating_add(1);
    }
    match n.ty {
        1 | 2 => {
            if depth >= MAX_DEPTH {
                return Err(bad(
                    W,
                    pos,
                    format!("containers nest deeper than {MAX_DEPTH} levels"),
                ));
            }
            let (size, p) = varint(&r, pos)?;
            let end = p.saturating_add(size);
            pos = p;
            while pos < end {
                let (child, p) = read_at(data, pos, depth.saturating_add(1))?;
                pos = p;
                if child.ty == 0 {
                    n.terminated = true;
                    break;
                }
                n.children.push(child);
            }
            if pos != end {
                return Err(bad(W, pos, "container length mismatch"));
            }
        }
        7 | 19 => {
            let (size, p) = varint(&r, pos)?;
            n.payload = r.bytes(p, size)?.to_vec();
            pos = p.saturating_add(size);
        }
        t => {
            let size = fixed_size(t).ok_or_else(|| bad(W, pos, format!("unsupported value type {t}")))?;
            n.payload = r.bytes(pos, size)?.to_vec();
            pos = pos.saturating_add(size);
        }
    }
    Ok((n, pos))
}

fn put_varint(out: &mut Vec<u8>, mut v: usize) {
    loop {
        let b = u8::try_from(v & 127).unwrap_or(0);
        v >>= 7;
        if v == 0 {
            out.push(b);
            return;
        }
        out.push(b | 128);
    }
}

/// Append `n` and its children to `out`, the counterpart of [`read_node`]. Refused: a name that is not Latin-1, a
/// fixed-size value of the wrong length, a type this module does not know.
pub fn write_node(n: &Node, out: &mut Vec<u8>) -> Result<()> {
    if n.ty == 0 {
        out.push(0);
        return Ok(());
    }
    out.push(n.ty | if n.named { 0 } else { 128 });
    if n.named {
        out.extend(latin1(&n.name, W)?);
        out.push(0);
    }
    match n.ty {
        1 | 2 => {
            let mut body = Vec::new();
            for c in &n.children {
                write_node(c, &mut body)?;
            }
            if n.terminated {
                body.push(0);
            }
            put_varint(out, body.len());
            out.extend(body);
        }
        7 | 19 => {
            put_varint(out, n.payload.len());
            out.extend(&n.payload);
        }
        t => {
            if fixed_size(t) != Some(n.payload.len()) {
                return Err(bad(
                    W,
                    out.len(),
                    format!("value of type {t} has {} bytes", n.payload.len()),
                ));
            }
            out.extend(&n.payload);
        }
    }
    Ok(())
}

/// A DB file behind the TOC envelope: (envelope bytes, root, trailing bytes).
pub fn read_file(data: &[u8]) -> Result<(Vec<u8>, Node, Vec<u8>)> {
    let (envelope, body) = data
        .split_at_checked(ENVELOPE)
        .filter(|(envelope, body)| !body.is_empty() && envelope.starts_with(&MAGIC))
        .ok_or_else(|| {
            bad(
                W,
                0,
                format!(
                    "unrecognised envelope: expected the magic {MAGIC:02x?} and more than {ENVELOPE} bytes"
                ),
            )
        })?;
    let (root, pos) = read_node(data, ENVELOPE)?;
    let trailer = body.get(pos.saturating_sub(ENVELOPE)..).unwrap_or_default();
    Ok((envelope.to_vec(), root, trailer.to_vec()))
}

/// A DB file: `envelope`, the tree and `trailer`, the counterpart of [`read_file`].
pub fn write_file(envelope: &[u8], root: &Node, trailer: &[u8]) -> Result<Vec<u8>> {
    let mut out = envelope.to_vec();
    write_node(root, &mut out)?;
    out.extend(trailer);
    Ok(out)
}