Skip to main content

frostbite_formats/
listing.rs

1//! What a data folder holds, by superbundle, bundle and entry: each TOC's bundles, and a bundle's EBX documents,
2//! resources and chunks with their names, the resource types, their sizes and the CAS archive and offset the bytes
3//! lie at. Only the TOC and the bundle manifests are read (a manifest is a CAS file of its own): no entry's payload
4//! is decoded, except where a caller asks for an EBX document's type ([`Source::ebx_type`]).
5
6use std::sync::Arc;
7
8use crate::bundle::{self, Asset, FileRef, Kind, Manifest};
9use crate::folder::Source;
10use crate::toc::{Toc, TocChunk};
11use crate::{Error, Result, depot, hex, lookup};
12
13/// One entry of a bundle, as its manifest lists it.
14#[derive(Clone, Debug, PartialEq, Eq)]
15pub struct Listed {
16    /// The superbundle TOC, relative to the data folder (as in [`Folder::tocs`](super::folder::Folder::tocs)), and the
17    /// bundle in it.
18    pub toc: String,
19    /// The bundle the entry is in, by name.
20    pub bundle: String,
21    /// Which table of the manifest the entry came from.
22    pub kind: Kind,
23    /// The entry's place among the manifest's entries of its kind.
24    pub index: usize,
25    /// An EBX document's or a resource's name as the manifest states it; a chunk's is its GUID as stored, in hex.
26    pub name: String,
27    /// A resource's type id and its id.
28    pub resource_type: Option<u32>,
29    /// A resource's own 64-bit id; `None` for EBX documents and chunks.
30    pub resource_id: Option<u64>,
31    /// The entry's size once decoded.
32    pub size: u32,
33    /// Where its stored bytes lie: the CAS archive ([`Loc`](crate::toc::Loc)), the offset and the stored size.
34    pub file: FileRef,
35}
36
37/// A bundle opened: its TOC's tables, its file table and its manifest.
38#[derive(Clone, Debug)]
39pub struct Bundle {
40    /// Path of the superbundle TOC the bundle was found in, relative to the data folder.
41    pub toc_path: String,
42    /// The bundle's name as the TOC states it.
43    pub name: String,
44    pub(super) toc: Arc<Toc>,
45    pub(super) files: Vec<FileRef>,
46    /// The index in `files` of the manifest's first asset.
47    pub(super) first: usize,
48    /// The bundle's binary manifest, with the sizes, hashes and names of its assets.
49    pub manifest: Manifest,
50}
51
52/// What [`Source::listing`] found in a TOC: its bundles opened, and the bundles whose manifest could not be found or
53/// read, by name with the reason.
54#[derive(Clone, Debug, Default)]
55pub struct Listing {
56    /// The bundles of the TOC whose region and manifest were read, in TOC order.
57    pub bundles: Vec<Bundle>,
58    /// `(bundle name, reason)` for each bundle that could not be listed: its manifest file was missing from the region, or would not read.
59    pub unread: Vec<(String, String)>,
60}
61
62impl Listing {
63    /// Every entry of every bundle, in bundle order.
64    pub fn entries(&self) -> impl Iterator<Item = Listed> + '_ {
65        self.bundles.iter().flat_map(Bundle::entries)
66    }
67}
68
69impl Bundle {
70    /// Where the file of entry `index` of `kind` lies in `files`: the manifest lists its assets in file order (the
71    /// EBX documents, then the resources, then the chunks), from `first`.
72    fn file_index(&self, kind: Kind, index: usize) -> usize {
73        let m = &self.manifest;
74        let before = match kind {
75            Kind::Ebx => 0,
76            Kind::Res => m.ebx.len(),
77            Kind::Chunk => m.ebx.len().saturating_add(m.res.len()),
78        };
79        self.first.saturating_add(before).saturating_add(index)
80    }
81
82    /// Entry `index` of `kind` from its manifest row `a`; `None` when the bundle's file table has no file for it.
83    fn listed(&self, kind: Kind, index: usize, a: &Asset) -> Option<Listed> {
84        let res = kind == Kind::Res;
85        Some(Listed {
86            toc: self.toc_path.clone(),
87            bundle: self.name.clone(),
88            kind,
89            index,
90            name: match kind {
91                Kind::Chunk => hex(&a.guid),
92                _ => a.name.clone(),
93            },
94            resource_type: res.then_some(a.rtype),
95            resource_id: res.then_some(a.rid),
96            size: if kind == Kind::Chunk { a.lsize } else { a.size },
97            file: *self.files.get(self.file_index(kind, index))?,
98        })
99    }
100
101    /// Every entry: the EBX documents, then the resources, then the chunks, each in manifest order.
102    pub fn entries(&self) -> impl Iterator<Item = Listed> + '_ {
103        let m = &self.manifest;
104        let ebx = (m.ebx.iter().enumerate()).filter_map(move |(i, a)| self.listed(Kind::Ebx, i, a));
105        let res = (m.res.iter().enumerate()).filter_map(move |(i, a)| self.listed(Kind::Res, i, a));
106        let chunks = (m.chunks.iter().enumerate()).filter_map(move |(i, a)| self.listed(Kind::Chunk, i, a));
107        ebx.chain(res).chain(chunks)
108    }
109
110    /// EBX document `i` of the manifest, as an entry; `None` when the manifest has no document `i`.
111    pub fn ebx(&self, i: usize) -> Option<Listed> {
112        self.listed(Kind::Ebx, i, self.manifest.ebx.get(i)?)
113    }
114
115    /// Resource `i` of the manifest, as an entry; `None` when the manifest has no resource `i`.
116    pub fn resource(&self, i: usize) -> Option<Listed> {
117        self.listed(Kind::Res, i, self.manifest.res.get(i)?)
118    }
119
120    /// The chunk with GUID `guid` in this bundle's TOC chunk table: its bytes' place and decoded size (the whole chunk:
121    /// a bundle's manifest may hold a tail of it, as for a streamed texture), `None` when the table has none; an
122    /// error when the table lists it as removed.
123    pub fn toc_chunk(&self, src: &Source<'_>, guid: &[u8; 16]) -> Result<Option<(FileRef, usize)>> {
124        let Some(TocChunk { file, .. }) = self.toc.chunks.iter().find(|c| &c.guid == guid) else {
125            return Ok(None);
126        };
127        let file =
128            file.ok_or_else(|| Error::Missing(format!("{}: chunk {} is removed", self.name, hex(guid))))?;
129        let raw = src.raw(file)?;
130        let blocks = crate::cas::blocks(&raw)?;
131        Ok(Some((
132            file,
133            blocks
134                .iter()
135                .map(|b| b.decoded_size)
136                .fold(0usize, usize::saturating_add),
137        )))
138    }
139
140    /// The chunk with GUID `guid` (as stored): its bytes' place and decoded size, from this bundle or else from the
141    /// TOC's chunk table (content copied from the base game lies there). From the bundle it is the range the manifest
142    /// stores (`lsize` bytes, which begin `loff` bytes into the whole chunk: [`Bundle::toc_chunk`] gives the whole).
143    pub fn chunk(&self, src: &Source<'_>, guid: &[u8; 16]) -> Result<(FileRef, usize)> {
144        let m = &self.manifest;
145        if let Some((i, c)) = m.chunks.iter().enumerate().find(|(_, c)| &c.guid == guid) {
146            let file = self.files.get(self.file_index(Kind::Chunk, i)).ok_or_else(|| {
147                Error::Missing(format!(
148                    "{}: chunk {} has no file in the bundle's file table",
149                    self.name,
150                    hex(guid)
151                ))
152            })?;
153            return Ok((*file, c.lsize as usize));
154        }
155        let TocChunk { file, .. } = self.toc.chunks.iter().find(|c| &c.guid == guid).ok_or_else(|| {
156            Error::Missing(format!(
157                "{}: chunk {} is in neither the bundle nor its TOC",
158                self.name,
159                hex(guid)
160            ))
161        })?;
162        let file =
163            file.ok_or_else(|| Error::Missing(format!("{}: chunk {} is removed", self.name, hex(guid))))?;
164        let raw = src.raw(file)?;
165        let blocks = crate::cas::blocks(&raw)?;
166        Ok((
167            file,
168            blocks
169                .iter()
170                .map(|b| b.decoded_size)
171                .fold(0usize, usize::saturating_add),
172        ))
173    }
174}
175
176/// The name of a resource type the game's executable names and this crate knows, `None` for any other.
177pub fn resource_type_name(rtype: u32) -> Option<&'static str> {
178    TYPE_NAMES
179        .iter()
180        .find(|(id, _)| *id == rtype)
181        .map(|(_, name)| *name)
182}
183
184/// The resource types this crate names and the names the game's executable holds for them (the id is the djb2-xor hash
185/// of the lowercased name: [`type_id`]). Some of the types have a reader in this crate ([`crate::texture`],
186/// [`crate::depot`], [`crate::bytecode`], [`crate::permutation`] and others); the rest are only named.
187///
188/// The last eight entries (`PhysicsResource` to `TerrainDecals`) are not from the executable's strings: each name is a
189/// candidate whose hash equals an id that occurs in the resource entries of skate.'s bundles (build 20260929), and
190/// the hash match is the whole evidence for it. 21 of the 47 ids that occur there match no name this crate knows.
191pub const TYPE_NAMES: &[(u32, &str)] = &[
192    (crate::TEXTURE, "Texture"),
193    (crate::MESHSET, "MeshSet"),
194    (depot::RTYPE, "ShaderBlockDepotResource"),
195    (crate::bytecode::RTYPE, "CompiledBytecode"),
196    (lookup::PROGRAM_LOOKUP, "ExpressionShaderDatabase"),
197    (
198        lookup::TEXTURE_LOOKUP,
199        "ExpressionShaderStreamableTextureSetLookupTable",
200    ),
201    (0x2FEC_6526, "ShaderStateAssetId"),
202    (0xD489_FACB, "ExpressionShaderRasterPermutation"),
203    (0x95CE_62DD, "ExpressionShaderComputePermutation"),
204    (0xA19B_025D, "ExpressionShaderBindingSet"),
205    (0x7D98_F632, "ExpressionShaderInputLayout"),
206    (0x2500_47B2, "ExpressionShaderRasterPermutationSharedData"),
207    (0x879B_A711, "ExpressionShaderPermutationSharedData"),
208    (0x7A63_0735, "ExpressionShaderStreamableTextureSet"),
209    (0xA895_7ED6, "ExpressionShaderRootSlotInitData"),
210    (0x589B_B36E, "ExpressionShaderPassBinding"),
211    (0x6A5B_E5DB, "ExpressionShaderBindingSignature"),
212    (0xF434_940D, "ShaderParameterCollectionTable"),
213    (0x4175_9364, "PhysicsResource"),
214    (0x30B4_A553, "OccluderMesh"),
215    (0x1CA3_8E06, "VisualTerrain"),
216    (0x957C_32B1, "AtlasTexture"),
217    (0xDE54_0C59, "LayerGraphs"),
218    (0x428E_C9D4, "BundleRefTableResource"),
219    (0x22FE_8AC8, "TerrainStreamingTree"),
220    (0x15E1_F32E, "TerrainDecals"),
221];
222
223/// A resource type's id from its name: the lowercased name's [`djb2`](crate::djb2).
224pub fn type_id(name: &str) -> u32 {
225    crate::djb2(&name.to_ascii_lowercase())
226}
227
228impl Source<'_> {
229    /// The bundles of the TOC at `toc` (relative to the data folder), by name, in stored order. Reads the TOC only.
230    pub fn bundle_names(&self, toc: &str) -> Result<Vec<String>> {
231        Ok(self
232            .folder
233            .toc(toc)?
234            .bundles
235            .into_iter()
236            .map(|(n, _)| n)
237            .collect())
238    }
239
240    fn open_bundle(&self, toc_path: &str, toc: &Arc<Toc>, name: &str, region: &[u8]) -> Result<Bundle> {
241        let (files, inline) = bundle::read_region(region)?;
242        let (manifest, first, _) = self
243            .manifest(&files, &inline)?
244            .ok_or_else(|| Error::Missing(format!("{name} has no manifest")))?;
245        Ok(Bundle {
246            toc_path: toc_path.to_owned(),
247            name: name.to_owned(),
248            toc: Arc::clone(toc),
249            files,
250            first,
251            manifest,
252        })
253    }
254
255    /// The bundle named `name` (ASCII case-insensitive) of the TOC at `toc`.
256    pub fn bundle(&self, toc: &str, name: &str) -> Result<Bundle> {
257        let t = Arc::new(self.folder.toc(toc)?);
258        let (n, region) = t
259            .bundles
260            .iter()
261            .find(|(n, _)| n.eq_ignore_ascii_case(name))
262            .ok_or_else(|| Error::Missing(format!("{toc} has no bundle {name}")))?;
263        self.open_bundle(toc, &t, n, region)
264    }
265
266    /// Every bundle of the TOC at `toc`, opened (the TOC is read once, each manifest once).
267    pub fn listing(&self, toc: &str) -> Result<Listing> {
268        let t = Arc::new(self.folder.toc(toc)?);
269        let mut out = Listing::default();
270        for (name, region) in &t.bundles {
271            match self.open_bundle(toc, &t, name, region) {
272                Ok(b) => out.bundles.push(b),
273                Err(e) => out.unread.push((name.clone(), e.to_string())),
274            }
275        }
276        Ok(out)
277    }
278
279    /// The type name of EBX document `entry`'s first instance. Decodes the document: its cost is the document's.
280    pub fn ebx_type(&self, entry: &Listed) -> Result<String> {
281        if entry.kind != Kind::Ebx {
282            return Err(Error::Unsupported(format!("{}: not an EBX document", entry.name)));
283        }
284        let bytes = self.payload(entry.file, entry.size as usize)?;
285        Ok(crate::ebx::read(&bytes)?.root_type)
286    }
287}