Expand description
Readers and writers for the container and resource formats of EA Frostbite as skate. (2025) stores them: bytes in, plain records out, and the same records back to bytes.
§What it reads
- Archives and bundles: superbundle TOCs (
toc), a bundle’s file table and manifest (bundle), CAS archives, block by block and decoded (cas), the native DB behindlayout.toc(db) andlayout.tocitself typed (layout), a data folder and the bundles it holds (folder,listing,scope), a table from EBX file GUIDs to document names (names), and ReSkate Studio’s.fbmodmods (fbmod). - EBX documents: read into typed values, written again, and carried between documents (
ebx). - Shaders: block depots (
depot) and the keys of their parameters with the names behind them (paramdb), the program and texture lookup tables (lookup), the permutation selector (selector), permutations and their fixed-function state (permutation), binding sets (binding), input layouts (inputlayout) and compiled bytecode containers (bytecode). - Geometry and animation: MeshSets (
meshset), rigid meshes built from triangles (rigid), the packed tangent frame (tangent), physics resources (physics), skeleton assets (skeleton) and texture headers (texture).
It was written against the skate. build installed from the game and the files ReSkate Studio (20261012) writes;
other Frostbite titles are not assumed to match. It is an independent reader of the stored formats with no code
from Frosty or FrostyToolsuite, except that the ebx module is a port of ReSkate’s EBX reader, writer and merge
(GPL-3.0-or-later).
§What it guarantees
- Checked reads. Readers are bounds-checked: a file that is truncated or does not hold to the format returns
an
Errorthat names what was being read, the offset and what was expected. Counts read from a file are checked against the bytes that remain before a table is reserved for them. Library code denies unchecked indexing, arithmetic and narrowing casts, so a stored offset, count or size that does not fit is an error, not a panic; the crate does not promise to be panic-free on arbitrary bytes, and the few items that allow one of those lints say why. - Strict readers. They walk to the exact end of what they read and refuse a value they do not know instead of guessing; fields whose meaning is not known are kept as stored.
- Writers are the readers’ counterparts. What a reader accepts is written back byte for byte (TOCs only in the Patch layout, with plain names; an EBX document when it already has the writer’s layout), or the writer says why it cannot.
- No game data, no hidden I/O. The crate holds no game data and no keys, and touches files only in
folder. Oodle-compressed CAS blocks are decoded through the caller’s own handle to the game’s Oodle library (cas::Cas); the library is not shipped.
It does not decode pixels, vertices or shader code (only the headers, tables and records around them), does not read other Frostbite games, and reads whole files into memory.
§Example
Build a one-bundle superbundle TOC, read it back, and check that the bundle and chunk lookups resolve:
use frostbite_formats::bundle;
use frostbite_formats::toc::{self, Loc, TocChunk};
let archive = Loc { patch: true, chunk: 0, archive: 1 };
// a bundle whose region lists one file: 16 bytes at offset 0 of the archive
let region = bundle::write_region(&[(archive, 0, 16)], &[])?;
let chunk = TocChunk { guid: [7; 16], file: Some((archive, 16, 64)) };
let bytes = toc::write(&[("win32/levels/demo".to_string(), region)], &[chunk], 0)?;
let parsed = toc::read(&bytes)?;
toc::verify(&parsed)?;
assert_eq!(parsed.bundles[0].0, "win32/levels/demo");
let (files, _inline_manifest) = bundle::read_region(&parsed.bundles[0].1)?;
assert_eq!(files, [(archive, 0, 16)]);
assert_eq!(parsed.chunks[0].file, Some((archive, 16, 64)));
// a corrupt file is refused with where and why
let err = toc::read(&bytes[..100]).unwrap_err();
assert!(err.to_string().contains("toc at 0x0"));Modules§
- binding
- Binding sets and pass bindings (types
BINDING_SETandPASS_BINDING, namedexpressionshader/bindingset/<id>and.../passbinding/<id>): the parameters a shader reads and where. A set holds groups; a group is either the layout of one constant buffer (each parameter at a byte offset) or a list of resources (each at an index). The parameters are the same (name hash, type hash, count) records a ShaderBlockDepot block holds (crate::depot), so a material’s block names the values the group’s parameters read. - bundle
- A bundle: its region in the TOC (the file table: where each of its files lives) and its binary manifest (the first file: names, SHA-1s and sizes of the bundle’s EBX, resources and chunks, plus the chunk metadata DB).
- bytecode
- CompiledBytecode resources (type
RTYPE, namedshaders/bytecode/<guid>): a program’s compiled form as skate.’s shader database holds it. A resource is a relocatable payload (its 16-byte metadata gives the payload size, then the relocation size) that begins with a header and holds one DXBC container with a DXIL part (Shader Model 6), or two (a raytracing pipeline’s, whose header namesRPTRat offset 0x20 where the others nameRC2S); more bytes follow a container in most resources. The header’s fields are not interpreted here: the bytes before the first container and after each container are kept as stored. A container is found by its magic and delimited by its own size field; a magic that is not a container is an error, not skipped. - cas
- Frostbite CAS: a sequence of blocks, each an eight-byte header and an exactly sized payload (
blocks), and the codec that decodes a stream of them to its bytes (Cas), the Oodle blocks through the caller’s handle to the game’s library. - db
- 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. - depot
- ShaderBlockDepot resources (type 0x73312045): material key -> parameter block, and the block’s parameters.
- ebx
- Frostbite EBX documents: RIFF
EBX\0/EBXSfiles holding the EBXD payload, EFIX fixups, EBXX array and boxed-value records, and a REFL or RFL2 reflection table.readturns one into typed values,write()lays a document out again,carrymoves values (and what they point at) from one document into another, andremapgives a document’s identities new GUIDs (a clone). - fbmod
- ReSkate Studio’s
.fbmod: the Frosty mod layout Studio labels version 6 (the legacy layout with a length-prefixed profile and no resource-table SHA-1; not the other Frosty v6 layout). Header, entry table, payload table, payloads: - folder
- A data folder (a Patch folder Studio writes, or the game’s
Data): its TOCs, its CAS archives and the install chunks of itslayout.tocthat name the archives’ directories; reading the files a bundle region points at. - inputlayout
- Input layouts (type
RTYPE, ExpressionShaderInputLayout, namedexpressionshader/inputlayout<id>): the vertex elements a raster permutation’s vertex program was compiled to read. A resource is a relocatable payload (the 16-byte metadata gives its size, its relocation size and the resource’s own id): - layout
layout.toc: the native DB (behind the TOC envelope) that names the superbundles, the install chunks that give the archives’ directories theirpersistentIndex, the initfs and the bundle format.readtypes the keys the stock layout and the 98 layouts of installed mods hold; the tree stays reachable asLayout::rootfor the rest (layeredInstallChunkFiles,meta, …).- listing
- What a data folder holds, by superbundle, bundle and entry: each TOC’s bundles, and a bundle’s EBX documents,
resources and chunks with their names, the resource types, their sizes and the CAS archive and offset the bytes
lie at. Only the TOC and the bundle manifests are read (a manifest is a CAS file of its own): no entry’s payload
is decoded, except where a caller asks for an EBX document’s type (
Source::ebx_type). - lookup
- The shader lookup tables of
dingolevel_root: material key -> program indices (program lookup, type 0xE2E6955B, after the program records) and material key -> streamable texture set (type 0x2D254A89). Rows are a map: the first row of a repeated key wins, as the game’s reader appends. - meshset
- MeshSet resources (type 0x49B156D4): the LODs, their sections and vertex declarations, and where each section’s
vertices and indices lie in the LOD’s geometry chunk. Read (
read,read_resource) and written back (write()): every MeshSet of the game reads and writes back byte-identical, its resource metadata too (tests/meshset.rs). - names
- A corpus-level table from an EBX document’s file GUID to its name. A document names another by the file GUID of the
target (
ebx::ImportReference::file_guid), and the GUID alone says nothing; the document’s name lies in the manifest of the bundle that holds it, so the table is built from bundles and then answers for any document that refers to a GUID some bundle of the same data folder holds. - paramdb
- Shader parameter keys: the 16-byte identity the game gives every shader parameter, and the names behind them.
- permutation
- Shader permutations (types
RASTERandCOMPUTE, namedexpressionshader/permutation<id>): which compiled programs a program database record’s permutation runs. A resource is a relocatable payload (the 16-byte metadata gives its size, its relocation size and the resource’s own id) of the permutation’s shared-data id, an array of 16-byte GUIDs, and for a raster permutation its input layout id: - physics
- skate.’s PhysicsResource (resource type 0x41759364): the collision a PhysicsAsset or EcsPhysicsAsset names. Read
and written faithfully (
read,write()), and a triangle soup encoded as the triangle-mesh shapes ReSkate Studio writes (weld,mesh_shape). - rigid
- A rigid MeshSet and its geometry chunk built from triangle meshes (
build): one LOD, one section a part, laid out as the game’s own one-LOD Quick Drop meshes are (the 73 ofWin32/buildkititems.toc, each onedefault_matsection; 60 store these three streams, 13 add a sub-material index, usage 51). Rebuilding each of the 60 from its decoded geometry (a check run on the game’s files, not part of this repository’s tests) gives: the chunk comes out byte-identical but for tangent frames with two encodings (the same frame either way), and every record field but the measured ones below byte-identical. - scope
- Bundles searched together: the way the game resolves a resource id or a name, which it looks up in every bundle
loaded. A bundle with a program database holds the permutations it adds and names the stock ones, which lie in
another bundle (the game’s configuration bundle in
globals.toc, a level’s root). - selector
- The permutation selector of a program record (
crate::lookup::ProgramRecord): the arrays of the 168-byte record that say which of the program’s permutations a set of option values runs. Five of the record’s twelve(u32 count, u64 pointer)items (at 0x18, 12 bytes each; the pointers are offsets in the program section) are read: - skeleton
- A skeleton asset (
AntSkeletonAsset, the EBX documentsanimation/dingo/*_skeleton) read into its joints (read): facts of the hierarchy only. - tangent
- The packed tangent frame of skate.’s vertices: element usage 52 (
meshset::usage::TANGENT_SPACE), format UByte4N, four bytes a vertex. Read withdecode, written withencode. - texture
- Texture resources (type
crate::TEXTURE): the 180-byte header skate. stores for a texture, whose pixels lie in the chunk it names. Field layout after ReSkate’sEngine/Resource/texture.cpp(read_texture_header, a port of ReSkate Studio’s texture resource), which reads the extended 180-byte form when the resource metadata’s version is 12 or 13; the fields it does not read are named from the stock install’s textures (every texture resource of the install read, 61,618 headers): - toc
- Superbundle TOC (
*.toc): a 0x22C-byte envelope, then a big-endian header, the bundles (name, inline region) and the chunk table, each found through a perfect hash over its keys (lowercase bundle names, chunk GUIDs). Base-game TOCs store names Huffman-coded (flag 4); Patch TOCs (the ones in a folder of added or replaced files, as ReSkate Studio writes it beside the game’sData) store them as plain strings, which is whatwrite()writes.
Structs§
- Rd
- Bounds-checked fixed-size reads, little and big endian: every read past the end is an
Error::Formatthat nameswhatand the offset.
Enums§
- Error
- What went wrong reading or writing a format: the format and offset that broke, a file that could not be opened, a CAS block that would not decode, or an entry of a kind no reader here reads.
Constants§
Functions§
- align
vrounded up to a multiple ofa.- at
- The offset of record
indexof a table atbasewhose records takestridebytes. Saturating: an offset past the address space is past any data, and the read that uses it is refused. - bad
- A format error: what was being read, where, and what broke.
- capacity
- Capacity for
countentries that each take at leastmin_bytesof theremaininginput bytes: refused before anything is reserved when they cannot fit, so a corrupt count returns an error instead of exhausting memory. - djb2
- Frostbite’s string hash: DJB2 with xor (
h = 5381, thenh = h * 33 ^ byteover the name’s bytes, 32 bits), case as given. TheNameHashof assets (a MeshSet’s header word 0x78, a RigidMeshAsset’sNameHash), the name hashes of MeshSet records, and (lowercased) resource type ids (listing::type_id). - guid_
text - 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 chunk entry by its GUID. - hex
- Lowercase hexadecimal of
bytes, in the order given. - latin1
- Latin-1 bytes of a name (Frostbite names are stored one byte per character).
- u32_len
nas theu32a format stores a count or size in; an error namingwhatwhen it does not fit.