Skip to main content

frostbite_formats/
db.rs

1//! Frostbite's native DB (binary object tree): `layout.toc` (behind the TOC envelope) and the chunk metadata of a
2//! bundle manifest. A node is a type tag (bit 7: unnamed), a name, then a container (1 list, 2 object: varint size,
3//! children, optional terminator), a sized blob (7 string, 19 blob) or a fixed-size value.
4
5use crate::toc::{ENVELOPE, MAGIC};
6use crate::{Rd, Result, bad, latin1};
7
8const W: &str = "native db";
9
10/// A node of the native DB tree: a type tag, an optional name, and either children (lists and objects), a payload
11/// (strings, blobs and fixed-size values) or neither.
12#[derive(Clone, Debug, PartialEq, Eq, Default)]
13pub struct Node {
14    /// The type tag: the low 5 bits of the stored tag byte (1 list, 2 object, 7 string, 19 blob, 8 and 11 four-byte values, and so on). 0 marks the end of a container.
15    pub ty: u8,
16    /// Whether the node has a name: bit 7 of the tag byte is clear.
17    pub named: bool,
18    /// Whether a container's children ended with an explicit zero tag, so that writing it back reproduces the bytes.
19    pub terminated: bool,
20    /// The node's name as Latin-1 text; empty when the node is unnamed.
21    pub name: String,
22    /// The stored bytes of a string, blob or fixed-size value (a string keeps its zero terminator); empty for containers.
23    pub payload: Vec<u8>,
24    /// The nodes of a list or object, in stored order; empty for other types.
25    pub children: Vec<Node>,
26}
27
28impl Node {
29    /// The named child `key` of an object, if there is one.
30    pub fn field(&self, key: &str) -> Option<&Node> {
31        self.children.iter().find(|c| c.named && c.name == key)
32    }
33    /// A string node's text without its terminator.
34    pub fn text(&self) -> String {
35        let t = self.payload.strip_suffix(&[0]).unwrap_or(&self.payload);
36        t.iter().map(|&b| char::from(b)).collect()
37    }
38    /// The value of a 32-bit integer node (type 8), `None` for any other node.
39    pub fn u32(&self) -> Option<u32> {
40        match (self.ty, self.payload.as_slice()) {
41            (8, &[a, b, c, d]) => Some(u32::from_le_bytes([a, b, c, d])),
42            _ => None,
43        }
44    }
45}
46
47fn fixed_size(ty: u8) -> Option<usize> {
48    Some(match ty {
49        6 => 1,
50        8 | 11 => 4,
51        9 | 12 => 8,
52        15 => 16,
53        16 => 20,
54        _ => return None,
55    })
56}
57
58fn varint(r: &Rd, mut pos: usize) -> Result<(usize, usize)> {
59    let (mut v, mut shift) = (0usize, 0u32);
60    loop {
61        let b = r.u8(pos)?;
62        pos = pos.saturating_add(1);
63        if shift > 56 {
64            return Err(bad(W, pos, "varint too long: expected at most 9 bytes"));
65        }
66        v |= usize::from(b & 127) << shift;
67        if b & 128 == 0 {
68            return Ok((v, pos));
69        }
70        shift = shift.saturating_add(7);
71    }
72}
73
74/// How deep containers may nest: the game's files nest a handful of levels, and the reader recurses once per level, so a
75/// file of nested lists must be refused, not left to overflow the stack.
76pub const MAX_DEPTH: usize = 64;
77
78/// One node at `pos`; the position after it.
79pub fn read_node(data: &[u8], pos: usize) -> Result<(Node, usize)> {
80    read_at(data, pos, 0)
81}
82
83fn read_at(data: &[u8], pos: usize, depth: usize) -> Result<(Node, usize)> {
84    let r = Rd::new(data, W);
85    let tag = r.u8(pos)?;
86    let mut pos = pos.saturating_add(1);
87    let mut n = Node {
88        ty: tag & 31,
89        ..Node::default()
90    };
91    if n.ty == 0 {
92        return Ok((n, pos));
93    }
94    n.named = tag & 128 == 0;
95    if n.named {
96        n.name = r.cstr(pos)?;
97        // one byte a character (Latin-1): the bytes read, not the UTF-8 length of the String they became
98        pos = pos.saturating_add(n.name.chars().count()).saturating_add(1);
99    }
100    match n.ty {
101        1 | 2 => {
102            if depth >= MAX_DEPTH {
103                return Err(bad(
104                    W,
105                    pos,
106                    format!("containers nest deeper than {MAX_DEPTH} levels"),
107                ));
108            }
109            let (size, p) = varint(&r, pos)?;
110            let end = p.saturating_add(size);
111            pos = p;
112            while pos < end {
113                let (child, p) = read_at(data, pos, depth.saturating_add(1))?;
114                pos = p;
115                if child.ty == 0 {
116                    n.terminated = true;
117                    break;
118                }
119                n.children.push(child);
120            }
121            if pos != end {
122                return Err(bad(W, pos, "container length mismatch"));
123            }
124        }
125        7 | 19 => {
126            let (size, p) = varint(&r, pos)?;
127            n.payload = r.bytes(p, size)?.to_vec();
128            pos = p.saturating_add(size);
129        }
130        t => {
131            let size = fixed_size(t).ok_or_else(|| bad(W, pos, format!("unsupported value type {t}")))?;
132            n.payload = r.bytes(pos, size)?.to_vec();
133            pos = pos.saturating_add(size);
134        }
135    }
136    Ok((n, pos))
137}
138
139fn put_varint(out: &mut Vec<u8>, mut v: usize) {
140    loop {
141        let b = u8::try_from(v & 127).unwrap_or(0);
142        v >>= 7;
143        if v == 0 {
144            out.push(b);
145            return;
146        }
147        out.push(b | 128);
148    }
149}
150
151/// Append `n` and its children to `out`, the counterpart of [`read_node`]. Refused: a name that is not Latin-1, a
152/// fixed-size value of the wrong length, a type this module does not know.
153pub fn write_node(n: &Node, out: &mut Vec<u8>) -> Result<()> {
154    if n.ty == 0 {
155        out.push(0);
156        return Ok(());
157    }
158    out.push(n.ty | if n.named { 0 } else { 128 });
159    if n.named {
160        out.extend(latin1(&n.name, W)?);
161        out.push(0);
162    }
163    match n.ty {
164        1 | 2 => {
165            let mut body = Vec::new();
166            for c in &n.children {
167                write_node(c, &mut body)?;
168            }
169            if n.terminated {
170                body.push(0);
171            }
172            put_varint(out, body.len());
173            out.extend(body);
174        }
175        7 | 19 => {
176            put_varint(out, n.payload.len());
177            out.extend(&n.payload);
178        }
179        t => {
180            if fixed_size(t) != Some(n.payload.len()) {
181                return Err(bad(
182                    W,
183                    out.len(),
184                    format!("value of type {t} has {} bytes", n.payload.len()),
185                ));
186            }
187            out.extend(&n.payload);
188        }
189    }
190    Ok(())
191}
192
193/// A DB file behind the TOC envelope: (envelope bytes, root, trailing bytes).
194pub fn read_file(data: &[u8]) -> Result<(Vec<u8>, Node, Vec<u8>)> {
195    let (envelope, body) = data
196        .split_at_checked(ENVELOPE)
197        .filter(|(envelope, body)| !body.is_empty() && envelope.starts_with(&MAGIC))
198        .ok_or_else(|| {
199            bad(
200                W,
201                0,
202                format!(
203                    "unrecognised envelope: expected the magic {MAGIC:02x?} and more than {ENVELOPE} bytes"
204                ),
205            )
206        })?;
207    let (root, pos) = read_node(data, ENVELOPE)?;
208    let trailer = body.get(pos.saturating_sub(ENVELOPE)..).unwrap_or_default();
209    Ok((envelope.to_vec(), root, trailer.to_vec()))
210}
211
212/// A DB file: `envelope`, the tree and `trailer`, the counterpart of [`read_file`].
213pub fn write_file(envelope: &[u8], root: &Node, trailer: &[u8]) -> Result<Vec<u8>> {
214    let mut out = envelope.to_vec();
215    write_node(root, &mut out)?;
216    out.extend(trailer);
217    Ok(out)
218}