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}