Skip to main content

unityrs_testkit/ngui/
mod.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/helpers/TypeTreeHelper.py, UnityPy/classes/generated.py. See THIRD_PARTY_LICENSES.
2//! NGUI-shaped atlases for the cutter's reference (`tools/parity/ngui_cutter.py`,
3//! `docs/BATCH_SPEC.md` section 5): the atlas MonoBehaviour with a typetree,
4//! the MonoScript its `m_Script` names, its `Material` and the `Texture2D`
5//! sheets, inline or streamed from a `.resS`, in bundles whose views join
6//! them.
7//!
8//! Every object is a [`V`], a typed value that gives both its typetree nodes
9//! and its little-endian bytes, in the layout UnityPy 1.25.2 reads them by
10//! (`helpers/TypeTreeHelper.py:182-263`): a value whose node is aligned
11//! (a `bool`, a string, `TypelessData`, every vector here) is followed by
12//! zeros up to a multiple of 4, a `pair` is its `first` then its `second`,
13//! and a node whose first child is `Array` is a vector, its count an `int`.
14//! A Material's `m_TexEnvs` holds pairs whose `first` is a string or a
15//! `FastPropertyName` struct with a `name`, as UnityPy types it either way
16//! (`classes/generated.py:11477`).
17//!
18//! A typetree row's level is a `u8`, so [`nodes`], [`write`] and [`file`]
19//! refuse a value deeper than it holds, and a length or count past an
20//! `int`, with a [`BuildError`], before any level is added or any size
21//! narrowed. Each file gives each object a type record of its own, so a
22//! file mixes shapes freely ([`file`]). [`scenes`] lists the scenes
23//! `tools/parity/ngui_scenes.py` asks cargo for.
24//!
25//! Owner: P1b, the NGUI cutter's reference (`docs/plans/extract.md` section 3,
26//! item 3).
27
28mod objects;
29mod scenes;
30mod sprite_atlases;
31mod sprite_objects;
32mod sprites;
33
34pub use objects::{
35    PropName, atlas, format, material, material_tpk, mono_behaviour, mono_script, set_field,
36    sprite, texture, texture_streamed,
37};
38pub use scenes::{AtlasScene, CutOptions, SceneBundle, failure_scenes, scenes};
39pub use sprite_atlases::{AtlasEntry, sprite_atlas};
40pub use sprites::{Mesh, SpriteSpec, packed, sprite_scenes};
41
42use crate::blob::NodeSpec;
43use crate::serialized::{ExternalSpec, ObjectSpec, SerializedSpec, TypeSpec};
44use crate::writer::ByteWriter;
45
46/// A typed value: its typetree nodes and its bytes ([`nodes`], [`write`]).
47#[derive(Clone, Debug, PartialEq)]
48pub enum V {
49    /// `int`.
50    Int(i32),
51    /// `unsigned int`.
52    UInt(u32),
53    /// `UInt8`, unaligned.
54    UInt8(u8),
55    /// `UInt8` with the typetree align-after flag.
56    AlignedUInt8(u8),
57    /// `UInt16`, unaligned.
58    UInt16(u16),
59    /// `UInt64`.
60    UInt64(u64),
61    /// `SInt64`.
62    Int64(i64),
63    /// `bool`, aligned.
64    Bool(bool),
65    /// `float`: UnityPy widens it exactly to a double.
66    Float(f32),
67    /// `double`.
68    Double(f64),
69    /// `string`: an `int` length, the bytes, aligned.
70    Str(Vec<u8>),
71    /// `TypelessData`: an `int` length and the bytes, aligned; UnityPy reads
72    /// it as `bytes`.
73    Bytes(Vec<u8>),
74    /// `PPtr<target>`: `m_FileID`, `m_PathID`.
75    PPtr(String, i32, i64),
76    /// A struct: its type and its fields, in order.
77    Struct(String, Vec<(String, V)>),
78    /// A vector: its node type (`vector`, `map`), the element's shape (for
79    /// the nodes, so an empty vector has them too) and the elements.
80    Vector(String, Box<V>, Vec<V>),
81    /// `pair`: `first`, `second`.
82    Pair(Box<V>, Box<V>),
83}
84
85/// Why a value has no typetree or no bytes.
86#[derive(Clone, Copy, Debug, PartialEq, Eq)]
87pub enum BuildError {
88    /// A row would sit at `level`, past the `u8` a typetree row holds.
89    TooDeep {
90        /// The deepest level the value needs.
91        level: usize,
92    },
93    /// A string's, bytes' or vector's length, past the `int` it is written as.
94    TooLong {
95        /// The length.
96        len: usize,
97    },
98    /// More objects than a type index (`int`) counts.
99    TooManyObjects(usize),
100}
101
102impl std::fmt::Display for BuildError {
103    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
104        match self {
105            Self::TooDeep { level } => write!(f, "a typetree row at level {level}, past 255"),
106            Self::TooLong { len } => write!(f, "a length of {len}, past an int"),
107            Self::TooManyObjects(n) => write!(f, "{n} objects, past an int"),
108        }
109    }
110}
111
112impl std::error::Error for BuildError {}
113
114/// A string value.
115#[must_use]
116pub fn s(text: &str) -> V {
117    V::Str(text.as_bytes().to_vec())
118}
119
120/// A pointer to a `target`.
121#[must_use]
122pub fn pptr(target: &str, at: (i32, i64)) -> V {
123    V::PPtr(target.to_owned(), at.0, at.1)
124}
125
126/// A struct of `ty`.
127#[must_use]
128pub fn st(ty: &str, fields: Vec<(&str, V)>) -> V {
129    V::Struct(
130        ty.to_owned(),
131        fields.into_iter().map(|(n, v)| (n.to_owned(), v)).collect(),
132    )
133}
134
135/// A `vector` of `items`, each shaped as `shape`.
136#[must_use]
137pub fn vector(shape: V, items: Vec<V>) -> V {
138    V::Vector("vector".to_owned(), Box::new(shape), items)
139}
140
141/// A `pair`.
142#[must_use]
143pub fn pair(first: V, second: V) -> V {
144    V::Pair(Box::new(first), Box::new(second))
145}
146
147/// How many levels below its own row `v`'s rows reach, counted without
148/// recursion.
149#[must_use]
150pub fn depth(v: &V) -> usize {
151    let mut deepest = 0;
152    let mut stack = vec![(v, 0usize)];
153    while let Some((v, at)) = stack.pop() {
154        let below = match v {
155            V::Str(_) | V::Vector(..) => 2,
156            V::Bytes(_) | V::PPtr(..) => 1,
157            _ => 0,
158        };
159        deepest = deepest.max(at + below);
160        match v {
161            V::Struct(_, fields) => stack.extend(fields.iter().map(|(_, f)| (f, at + 1))),
162            V::Vector(_, shape, _) => stack.push((shape, at + 2)),
163            V::Pair(first, second) => stack.extend([(&**first, at + 1), (&**second, at + 1)]),
164            _ => {}
165        }
166    }
167    deepest
168}
169
170/// The typetree rows of the field `name` holding `v`, its own row at
171/// `level`; [`BuildError::TooDeep`] when a row would pass level 255.
172pub fn nodes(level: u8, name: &str, v: &V) -> Result<Vec<NodeSpec>, BuildError> {
173    let deepest = usize::from(level) + depth(v);
174    if deepest > usize::from(u8::MAX) {
175        return Err(BuildError::TooDeep { level: deepest });
176    }
177    let mut out = Vec::new();
178    rows(level, name, v, &mut out);
179    Ok(out)
180}
181
182/// [`nodes`]' rows, once the depth is checked: no level below passes 255.
183fn rows(level: u8, name: &str, v: &V, out: &mut Vec<NodeSpec>) {
184    let leaf = |ty: &str, size: i32| NodeSpec::new(level, ty, name).size(size);
185    match v {
186        V::Int(_) => out.push(leaf("int", 4)),
187        V::UInt(_) => out.push(leaf("unsigned int", 4)),
188        V::UInt8(_) => out.push(leaf("UInt8", 1)),
189        V::AlignedUInt8(_) => out.push(leaf("UInt8", 1).aligned()),
190        V::UInt16(_) => out.push(leaf("UInt16", 2)),
191        V::UInt64(_) => out.push(leaf("UInt64", 8)),
192        V::Int64(_) => out.push(leaf("SInt64", 8)),
193        V::Float(_) => out.push(leaf("float", 4)),
194        V::Double(_) => out.push(leaf("double", 8)),
195        V::Bool(_) => out.push(leaf("bool", 1).aligned()),
196        V::Str(_) => out.extend([
197            leaf("string", -1),
198            NodeSpec::new(level + 1, "Array", "Array")
199                .size(-1)
200                .aligned(),
201            NodeSpec::new(level + 2, "int", "size").size(4),
202            NodeSpec::new(level + 2, "char", "data").size(1),
203        ]),
204        V::Bytes(_) => out.extend([
205            leaf("TypelessData", -1).aligned(),
206            NodeSpec::new(level + 1, "int", "size").size(4),
207            NodeSpec::new(level + 1, "UInt8", "data").size(1),
208        ]),
209        V::PPtr(target, ..) => out.extend([
210            leaf(&format!("PPtr<{target}>"), 12),
211            NodeSpec::new(level + 1, "int", "m_FileID").size(4),
212            NodeSpec::new(level + 1, "SInt64", "m_PathID").size(8),
213        ]),
214        V::Struct(ty, fields) => {
215            out.push(leaf(ty, -1));
216            for (n, f) in fields {
217                rows(level + 1, n, f, out);
218            }
219        }
220        V::Vector(ty, shape, _) => {
221            out.extend([
222                leaf(ty, -1),
223                NodeSpec::new(level + 1, "Array", "Array")
224                    .size(-1)
225                    .aligned(),
226                NodeSpec::new(level + 2, "int", "size").size(4),
227            ]);
228            rows(level + 2, "data", shape, out);
229        }
230        V::Pair(first, second) => {
231            out.push(leaf("pair", -1));
232            rows(level + 1, "first", first, out);
233            rows(level + 1, "second", second, out);
234        }
235    }
236}
237
238fn len_i32(len: usize) -> Result<i32, BuildError> {
239    i32::try_from(len).map_err(|_| BuildError::TooLong { len })
240}
241
242/// `v`'s bytes, in the order and alignment [`nodes`] describes; refuses a
243/// value [`nodes`] refuses at level 0, and a length past an `int`.
244pub fn write(w: &mut ByteWriter, v: &V) -> Result<(), BuildError> {
245    let deepest = depth(v);
246    if deepest > usize::from(u8::MAX) {
247        return Err(BuildError::TooDeep { level: deepest });
248    }
249    bytes(w, v)
250}
251
252fn bytes(w: &mut ByteWriter, v: &V) -> Result<(), BuildError> {
253    match v {
254        V::Int(x) => {
255            w.i32(*x);
256        }
257        V::UInt(x) => {
258            w.u32(*x);
259        }
260        V::UInt8(x) => {
261            w.u8(*x);
262        }
263        V::AlignedUInt8(x) => {
264            w.u8(*x).align(4);
265        }
266        V::UInt16(x) => {
267            w.u16(*x);
268        }
269        V::UInt64(x) => {
270            w.u64(*x);
271        }
272        V::Int64(x) => {
273            w.i64(*x);
274        }
275        V::Float(x) => {
276            w.f32(*x);
277        }
278        V::Double(x) => {
279            w.f64(*x);
280        }
281        V::Bool(x) => {
282            w.bool(*x).align(4);
283        }
284        V::Str(b) | V::Bytes(b) => {
285            w.i32(len_i32(b.len())?).bytes(b).align(4);
286        }
287        V::PPtr(_, file, path) => {
288            w.i32(*file).i64(*path);
289        }
290        V::Struct(_, fields) => {
291            for (_, f) in fields {
292                bytes(w, f)?;
293            }
294        }
295        V::Vector(_, _, items) => {
296            w.i32(len_i32(items.len())?);
297            for item in items {
298                bytes(w, item)?;
299            }
300            w.align(4);
301        }
302        V::Pair(first, second) => {
303            bytes(w, first)?;
304            bytes(w, second)?;
305        }
306    }
307    Ok(())
308}
309
310/// One object: its path id, class id and value (a [`V::Struct`] whose type
311/// is the class's name, written as the root node `Base`), its bytes cut to
312/// `cut` when that is set (a read that runs out), and `trailing` zero bytes
313/// stored after them (a read that ends before the object does, which
314/// UnityPy's `check_read` refuses).
315#[derive(Clone, Debug, PartialEq)]
316pub struct Object {
317    /// `path_id`.
318    pub path_id: i64,
319    /// The class id.
320    pub class_id: i32,
321    /// The value.
322    pub value: V,
323    /// The object's stored bytes are the value's first `cut`.
324    pub cut: Option<usize>,
325    /// Zero bytes stored after the value's (or the cut's).
326    pub trailing: usize,
327}
328
329impl Object {
330    /// An object of `class_id` holding `value`.
331    #[must_use]
332    pub fn new(path_id: i64, class_id: i32, value: V) -> Self {
333        Self {
334            path_id,
335            class_id,
336            value,
337            cut: None,
338            trailing: 0,
339        }
340    }
341
342    /// The same object, its stored bytes cut to their first `n`.
343    #[must_use]
344    pub fn cut_to(mut self, n: usize) -> Self {
345        self.cut = Some(n);
346        self
347    }
348
349    /// The same object with `n` zero bytes stored after its value.
350    #[must_use]
351    pub fn with_trailing(mut self, n: usize) -> Self {
352        self.trailing = n;
353        self
354    }
355}
356
357/// A `SerializedFile` (format 22, little-endian, engine 2022.3.0f1) of
358/// `objects`, each with a type record of its own, with the given externals
359/// (`archive:/CAB-x/CAB-x`). With `type_trees` false it stores no typetree,
360/// so UnityPy reads its objects by the TPK's.
361pub fn file(
362    externals: &[&str],
363    objects: &[Object],
364    type_trees: bool,
365) -> Result<Vec<u8>, BuildError> {
366    file_on(None, externals, objects, type_trees)
367}
368
369/// [`file`], its target platform `platform` (a `BuildTarget` value) when
370/// that is set, else the default's.
371pub fn file_on(
372    platform: Option<i32>,
373    externals: &[&str],
374    objects: &[Object],
375    type_trees: bool,
376) -> Result<Vec<u8>, BuildError> {
377    let base = SerializedSpec::default();
378    let mut types = Vec::new();
379    let mut objs = Vec::new();
380    for (i, o) in objects.iter().enumerate() {
381        let type_id = i32::try_from(i).map_err(|_| BuildError::TooManyObjects(objects.len()))?;
382        // Format 22 keeps the class id in the type record (an `int`); an
383        // object row holds one only below format 16.
384        let class_id = u16::try_from(o.class_id).unwrap_or(0);
385        types.push(TypeSpec {
386            class_id: o.class_id,
387            nodes: nodes(0, "Base", &o.value)?,
388            ..TypeSpec::default()
389        });
390        let mut w = ByteWriter::le();
391        write(&mut w, &o.value)?;
392        let mut data = w.into_inner();
393        if let Some(n) = o.cut {
394            data.truncate(n);
395        }
396        data.resize(data.len() + o.trailing, 0);
397        objs.push(ObjectSpec {
398            path_id: o.path_id,
399            type_id,
400            class_id,
401            data,
402            ..ObjectSpec::default()
403        });
404    }
405    Ok(crate::serialized::build(&SerializedSpec {
406        platform: platform.unwrap_or(base.platform),
407        type_trees,
408        types,
409        objects: objs,
410        externals: externals
411            .iter()
412            .map(|p| ExternalSpec {
413                path: p.as_bytes().to_vec(),
414                ..ExternalSpec::default()
415            })
416            .collect(),
417        ..SerializedSpec::default()
418    }))
419}
420
421/// Pixel `(x, y)` of a sheet, `y` counted from the image's top (the row
422/// order `Texture2D.image` gives, after UnityPy's flip):
423/// `[base + x + 16 y, 0x40 + x, 0x80 + y, 0xFF - x - y]`, each byte
424/// wrapping, the last left out for RGB24. Every channel of a sheet up to
425/// 15 x 15 is distinct from the zeros a crop pads with.
426#[must_use]
427pub fn pixel(base: u8, x: u8, y: u8) -> [u8; 4] {
428    [
429        base.wrapping_add(x).wrapping_add(y.wrapping_mul(16)),
430        0x40u8.wrapping_add(x),
431        0x80u8.wrapping_add(y),
432        0xFFu8.wrapping_sub(x).wrapping_sub(y),
433    ]
434}
435
436/// A sheet's `image_data` as Unity stores it, bottom row first, of
437/// [`pixel`]s: 4 bytes a pixel, or 3 (`rgb`).
438#[must_use]
439pub fn sheet(base: u8, width: u8, height: u8, rgb: bool) -> Vec<u8> {
440    let mut out = Vec::new();
441    for row in 0..height {
442        let y = height - 1 - row;
443        for x in 0..width {
444            let p = pixel(base, x, y);
445            out.extend_from_slice(if rgb { &p[..3] } else { &p });
446        }
447    }
448    out
449}
450
451#[cfg(test)]
452mod tests {
453    use super::{BuildError, Object, V, depth, file, nodes, pixel, s, sheet, st, vector, write};
454    use crate::writer::ByteWriter;
455
456    #[test]
457    fn a_struct_writes_its_fields_aligned_where_unity_aligns_them() {
458        let v = st(
459            "T",
460            vec![("b", V::Bool(true)), ("n", s("abcde")), ("i", V::Int(-2))],
461        );
462        let mut w = ByteWriter::le();
463        write(&mut w, &v).unwrap();
464        let mut want = vec![1, 0, 0, 0, 5, 0, 0, 0];
465        want.extend_from_slice(b"abcde\0\0\0");
466        want.extend_from_slice(&(-2i32).to_le_bytes());
467        assert_eq!(w.into_inner(), want);
468        let n = nodes(0, "Base", &v).unwrap();
469        let names: Vec<_> = n.iter().map(|x| (x.level, x.name.clone())).collect();
470        assert_eq!(names[0], (0, b"Base".to_vec()));
471        assert_eq!(names[1], (1, b"b".to_vec()));
472        assert_eq!(names[2], (1, b"n".to_vec()));
473        assert_eq!(names[3], (2, b"Array".to_vec()));
474    }
475
476    #[test]
477    fn an_empty_vector_still_has_its_element_nodes() {
478        let v = vector(V::Int(0), Vec::new());
479        assert_eq!(nodes(1, "v", &v).unwrap().len(), 4);
480        let mut w = ByteWriter::le();
481        write(&mut w, &v).unwrap();
482        assert_eq!(w.into_inner(), [0, 0, 0, 0]);
483    }
484
485    /// A struct nested `n` deep, holding an `int`.
486    fn nested(n: usize) -> V {
487        (0..n).fold(V::Int(0), |inner, _| st("S", vec![("f", inner)]))
488    }
489
490    #[test]
491    fn the_deepest_row_a_level_holds_is_255() {
492        // A string's rows reach two below it: at 253 its last is 255.
493        assert_eq!(
494            nodes(253, "n", &s("x")).unwrap().last().map(|r| r.level),
495            Some(255)
496        );
497        assert_eq!(
498            nodes(254, "n", &s("x")),
499            Err(BuildError::TooDeep { level: 256 })
500        );
501        assert_eq!(nodes(255, "n", &V::Int(0)).unwrap().len(), 1);
502        assert_eq!(nodes(0, "Base", &nested(255)).unwrap().len(), 256);
503        assert_eq!(
504            nodes(0, "Base", &nested(256)),
505            Err(BuildError::TooDeep { level: 256 })
506        );
507    }
508
509    #[test]
510    fn a_value_too_deep_for_a_typetree_is_refused_before_it_is_written() {
511        let deep = nested(1_000);
512        assert_eq!(depth(&deep), 1_000);
513        let mut w = ByteWriter::le();
514        assert_eq!(
515            write(&mut w, &deep),
516            Err(BuildError::TooDeep { level: 1_000 })
517        );
518        assert!(w.into_inner().is_empty(), "nothing is written first");
519        let object = Object::new(1, 114, deep);
520        assert_eq!(
521            file(&[], &[object], true),
522            Err(BuildError::TooDeep { level: 1_000 })
523        );
524        // A class id past a `u16` (`SpriteAtlas`'s) is the type record's.
525        let object = Object::new(1, 687_078_895, V::Int(0));
526        assert!(file(&[], &[object], true).is_ok());
527    }
528
529    #[test]
530    fn a_cut_object_stores_its_first_bytes_and_trailing_ones_after() {
531        let whole = file(
532            &[],
533            &[Object::new(1, 49, st("T", vec![("i", V::Int(7))]))],
534            true,
535        )
536        .unwrap();
537        let cut = file(
538            &[],
539            &[Object::new(1, 49, st("T", vec![("i", V::Int(7))])).cut_to(2)],
540            true,
541        )
542        .unwrap();
543        assert!(cut.len() < whole.len());
544        let longer = file(
545            &[],
546            &[Object::new(1, 49, st("T", vec![("i", V::Int(7))])).with_trailing(16)],
547            true,
548        )
549        .unwrap();
550        assert_eq!(longer.len(), whole.len() + 16);
551    }
552
553    #[test]
554    fn a_sheet_is_stored_bottom_row_first() {
555        let data = sheet(1, 2, 2, false);
556        assert_eq!(&data[..4], &pixel(1, 0, 1));
557        assert_eq!(&data[12..], &pixel(1, 1, 0));
558        assert_eq!(sheet(1, 2, 2, true).len(), 12);
559    }
560}