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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
//! 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:
//!
//! ```text
//! "FROSTY\0\1"  u32 version (6)  u64 payload-table offset  u32 payload count
//! u8 length + profile  u32 game version  six zero-terminated strings (title, author, category, version,
//! description, link)  u32 entry count  entries...  payload table: (u64 offset, u64 size) per payload  payloads
//! ```
//!
//! An entry is `u8 kind, i32 payload index (-1: none), name`; with a payload, `SHA-1 (20), u64 decoded size, u8 flags,
//! u32 handler, user string`; then `u32 count + u32 bundle hashes`; then by kind: a resource (2) `u32 type, u64 id,
//! u32 length + metadata`; a chunk (3) six `u32` and `u32 count + u32 added-bundle hashes`. Kind 0 (embedded files:
//! the icon and screenshots) and 1 (EBX) have nothing more. Payloads are CAS-framed, shared by index; the SHA-1 is of
//! the stored (encoded) payload. Layout after FrostyToolsuite's `FrostyModReader`, `BaseModResource`, `ResResource` and
//! `ChunkResource`; the bytes are Studio's, read to the exact end.
//!
//! Decoding a payload needs the game's Oodle library, which the caller loads ([`Fbmod::payload`]). [`write()`] is the reader's counterpart: an unmodified file read and written again is byte-identical. The SHA-1 of a
//! payload is recomputed on writing (and checked on reading), so it is not a field.

use crate::cas::{self, Cas, CasRaw};
use crate::{Result, bad, capacity, past_end};
use primase_foundations::bytes::Endian;
use primase_foundations::compress::oodle::Oodle;
use primase_foundations::compress::{Compressor, Decompressor};
use sha1::{Digest, Sha1};

const W: &str = "fbmod";
/// The first eight bytes of a mod.
pub const MAGIC: [u8; 8] = *b"FROSTY\0\x01";
/// The only version Studio writes.
pub const VERSION: u32 = 6;
/// Fixed bytes before the profile: magic, version, payload table offset, payload count, profile length.
const FIXED: usize = 8 + 4 + 8 + 4 + 1;

/// The kind byte of an entry.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum EntryKind {
    /// An embedded file: the icon or a screenshot.
    Embedded,
    /// An EBX document; the entry stores nothing beyond the common fields.
    Ebx,
    /// A resource; see [`ResInfo`].
    Res,
    /// A chunk; see [`ChunkInfo`].
    Chunk,
}

impl EntryKind {
    /// The kind byte an entry stores.
    pub fn id(self) -> u8 {
        match self {
            Self::Embedded => 0,
            Self::Ebx => 1,
            Self::Res => 2,
            Self::Chunk => 3,
        }
    }
}

/// What a resource entry stores beyond the common fields.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ResInfo {
    /// The resource type hash (a MeshSet is [`crate::MESHSET`]).
    pub res_type: u32,
    /// The resource's 64-bit id.
    pub rid: u64,
    /// The resource's 16 metadata bytes (stored with a u32 length), kept as stored.
    pub meta: Vec<u8>,
}

/// What a chunk entry stores beyond the common fields (FrostyToolsuite's `ChunkResource`).
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ChunkInfo {
    /// `rangeStart` of FrostyToolsuite's `ChunkResource` (u32), kept as stored.
    pub range_start: u32,
    /// `rangeEnd` (u32), kept as stored.
    pub range_end: u32,
    /// `logicalOffset` (u32), kept as stored.
    pub logical_offset: u32,
    /// `logicalSize` (u32), kept as stored.
    pub logical_size: u32,
    /// `h32` (u32), kept as stored.
    pub h32: u32,
    /// `firstMip` (i32), kept as stored.
    pub first_mip: i32,
    /// Bundles the chunk is added to (the entry's own `bundles` are the bundles it modifies).
    pub added_bundles: Vec<u32>,
}

/// The kind of an entry with what only that kind stores.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Body {
    /// An embedded file (the icon or a screenshot); nothing beyond the common fields.
    Embedded,
    /// An EBX document; nothing beyond the common fields.
    Ebx,
    /// A resource with its type, id and metadata.
    Res(ResInfo),
    /// A chunk with its range, logical size and added bundles.
    Chunk(ChunkInfo),
}

impl Body {
    /// The entry kind this body belongs to.
    pub fn kind(&self) -> EntryKind {
        match self {
            Self::Embedded => EntryKind::Embedded,
            Self::Ebx => EntryKind::Ebx,
            Self::Res(_) => EntryKind::Res,
            Self::Chunk(_) => EntryKind::Chunk,
        }
    }
}

/// The payload an entry points at and how it is described.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Stored {
    /// Index into [`Fbmod::payloads`]; entries may share one.
    pub index: usize,
    /// The payload's size once decoded.
    pub size: u64,
    /// The u8 flags field of the payload description, kept as stored.
    pub flags: u8,
    /// The u32 handler field of the payload description, kept as stored.
    pub handler: u32,
    /// The user string of the payload description (a zero-terminated string), kept as stored.
    pub user: String,
}

/// One entry of a mod: an asset it adds or replaces, with its payload (if it has one) and the bundles it touches.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Entry {
    /// The asset's name or path, as the mod stores it (a chunk entry's name is its GUID text, see [`crate::guid_text`]).
    pub name: String,
    /// `None` for an entry without a payload (index -1: the embedded files of a fresh mod).
    pub stored: Option<Stored>,
    /// Hashes of the bundles the entry modifies.
    pub bundles: Vec<u32>,
    /// What only this kind of entry stores.
    pub body: Body,
}

impl Entry {
    /// The entry's kind.
    pub fn kind(&self) -> EntryKind {
        self.body.kind()
    }
    /// Index of the entry's payload, if it has one.
    pub fn index(&self) -> Option<usize> {
        self.stored.as_ref().map(|s| s.index)
    }
}

/// A `.fbmod` file read into its header fields, entries and CAS-framed payloads.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Fbmod {
    /// The file's version word; 6 ([`VERSION`]) is the only one [`read`] accepts.
    pub version: u32,
    /// The profile string, stored with a one-byte length.
    pub profile: String,
    /// The game version the mod was made for.
    pub game_version: u32,
    /// Title string.
    pub title: String,
    /// Author string.
    pub author: String,
    /// Category string.
    pub category: String,
    /// The mod's own version string, as the author typed it (not the file version).
    pub mod_version: String,
    /// Description string.
    pub description: String,
    /// Link string.
    pub link: String,
    /// The mod's entries, in stored order.
    pub entries: Vec<Entry>,
    /// CAS-framed payloads, as stored.
    pub payloads: Vec<Vec<u8>>,
}

/// The mod's bytes read in order ([`primase_foundations::bytes::Cursor`], little-endian), a read past them refused as the mod's.
struct Cur<'a> {
    c: primase_foundations::bytes::Cursor<'a>,
}

impl<'a> Cur<'a> {
    fn take(&mut self, n: usize) -> Result<&'a [u8]> {
        self.c.take(n).map_err(|e| past_end(W, e, self.c.bytes().len()))
    }
    fn arr<const N: usize>(&mut self) -> Result<[u8; N]> {
        self.c.array().map_err(|e| past_end(W, e, self.c.bytes().len()))
    }
    fn u8(&mut self) -> Result<u8> {
        self.c.u8().map_err(|e| past_end(W, e, self.c.bytes().len()))
    }
    fn u32(&mut self) -> Result<u32> {
        self.c
            .u32(Endian::Little)
            .map_err(|e| past_end(W, e, self.c.bytes().len()))
    }
    fn i32(&mut self) -> Result<i32> {
        self.c
            .i32(Endian::Little)
            .map_err(|e| past_end(W, e, self.c.bytes().len()))
    }
    fn u64(&mut self) -> Result<u64> {
        self.c
            .u64(Endian::Little)
            .map_err(|e| past_end(W, e, self.c.bytes().len()))
    }
    fn position(&self) -> usize {
        self.c.position()
    }
    fn count(&mut self, min_bytes: usize) -> Result<usize> {
        let n = self.u32()? as usize;
        capacity(W, n, min_bytes, self.c.remaining())
    }
    fn string(&mut self) -> Result<String> {
        let at = self.position();
        let rest = self.c.bytes().get(at..).unwrap_or_default();
        let mut parts = rest.splitn(2, |&b| b == 0);
        let (Some(text), Some(_)) = (parts.next(), parts.next()) else {
            return Err(bad(W, at, "unterminated string, expected a zero byte"));
        };
        let s = std::str::from_utf8(text).map_err(|_| bad(W, at, "string is not UTF-8"))?;
        self.take(text.len().saturating_add(1))?;
        Ok(s.to_owned())
    }
    fn u32s(&mut self) -> Result<Vec<u32>> {
        let n = self.count(4)?;
        (0..n).map(|_| self.u32()).collect()
    }
}

fn sha1(data: &[u8]) -> [u8; 20] {
    Sha1::digest(data).into()
}

/// Read a mod to its exact end. Refused: another magic or version, an unknown entry kind, a payload index that does
/// not exist, a stored SHA-1 that is not the payload's, payloads that are not laid out one after the other to the end
/// of the file, and bytes after them.
pub fn read(bytes: &[u8]) -> Result<Fbmod> {
    let mut c = Cur {
        c: primase_foundations::bytes::Cursor::new(bytes),
    };
    if c.arr::<8>()? != MAGIC {
        return Err(bad(W, 0, "not a FROSTY mod"));
    }
    let version = c.u32()?;
    if version != VERSION {
        return Err(bad(W, 8, format!("version {version}, expected {VERSION}")));
    }
    let table_at = usize::try_from(c.u64()?).map_err(|_| bad(W, 12, "payload table offset"))?;
    let payload_count = c.u32()? as usize;
    let plen = usize::from(c.u8()?);
    let profile = std::str::from_utf8(c.take(plen)?)
        .map_err(|_| bad(W, FIXED, "profile is not UTF-8"))?
        .to_owned();
    let game_version = c.u32()?;
    let mut details = Vec::with_capacity(6);
    for _ in 0..6 {
        details.push(c.string()?);
    }
    let [title, author, category, mod_version, description, link]: [String; 6] =
        details.try_into().map_err(|_| bad(W, c.position(), "details"))?;
    // kind, index, name terminator, bundle count
    let n = c.count(10)?;
    let mut entries = Vec::with_capacity(n);
    for _ in 0..n {
        let at = c.position();
        let kind = c.u8()?;
        let index = c.i32()?;
        let name = c.string()?;
        let index = match usize::try_from(index) {
            Ok(i) if i < payload_count => Some(i),
            _ if index == -1 => None,
            _ => return Err(bad(W, at, format!("payload {index} of {payload_count}: {name}"))),
        };
        let (stored, sha) = match index {
            Some(index) => {
                let sha = c.arr::<20>()?;
                let size = c.u64()?;
                let flags = c.u8()?;
                let handler = c.u32()?;
                let user = c.string()?;
                (
                    Some(Stored {
                        index,
                        size,
                        flags,
                        handler,
                        user,
                    }),
                    Some(sha),
                )
            }
            None => (None, None),
        };
        let bundles = c.u32s()?;
        let body = match kind {
            0 => Body::Embedded,
            1 => Body::Ebx,
            2 => {
                let res_type = c.u32()?;
                let rid = c.u64()?;
                let len = c.u32()? as usize;
                Body::Res(ResInfo {
                    res_type,
                    rid,
                    meta: c.take(len)?.to_vec(),
                })
            }
            3 => Body::Chunk(ChunkInfo {
                range_start: c.u32()?,
                range_end: c.u32()?,
                logical_offset: c.u32()?,
                logical_size: c.u32()?,
                h32: c.u32()?,
                first_mip: c.i32()?,
                added_bundles: c.u32s()?,
            }),
            k => return Err(bad(W, at, format!("unknown entry kind {k}: {name}"))),
        };
        entries.push((
            Entry {
                name,
                stored,
                bundles,
                body,
            },
            sha,
            at,
        ));
    }
    if c.position() != table_at {
        return Err(bad(
            W,
            c.position(),
            format!("entries end here, payload table at {table_at:#x}"),
        ));
    }
    let mut spans = Vec::with_capacity(capacity(
        W,
        payload_count,
        16,
        bytes.len().saturating_sub(c.position()),
    )?);
    for _ in 0..payload_count {
        spans.push((c.u64()?, c.u64()?));
    }
    let mut payloads = Vec::with_capacity(payload_count);
    let mut next = 0u64;
    for (i, (offset, size)) in spans.into_iter().enumerate() {
        if offset != next {
            return Err(bad(
                W,
                c.position(),
                format!("payload {i} at {offset:#x}, expected {next:#x}"),
            ));
        }
        next = offset
            .checked_add(size)
            .ok_or_else(|| bad(W, c.position(), format!("payload {i} size")))?;
        let size = usize::try_from(size).map_err(|_| bad(W, c.position(), format!("payload {i} size")))?;
        payloads.push(c.take(size)?.to_vec());
    }
    if c.position() != bytes.len() {
        return Err(bad(
            W,
            c.position(),
            format!(
                "{} bytes after the last payload, expected the file to end there",
                bytes.len().saturating_sub(c.position())
            ),
        ));
    }
    let mut out = Vec::with_capacity(entries.len());
    for (entry, sha, at) in entries {
        if let (Some(s), Some(sha)) = (&entry.stored, sha)
            && payloads.get(s.index).map(|p| sha1(p)) != Some(sha)
        {
            return Err(bad(
                W,
                at,
                format!("SHA-1 of payload {} differs: {}", s.index, entry.name),
            ));
        }
        out.push(entry);
    }
    Ok(Fbmod {
        version,
        profile,
        game_version,
        title,
        author,
        category,
        mod_version,
        description,
        link,
        entries: out,
        payloads,
    })
}

struct Out(Vec<u8>);

impl Out {
    fn u32(&mut self, v: u32) {
        self.0.extend(v.to_le_bytes());
    }
    fn string(&mut self, s: &str) -> Result<()> {
        if s.contains('\0') {
            return Err(bad(W, self.0.len(), format!("string {s:?} holds a zero byte")));
        }
        self.0.extend(s.as_bytes());
        self.0.push(0);
        Ok(())
    }
    fn u32s(&mut self, v: &[u32]) -> Result<()> {
        self.u32(u32::try_from(v.len()).map_err(|_| bad(W, self.0.len(), "list length"))?);
        v.iter().for_each(|&x| self.u32(x));
        Ok(())
    }
}

/// The counterpart of [`read`]. Refused: a version other than 6, a payload index that does not exist, text that is
/// not zero-free, a profile over 255 bytes. SHA-1s are computed from the payloads.
pub fn write(m: &Fbmod) -> Result<Vec<u8>> {
    if m.version != VERSION {
        return Err(bad(W, 8, format!("version {}, expected {VERSION}", m.version)));
    }
    let mut o = Out(Vec::new());
    o.0.extend(MAGIC);
    o.u32(m.version);
    o.0.extend(0u64.to_le_bytes());
    o.u32(u32::try_from(m.payloads.len()).map_err(|_| bad(W, 0, "payload count"))?);
    let profile = u8::try_from(m.profile.len()).map_err(|_| bad(W, FIXED - 1, "profile over 255 bytes"))?;
    o.0.push(profile);
    o.0.extend(m.profile.as_bytes());
    o.u32(m.game_version);
    for s in [
        &m.title,
        &m.author,
        &m.category,
        &m.mod_version,
        &m.description,
        &m.link,
    ] {
        o.string(s)?;
    }
    o.u32(u32::try_from(m.entries.len()).map_err(|_| bad(W, 0, "entry count"))?);
    for e in &m.entries {
        o.0.push(e.kind().id());
        match &e.stored {
            Some(s) => {
                let payload = m.payloads.get(s.index).ok_or_else(|| {
                    bad(
                        W,
                        o.0.len(),
                        format!("payload {} of {}: {}", s.index, m.payloads.len(), e.name),
                    )
                })?;
                o.u32(u32::try_from(s.index).map_err(|_| bad(W, o.0.len(), "payload index"))?);
                o.string(&e.name)?;
                o.0.extend(sha1(payload));
                o.0.extend(s.size.to_le_bytes());
                o.0.push(s.flags);
                o.u32(s.handler);
                o.string(&s.user)?;
            }
            None => {
                o.0.extend((-1i32).to_le_bytes());
                o.string(&e.name)?;
            }
        }
        o.u32s(&e.bundles)?;
        match &e.body {
            Body::Embedded | Body::Ebx => {}
            Body::Res(r) => {
                o.u32(r.res_type);
                o.0.extend(r.rid.to_le_bytes());
                o.u32(u32::try_from(r.meta.len()).map_err(|_| bad(W, o.0.len(), "metadata length"))?);
                o.0.extend(&r.meta);
            }
            Body::Chunk(c) => {
                for v in [
                    c.range_start,
                    c.range_end,
                    c.logical_offset,
                    c.logical_size,
                    c.h32,
                ] {
                    o.u32(v);
                }
                o.0.extend(c.first_mip.to_le_bytes());
                o.u32s(&c.added_bundles)?;
            }
        }
    }
    let table_at = o.0.len() as u64;
    let mut offset = 0u64;
    for p in &m.payloads {
        o.0.extend(offset.to_le_bytes());
        o.0.extend((p.len() as u64).to_le_bytes());
        offset = offset.saturating_add(p.len() as u64);
    }
    for p in &m.payloads {
        o.0.extend(p);
    }
    if let Some(slot) = o.0.get_mut(12..20) {
        slot.copy_from_slice(&table_at.to_le_bytes());
    }
    Ok(o.0)
}

impl Fbmod {
    /// Add `raw` as an uncompressed CAS payload (raw 64 KiB blocks: no encoder or compression settings involved) and
    /// return its index: an identical payload already in the mod is reused.
    pub fn add_payload(&mut self, raw: &[u8]) -> Result<usize> {
        let encoded = CasRaw.compress(raw)?;
        if let Some(i) = self.payloads.iter().position(|p| *p == encoded) {
            return Ok(i);
        }
        self.payloads.push(encoded);
        Ok(self.payloads.len().saturating_sub(1))
    }

    /// Remove the payloads no entry points at (what an entry given a new payload leaves behind), keeping the others in
    /// order and renumbering the entries' indices; return how many were removed.
    pub fn drop_unused_payloads(&mut self) -> usize {
        let mut used = vec![false; self.payloads.len()];
        for s in self.entries.iter().filter_map(|e| e.stored.as_ref()) {
            if let Some(u) = used.get_mut(s.index) {
                *u = true;
            }
        }
        let mut renumbered = Vec::with_capacity(used.len());
        let mut next = 0usize;
        for &u in &used {
            renumbered.push(next);
            next = next.saturating_add(usize::from(u));
        }
        let mut keep = used.iter();
        self.payloads.retain(|_| keep.next().copied().unwrap_or(false));
        for s in self.entries.iter_mut().filter_map(|e| e.stored.as_mut()) {
            if let Some(&n) = renumbered.get(s.index) {
                s.index = n;
            }
        }
        used.len().saturating_sub(next)
    }
}

impl Fbmod {
    /// Payload `i` decoded; `oodle` is needed only for Oodle blocks.
    pub fn payload(&self, i: usize, oodle: Option<&Oodle>) -> Result<Vec<u8>> {
        let raw = self
            .payloads
            .get(i)
            .ok_or_else(|| bad("fbmod", 0, format!("payload {i} of {}", self.payloads.len())))?;
        let size = cas::blocks(raw)?
            .iter()
            .try_fold(0usize, |s, b| s.checked_add(b.decoded_size))
            .ok_or_else(|| bad("fbmod", 0, format!("payload {i} size")))?;
        Ok(Cas { oodle }.decompress(raw, size)?)
    }
}