Skip to main content

frostbite_formats/
lib.rs

1//! Readers and writers for the container and resource formats of EA Frostbite as *skate.* (2025) stores them: bytes
2//! in, plain records out, and the same records back to bytes.
3//!
4//! # What it reads
5//!
6//! - **Archives and bundles:** superbundle TOCs ([`toc`]), a bundle's file table and manifest ([`bundle`]), CAS
7//!   archives, block by block and decoded ([`cas`]), the native DB behind `layout.toc` ([`db`]) and `layout.toc`
8//!   itself typed ([`layout`]), a data folder and the bundles it holds ([`folder`], [`listing`], [`scope`]), a table
9//!   from EBX file GUIDs to document names ([`names`]), and ReSkate Studio's `.fbmod` mods ([`fbmod`]).
10//! - **EBX documents:** read into typed values, written again, and carried between documents ([`ebx`]).
11//! - **Shaders:** block depots ([`depot`]) and the keys of their parameters with the names behind them ([`paramdb`]),
12//!   the program and texture lookup tables ([`lookup`]), the permutation
13//!   selector ([`selector`]), permutations and their fixed-function state ([`permutation`]), binding sets
14//!   ([`binding`]), input layouts ([`inputlayout`]) and compiled bytecode containers ([`bytecode`]).
15//! - **Geometry and animation:** MeshSets ([`meshset`]), rigid meshes built from triangles ([`rigid`]), the packed
16//!   tangent frame ([`tangent`]), physics resources ([`physics`]), skeleton assets ([`skeleton`]) and texture
17//!   headers ([`texture`]).
18//!
19//! It was written against the skate. build installed from the game and the files ReSkate Studio (20261012) writes;
20//! other Frostbite titles are not assumed to match. It is an independent reader of the stored formats with no code
21//! from Frosty or FrostyToolsuite, except that the [`ebx`] module is a port of ReSkate's EBX reader, writer and merge
22//! (GPL-3.0-or-later).
23//!
24//! # What it guarantees
25//!
26//! - **Checked reads.** Readers are bounds-checked: a file that is truncated or does not hold to the format returns
27//!   an [`Error`] that names what was being read, the offset and what was expected. Counts read from a file are checked
28//!   against the bytes that remain before a table is reserved for them. Library code denies unchecked indexing,
29//!   arithmetic and narrowing casts, so a stored offset, count or size that does not fit is an error, not a panic;
30//!   the crate does not promise to be panic-free on arbitrary bytes, and the few items that allow one of those lints
31//!   say why.
32//! - **Strict readers.** They walk to the exact end of what they read and refuse a value they do not know instead of
33//!   guessing; fields whose meaning is not known are kept as stored.
34//! - **Writers are the readers' counterparts.** What a reader accepts is written back byte for byte (TOCs only in the
35//!   Patch layout, with plain names; an EBX document when it already has the writer's layout), or the writer says
36//!   why it cannot.
37//! - **No game data, no hidden I/O.** The crate holds no game data and no keys, and touches files only in [`folder`].
38//!   Oodle-compressed CAS blocks are decoded through the caller's own handle to the game's Oodle library
39//!   ([`cas::Cas`]); the library is not shipped.
40//!
41//! It does not decode pixels, vertices or shader code (only the headers, tables and records around them), does not
42//! read other Frostbite games, and reads whole files into memory.
43//!
44//! # Example
45//!
46//! Build a one-bundle superbundle TOC, read it back, and check that the bundle and chunk lookups resolve:
47//!
48//! ```
49//! use frostbite_formats::bundle;
50//! use frostbite_formats::toc::{self, Loc, TocChunk};
51//!
52//! # fn main() -> Result<(), frostbite_formats::Error> {
53//! let archive = Loc { patch: true, chunk: 0, archive: 1 };
54//! // a bundle whose region lists one file: 16 bytes at offset 0 of the archive
55//! let region = bundle::write_region(&[(archive, 0, 16)], &[])?;
56//! let chunk = TocChunk { guid: [7; 16], file: Some((archive, 16, 64)) };
57//!
58//! let bytes = toc::write(&[("win32/levels/demo".to_string(), region)], &[chunk], 0)?;
59//!
60//! let parsed = toc::read(&bytes)?;
61//! toc::verify(&parsed)?;
62//! assert_eq!(parsed.bundles[0].0, "win32/levels/demo");
63//! let (files, _inline_manifest) = bundle::read_region(&parsed.bundles[0].1)?;
64//! assert_eq!(files, [(archive, 0, 16)]);
65//! assert_eq!(parsed.chunks[0].file, Some((archive, 16, 64)));
66//!
67//! // a corrupt file is refused with where and why
68//! let err = toc::read(&bytes[..100]).unwrap_err();
69//! assert!(err.to_string().contains("toc at 0x0"));
70//! # Ok(())
71//! # }
72//! ```
73#![deny(missing_docs, clippy::disallowed_methods, clippy::disallowed_types)]
74// Stored bytes never panic a reader: no unchecked index, slice, arithmetic or narrowing cast in library code.
75#![cfg_attr(
76    not(test),
77    deny(
78        clippy::indexing_slicing,
79        clippy::arithmetic_side_effects,
80        clippy::cast_possible_truncation
81    )
82)]
83
84use primase_foundations::bytes::Endian;
85
86pub mod binding;
87pub mod bundle;
88pub mod bytecode;
89pub mod cas;
90pub mod db;
91pub mod depot;
92pub mod ebx;
93pub mod fbmod;
94pub mod folder;
95pub mod inputlayout;
96pub mod layout;
97pub mod listing;
98pub mod lookup;
99pub mod meshset;
100pub mod names;
101pub mod paramdb;
102pub mod permutation;
103pub mod physics;
104pub mod rigid;
105pub mod scope;
106pub mod selector;
107pub mod skeleton;
108pub mod tangent;
109pub mod texture;
110pub mod toc;
111
112/// Resource type of a MeshSet.
113pub const MESHSET: u32 = 0x49B1_56D4;
114/// Resource type of a texture.
115pub const TEXTURE: u32 = 0x6BDE_20BA;
116
117/// What went wrong reading or writing a format: the format and offset that broke, a file that could not be opened, a
118/// CAS block that would not decode, or an entry of a kind no reader here reads.
119#[derive(Debug, thiserror::Error)]
120pub enum Error {
121    /// Bytes that do not hold to the format: what was being read, the offset (within the bytes being read) where it
122    /// went wrong, and what was expected.
123    #[error("{what} at {offset:#x}: {detail}")]
124    Format {
125        /// The thing being read (`"toc"`, `"meshset"`), the first word of the message.
126        what: &'static str,
127        /// Byte offset of the failure within the bytes that were being read, not within the file they came from.
128        offset: usize,
129        /// What was expected or what was found instead.
130        detail: String,
131    },
132    /// A file or folder that could not be read.
133    #[error("{}: {source}", path.display())]
134    Io {
135        /// The file or folder that failed.
136        path: std::path::PathBuf,
137        /// The operating system's error.
138        source: std::io::Error,
139    },
140    /// A CAS block that would not decode (or an Oodle library that was needed and not given).
141    #[error("cas: {0}")]
142    Cas(#[from] primase_foundations::compress::Error),
143    /// Something a lookup needed and the data does not hold (a bundle, a chunk, an archive), named.
144    #[error("{0}")]
145    Missing(String),
146    /// An entry of a kind or form no reader here reads, named.
147    #[error("{0}")]
148    Unsupported(String),
149}
150
151/// `Result` with this crate's [`Error`].
152pub type Result<T, E = Error> = std::result::Result<T, E>;
153
154/// Frostbite's string hash: DJB2 with xor (`h = 5381`, then `h = h * 33 ^ byte` over the name's bytes, 32 bits), case as
155/// given. The `NameHash` of assets (a MeshSet's header word 0x78, a RigidMeshAsset's `NameHash`), the name hashes of
156/// MeshSet records, and (lowercased) resource type ids ([`listing::type_id`]).
157pub fn djb2(name: &str) -> u32 {
158    name.bytes()
159        .fold(5381u32, |h, b| h.wrapping_mul(33) ^ u32::from(b))
160}
161
162/// A GUID's text form (`8-4-4-4-12`) from its stored bytes (the first three groups little-endian): how a mod names a
163/// chunk entry by its GUID.
164pub fn guid_text(g: &[u8; 16]) -> String {
165    let [a0, a1, a2, a3, b0, b1, c0, c1, d0, d1, e0, e1, e2, e3, e4, e5] = *g;
166    format!(
167        "{a3:02x}{a2:02x}{a1:02x}{a0:02x}-{b1:02x}{b0:02x}-{c1:02x}{c0:02x}-{d0:02x}{d1:02x}-{e0:02x}{e1:02x}{e2:02x}{e3:02x}{e4:02x}{e5:02x}"
168    )
169}
170
171/// Lowercase hexadecimal of `bytes`, in the order given.
172pub fn hex(bytes: &[u8]) -> String {
173    use std::fmt::Write;
174    bytes.iter().fold(
175        String::with_capacity(bytes.len().saturating_mul(2)),
176        |mut s, b| {
177            let _ = write!(s, "{b:02x}");
178            s
179        },
180    )
181}
182
183/// A format error: what was being read, where, and what broke.
184pub fn bad(what: &'static str, offset: usize, detail: impl Into<String>) -> Error {
185    Error::Format {
186        what,
187        offset,
188        detail: detail.into(),
189    }
190}
191
192/// A read past the data: `what`'s error at the read's offset, naming how many bytes it wanted and
193/// the `total` there are (a span whose end overflows the address space wants all it names).
194pub(crate) fn past_end(
195    what: &'static str,
196    e: primase_foundations::bytes::BoundsError,
197    total: usize,
198) -> Error {
199    let at = usize::try_from(e.absolute()).unwrap_or(usize::MAX);
200    let length = match e {
201        primase_foundations::bytes::BoundsError::OutOfBounds { length, .. } => length,
202        primase_foundations::bytes::BoundsError::LengthOverflow { count, stride, .. } => {
203            count.saturating_mul(stride)
204        }
205    };
206    bad(what, at, format!("{length} bytes past the end ({total} bytes)"))
207}
208
209/// A read past a document's bytes through [`primase_foundations::bytes::Cursor`] (the EBX decoder's): its error at the read's
210/// offset.
211impl From<primase_foundations::bytes::BoundsError> for Error {
212    fn from(e: primase_foundations::bytes::BoundsError) -> Self {
213        match e {
214            primase_foundations::bytes::BoundsError::OutOfBounds { total, .. } => past_end("read", e, total),
215            primase_foundations::bytes::BoundsError::LengthOverflow { count, stride, .. } => bad(
216                "read",
217                usize::try_from(e.absolute()).unwrap_or(usize::MAX),
218                format!("{count} entries of {stride} bytes overflow"),
219            ),
220        }
221    }
222}
223
224/// Bounds-checked fixed-size reads, little and big endian: every read past the end is an [`Error::Format`] that names
225/// `what` and the offset.
226#[derive(Debug)]
227pub struct Rd<'a> {
228    /// The bytes being read.
229    pub data: &'a [u8],
230    /// What they are, for error messages.
231    pub what: &'static str,
232}
233
234impl<'a> Rd<'a> {
235    /// Reads over `data`; `what` names the thing being read in every error.
236    pub fn new(data: &'a [u8], what: &'static str) -> Self {
237        Self { data, what }
238    }
239
240    /// `n` bytes at `at`.
241    pub fn bytes(&self, at: usize, n: usize) -> Result<&'a [u8]> {
242        primase_foundations::bytes::View::new(self.data)
243            .slice(at, n)
244            .map_err(|e| past_end(self.what, e, self.data.len()))
245    }
246
247    /// `N` bytes at `at` as an array.
248    pub fn arr<const N: usize>(&self, at: usize) -> Result<[u8; N]> {
249        primase_foundations::bytes::View::new(self.data)
250            .array(at)
251            .map_err(|e| past_end(self.what, e, self.data.len()))
252    }
253
254    /// The byte at `at`.
255    pub fn u8(&self, at: usize) -> Result<u8> {
256        primase_foundations::bytes::View::new(self.data)
257            .u8(at)
258            .map_err(|e| past_end(self.what, e, self.data.len()))
259    }
260    /// The little-endian `u16` at `at`.
261    pub fn u16le(&self, at: usize) -> Result<u16> {
262        self.number(at, Endian::Little, primase_foundations::bytes::View::u16)
263    }
264    /// The little-endian `u32` at `at`.
265    pub fn u32le(&self, at: usize) -> Result<u32> {
266        self.number(at, Endian::Little, primase_foundations::bytes::View::u32)
267    }
268    /// The little-endian `u64` at `at`.
269    pub fn u64le(&self, at: usize) -> Result<u64> {
270        self.number(at, Endian::Little, primase_foundations::bytes::View::u64)
271    }
272    /// The little-endian `u32` at `at` as a size or count.
273    pub fn size32le(&self, at: usize) -> Result<usize> {
274        let v = self.u32le(at)?;
275        usize::try_from(v).map_err(|_| bad(self.what, at, format!("{v:#x} does not fit the address space")))
276    }
277    /// The little-endian `u64` at `at` as an offset or size.
278    pub fn offset64le(&self, at: usize) -> Result<usize> {
279        let v = self.u64le(at)?;
280        usize::try_from(v).map_err(|_| bad(self.what, at, format!("{v:#x} does not fit the address space")))
281    }
282    /// The big-endian `u32` at `at`.
283    pub fn u32be(&self, at: usize) -> Result<u32> {
284        self.number(at, Endian::Big, primase_foundations::bytes::View::u32)
285    }
286    /// The big-endian `i32` at `at`.
287    pub fn i32be(&self, at: usize) -> Result<i32> {
288        self.number(at, Endian::Big, primase_foundations::bytes::View::i32)
289    }
290    /// The big-endian `u64` at `at`.
291    pub fn u64be(&self, at: usize) -> Result<u64> {
292        self.number(at, Endian::Big, primase_foundations::bytes::View::u64)
293    }
294    /// A number at `at` in byte order `e`, read by `read`.
295    fn number<T>(
296        &self,
297        at: usize,
298        e: Endian,
299        read: fn(
300            &primase_foundations::bytes::View<'a>,
301            usize,
302            Endian,
303        ) -> std::result::Result<T, primase_foundations::bytes::BoundsError>,
304    ) -> Result<T> {
305        read(&primase_foundations::bytes::View::new(self.data), at, e)
306            .map_err(|err| past_end(self.what, err, self.data.len()))
307    }
308    /// A zero-terminated Latin-1 string starting at `at`.
309    pub fn cstr(&self, at: usize) -> Result<String> {
310        let rest = self
311            .data
312            .get(at..)
313            .ok_or_else(|| bad(self.what, at, "string past the end"))?;
314        let mut parts = rest.splitn(2, |&b| b == 0);
315        match (parts.next(), parts.next()) {
316            (Some(text), Some(_)) => Ok(text.iter().map(|&b| char::from(b)).collect()),
317            _ => Err(bad(self.what, at, "unterminated string, expected a zero byte")),
318        }
319    }
320}
321
322/// Latin-1 bytes of a name (Frostbite names are stored one byte per character).
323pub fn latin1(s: &str, what: &'static str) -> Result<Vec<u8>> {
324    s.chars()
325        .map(|c| u8::try_from(u32::from(c)).map_err(|_| bad(what, 0, format!("name {s:?} is not Latin-1"))))
326        .collect()
327}
328
329/// Capacity for `count` entries that each take at least `min_bytes` of the `remaining` input bytes: refused before
330/// anything is reserved when they cannot fit, so a corrupt count returns an error instead of exhausting memory.
331pub fn capacity(what: &'static str, count: usize, min_bytes: usize, remaining: usize) -> Result<usize> {
332    match primase_foundations::bytes::checked_span(0, count, min_bytes, remaining) {
333        Ok(_) => Ok(count),
334        _ => Err(bad(
335            what,
336            0,
337            format!("{count} entries of at least {min_bytes} bytes in {remaining} bytes"),
338        )),
339    }
340}
341
342/// `n` as the `u32` a format stores a count or size in; an error naming `what` when it does not fit.
343pub fn u32_len(what: &'static str, n: usize) -> Result<u32> {
344    u32::try_from(n).map_err(|_| {
345        bad(
346            what,
347            0,
348            format!("{n} does not fit the 32-bit field it is stored in"),
349        )
350    })
351}
352
353/// The offset of record `index` of a table at `base` whose records take `stride` bytes. Saturating: an offset past the
354/// address space is past any data, and the read that uses it is refused.
355pub fn at(base: usize, index: usize, stride: usize) -> usize {
356    base.saturating_add(index.saturating_mul(stride))
357}
358
359/// `v` rounded up to a multiple of `a`.
360pub fn align(v: usize, a: usize) -> usize {
361    v.div_ceil(a).saturating_mul(a)
362}
363
364#[cfg(test)]
365mod bounds_tests {
366    use super::*;
367    /// The fields of a format error, or a panic for any other kind: the constructors must choose both the kind and
368    /// the offset, not only the message text.
369    fn format_error(error: Error) -> (&'static str, usize, String) {
370        match error {
371            Error::Format { what, offset, detail } => (what, offset, detail),
372            other => panic!("expected a format error, got {other}"),
373        }
374    }
375    #[test]
376    fn wrapper_retains_bounds_and_error_context() {
377        let rd = Rd::new(&[1, 2, 3, 4], "bounds fixture");
378        assert!(rd.bytes(4, 0).unwrap().is_empty());
379        assert_eq!(rd.u32be(0).unwrap(), 0x01020304);
380        for (offset, length) in [(4, 1), (5, 0), (usize::MAX, 1)] {
381            let (what, at, detail) = format_error(rd.bytes(offset, length).unwrap_err());
382            assert_eq!((what, at), ("bounds fixture", offset));
383            assert_eq!(detail, format!("{length} bytes past the end (4 bytes)"));
384        }
385        assert_eq!(capacity("table", 2, 2, 4).unwrap(), 2);
386        assert_eq!(capacity("table", usize::MAX, 0, 0).unwrap(), usize::MAX);
387        for (count, stride) in [(3, 2), (usize::MAX, 2)] {
388            let (what, at, detail) = format_error(capacity("table", count, stride, 4).unwrap_err());
389            assert_eq!((what, at), ("table", 0));
390            assert_eq!(
391                detail,
392                format!("{count} entries of at least {stride} bytes in 4 bytes")
393            );
394        }
395    }
396}