Skip to main content

unityrs_testkit/env/
mod.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/helpers/ImportHelper.py. See THIRD_PARTY_LICENSES.
2//! Multi-file scenes for the `Environment` tests: bundles whose objects
3//! point into each other, resources in sibling entries and in other bundles.
4//!
5//! A scene is the files a caller loads, in order, and the files a resolver
6//! can return (UnityPy's `env.path`). Every object is one of three shapes,
7//! each with its own type record so a file may mix them freely:
8//!
9//! - a named object ([`Obj::named`]): `m_Name` and `m_Ptr0`, `m_Ptr1`, ...
10//!   (`PPtr<Object>`), as class 1;
11//! - a streamed texture ([`Obj::streamed`]): `m_Name` and `m_StreamData`
12//!   (`offset`, `size`, `path`), as class 28;
13//! - an AssetBundle ([`Obj::asset_bundle`]): `m_Name`, `m_PreloadTable`,
14//!   `m_Container` and, unless left out, `m_MainAsset`, as class 142.
15//!
16//! `tools/fixtures/env.py` asks cargo for [`scenes`] and records what
17//! UnityPy 1.25.2 does with each (`crates/unityrs-core/tests/fixtures/d/`).
18//!
19//! Owner: package D.
20
21mod catalog;
22
23pub use catalog::{
24    FindAsk, FindScene, asset_bundle_modes, bad_cab, container_other_file, cross_bundle_pointer,
25    dependency_reads, dependency_scenes, deref_rules, deref_sibling_nested, fallback_file_pointer,
26    find_file_kinds, find_file_listing, find_scenes, last_block_fails, listings, listings_raced,
27    loose_external_pointer, nested_after_cab, nested_between_loads, nested_dropped_evicted,
28    nested_duplicates, nested_evicted, nested_raw_replaced, nested_reloaded, nested_reloaded_spans,
29    nested_reloaded_spans_raced, nested_replaced_unread, preload_below_start,
30    preload_loads_new_cab, preload_nested_external, preload_paths, preload_raw_target,
31    preload_revisits_after_load, preload_revisits_ahead, preload_skips, race_scenes,
32    resolver_loads, resource_in_nested_cab, resource_in_own_nested, scenes, web_file,
33};
34
35use crate::blob::NodeSpec;
36use crate::bundle::{BundleSpec, EntrySpec};
37use crate::serialized::{ExternalSpec, ObjectSpec, SerializedSpec, TypeSpec};
38use crate::writer::ByteWriter;
39
40/// Named files, as a caller would load them.
41#[derive(Clone, Debug, Default, PartialEq, Eq)]
42pub struct Scene {
43    /// `(name, bytes)` in load order.
44    pub files: Vec<(Vec<u8>, Vec<u8>)>,
45    /// `(name, bytes)` a resolver may return (UnityPy's `env.path`): a
46    /// `find_file` or a resource fallback asking for exactly `name` gets the
47    /// file (UnityPy's case-insensitive search never matches a name without
48    /// a directory, `helpers/ImportHelper.py:159-173`).
49    pub resolver: Vec<(Vec<u8>, Vec<u8>)>,
50}
51
52/// A scene some of whose loads are dependencies (UnityPy's
53/// `load_file(..., is_dependency=True)`, the core's
54/// `Environment::load_dependency`).
55#[derive(Clone, Debug, Default, PartialEq, Eq)]
56pub struct DepScene {
57    /// The files, in load order.
58    pub scene: Scene,
59    /// The indexes of `scene.files` loaded as dependencies.
60    pub dependencies: Vec<usize>,
61}
62
63/// A scene whose container preload walk races a load another thread makes:
64/// `other` is loaded at one point of the walk, each in turn
65/// (`tools/fixtures/env.py` records UnityPy's walk with the load made at
66/// each point and, for a load of more than one key, with only its first key
67/// made there). Exactly one file of the scene holds an AssetBundle, so the
68/// walk is of one table; `other` registers only keys a file of the scene
69/// registered first, so UnityPy's pass, which fails when its dict of CABs
70/// grows under it, finishes wherever the load is made.
71#[derive(Clone, Debug, Default, PartialEq, Eq)]
72pub struct RaceScene {
73    /// The files loaded before the walk, and the resolver's.
74    pub scene: Scene,
75    /// `(name, bytes)` of the load made while the walk runs.
76    pub other: (Vec<u8>, Vec<u8>),
77}
78
79/// One container row: the path, its preload span and the asset pointer.
80#[derive(Clone, Debug, PartialEq, Eq)]
81pub struct Row {
82    /// The container path.
83    pub path: Vec<u8>,
84    /// `preloadIndex`.
85    pub preload_index: i32,
86    /// `preloadSize`.
87    pub preload_size: i32,
88    /// `asset` as `(m_FileID, m_PathID)`.
89    pub asset: (i32, i64),
90}
91
92/// The AssetBundle's fields.
93#[derive(Clone, Debug, Default, PartialEq, Eq)]
94pub struct Bundle {
95    /// `m_PreloadTable`.
96    pub preload: Vec<(i32, i64)>,
97    /// `m_Container`.
98    pub rows: Vec<Row>,
99    /// Leaves `m_MainAsset` out (UnityPy then builds an `UnknownObject`).
100    pub no_main_asset: bool,
101    /// Leaves `m_Container` out (object mode then has no such attribute).
102    pub no_container: bool,
103    /// Adds a second field named `m.Container` after `m_Container` (the two
104    /// clean to one key; object mode keeps the last).
105    pub shadow_container: Option<Vec<Row>>,
106    /// Writes `m_Container` and `m_PreloadTable` as a damaged tree can hold
107    /// them: each pair's key an `int` (the row's position) instead of a
108    /// `string`, `preloadIndex` a `float`, `preloadSize` named `preloadSizX`,
109    /// the asset's `m_FileID` a `float`, and each preload pointer with a
110    /// third child, `m_Extra` (an `int`, written as 0). UnityPy still loads
111    /// the file: its load reads only each asset's `path_id`.
112    pub hostile: bool,
113}
114
115/// What an object holds.
116#[derive(Clone, Debug, PartialEq, Eq)]
117pub enum Body {
118    /// `m_Name` and pointers `m_Ptr0`, `m_Ptr1`, ...
119    Named(Vec<(i32, i64)>),
120    /// `m_Name` and `m_StreamData` (`offset`, `size`, `path`).
121    Streamed {
122        /// `m_StreamData.path`.
123        path: Vec<u8>,
124        /// `m_StreamData.offset`.
125        offset: u64,
126        /// `m_StreamData.size`.
127        size: u32,
128    },
129    /// An AssetBundle.
130    AssetBundle(Bundle),
131}
132
133/// One object.
134#[derive(Clone, Debug, PartialEq, Eq)]
135pub struct Obj {
136    /// Its path id.
137    pub path_id: i64,
138    /// `m_Name`.
139    pub name: Vec<u8>,
140    /// Its fields.
141    pub body: Body,
142}
143
144impl Obj {
145    /// A named object (class 1) with pointers.
146    #[must_use]
147    pub fn named(path_id: i64, name: &str, ptrs: &[(i32, i64)]) -> Self {
148        Self {
149            path_id,
150            name: name.as_bytes().to_vec(),
151            body: Body::Named(ptrs.to_vec()),
152        }
153    }
154
155    /// A streamed texture (class 28) reading `size` bytes at `offset` of
156    /// `path`.
157    #[must_use]
158    pub fn streamed(path_id: i64, name: &str, path: &str, offset: u64, size: u32) -> Self {
159        Self {
160            path_id,
161            name: name.as_bytes().to_vec(),
162            body: Body::Streamed {
163                path: path.as_bytes().to_vec(),
164                offset,
165                size,
166            },
167        }
168    }
169
170    /// An AssetBundle (class 142).
171    #[must_use]
172    pub fn asset_bundle(path_id: i64, bundle: Bundle) -> Self {
173        Self {
174            path_id,
175            name: b"bundle".to_vec(),
176            body: Body::AssetBundle(bundle),
177        }
178    }
179}
180
181/// A row pointing at `asset`, with its preload span.
182#[must_use]
183pub fn row(path: &str, preload: (i32, i32), asset: (i32, i64)) -> Row {
184    Row {
185        path: path.as_bytes().to_vec(),
186        preload_index: preload.0,
187        preload_size: preload.1,
188        asset,
189    }
190}
191
192fn string_nodes(level: u8, name: &str) -> Vec<NodeSpec> {
193    vec![
194        NodeSpec::new(level, "string", name),
195        NodeSpec::new(level + 1, "Array", "Array")
196            .size(-1)
197            .aligned(),
198        NodeSpec::new(level + 2, "int", "size").size(4),
199        NodeSpec::new(level + 2, "char", "data").size(1),
200    ]
201}
202
203fn pptr_nodes(level: u8, name: &str) -> Vec<NodeSpec> {
204    vec![
205        NodeSpec::new(level, "PPtr<Object>", name).size(12),
206        NodeSpec::new(level + 1, "int", "m_FileID").size(4),
207        NodeSpec::new(level + 1, "SInt64", "m_PathID").size(8),
208    ]
209}
210
211fn asset_info_nodes(level: u8, name: &str) -> Vec<NodeSpec> {
212    let mut n = vec![
213        NodeSpec::new(level, "AssetInfo", name),
214        NodeSpec::new(level + 1, "int", "preloadIndex").size(4),
215        NodeSpec::new(level + 1, "int", "preloadSize").size(4),
216    ];
217    n.extend(pptr_nodes(level + 1, "asset"));
218    n
219}
220
221/// [`Bundle::hostile`]'s `AssetInfo`.
222fn hostile_asset_info_nodes(level: u8, name: &str) -> Vec<NodeSpec> {
223    vec![
224        NodeSpec::new(level, "AssetInfo", name),
225        NodeSpec::new(level + 1, "float", "preloadIndex").size(4),
226        NodeSpec::new(level + 1, "int", "preloadSizX").size(4),
227        NodeSpec::new(level + 1, "PPtr<Object>", "asset").size(12),
228        NodeSpec::new(level + 2, "float", "m_FileID").size(4),
229        NodeSpec::new(level + 2, "SInt64", "m_PathID").size(8),
230    ]
231}
232
233fn container_nodes(name: &str, hostile: bool) -> Vec<NodeSpec> {
234    let mut n = vec![
235        NodeSpec::new(1, "map", name),
236        NodeSpec::new(2, "Array", "Array").size(-1),
237        NodeSpec::new(3, "int", "size").size(4),
238        NodeSpec::new(3, "pair", "data"),
239    ];
240    if hostile {
241        n.push(NodeSpec::new(4, "int", "first").size(4));
242        n.extend(hostile_asset_info_nodes(4, "second"));
243    } else {
244        n.extend(string_nodes(4, "first"));
245        n.extend(asset_info_nodes(4, "second"));
246    }
247    n
248}
249
250fn put_string(w: &mut ByteWriter, s: &[u8]) {
251    w.i32(i32::try_from(s.len()).unwrap_or(i32::MAX))
252        .bytes(s)
253        .align(4);
254}
255
256fn put_pptr(w: &mut ByteWriter, p: (i32, i64)) {
257    w.i32(p.0).i64(p.1);
258}
259
260fn put_rows(w: &mut ByteWriter, rows: &[Row], hostile: bool) {
261    w.i32(i32::try_from(rows.len()).unwrap_or(i32::MAX));
262    for (i, r) in rows.iter().enumerate() {
263        if hostile {
264            // Small values: each is exact as an `f32`.
265            #[allow(clippy::cast_precision_loss)]
266            let (index, file_id) = (r.preload_index as f32, r.asset.0 as f32);
267            w.i32(i32::try_from(i).unwrap_or(i32::MAX))
268                .f32(index)
269                .i32(r.preload_size)
270                .f32(file_id)
271                .i64(r.asset.1);
272        } else {
273            put_string(w, &r.path);
274            w.i32(r.preload_index).i32(r.preload_size);
275            put_pptr(w, r.asset);
276        }
277    }
278}
279
280/// The class id, tree and little-endian bytes of `o`.
281fn shape(o: &Obj) -> (i32, Vec<NodeSpec>, Vec<u8>) {
282    let mut w = ByteWriter::le();
283    match &o.body {
284        Body::Named(ptrs) => {
285            let mut nodes = vec![NodeSpec::new(0, "GameObject", "Base")];
286            nodes.extend(string_nodes(1, "m_Name"));
287            put_string(&mut w, &o.name);
288            for (i, p) in ptrs.iter().enumerate() {
289                nodes.extend(pptr_nodes(1, &format!("m_Ptr{i}")));
290                put_pptr(&mut w, *p);
291            }
292            (1, nodes, w.into_inner())
293        }
294        Body::Streamed { path, offset, size } => {
295            let mut nodes = vec![NodeSpec::new(0, "Texture2D", "Base")];
296            nodes.extend(string_nodes(1, "m_Name"));
297            nodes.push(NodeSpec::new(1, "StreamingInfo", "m_StreamData"));
298            nodes.push(NodeSpec::new(2, "UInt64", "offset").size(8));
299            nodes.push(NodeSpec::new(2, "unsigned int", "size").size(4));
300            nodes.extend(string_nodes(2, "path"));
301            put_string(&mut w, &o.name);
302            w.u64(*offset).u32(*size);
303            put_string(&mut w, path);
304            (28, nodes, w.into_inner())
305        }
306        Body::AssetBundle(b) => {
307            let mut nodes = vec![NodeSpec::new(0, "AssetBundle", "Base")];
308            nodes.extend(string_nodes(1, "m_Name"));
309            put_string(&mut w, &o.name);
310            nodes.push(NodeSpec::new(1, "vector", "m_PreloadTable"));
311            nodes.push(NodeSpec::new(2, "Array", "Array").size(-1));
312            nodes.push(NodeSpec::new(3, "int", "size").size(4));
313            nodes.extend(pptr_nodes(3, "data"));
314            if b.hostile {
315                nodes.push(NodeSpec::new(4, "int", "m_Extra").size(4));
316            }
317            w.i32(i32::try_from(b.preload.len()).unwrap_or(i32::MAX));
318            for p in &b.preload {
319                put_pptr(&mut w, *p);
320                if b.hostile {
321                    w.i32(0);
322                }
323            }
324            if !b.no_container {
325                nodes.extend(container_nodes("m_Container", b.hostile));
326                put_rows(&mut w, &b.rows, b.hostile);
327            }
328            if let Some(shadow) = &b.shadow_container {
329                nodes.extend(container_nodes("m.Container", b.hostile));
330                put_rows(&mut w, shadow, b.hostile);
331            }
332            if !b.no_main_asset {
333                nodes.extend(asset_info_nodes(1, "m_MainAsset"));
334                w.i32(0).i32(0);
335                put_pptr(&mut w, (0, 0));
336            }
337            (142, nodes, w.into_inner())
338        }
339    }
340}
341
342/// A `SerializedFile` (format 22, little-endian, type trees on) holding
343/// `objects`, each with its own type record, and the given external paths.
344#[must_use]
345pub fn serialized(externals: &[&str], objects: &[Obj]) -> Vec<u8> {
346    let mut types = Vec::new();
347    let mut objs = Vec::new();
348    for (i, o) in objects.iter().enumerate() {
349        let (class_id, nodes, data) = shape(o);
350        types.push(TypeSpec {
351            class_id,
352            nodes,
353            ..TypeSpec::default()
354        });
355        objs.push(ObjectSpec {
356            path_id: o.path_id,
357            type_id: i32::try_from(i).unwrap_or(i32::MAX),
358            class_id: u16::try_from(class_id).unwrap_or(0),
359            data,
360            ..ObjectSpec::default()
361        });
362    }
363    crate::serialized::build(&SerializedSpec {
364        types,
365        objects: objs,
366        externals: externals
367            .iter()
368            .map(|p| ExternalSpec {
369                path: p.as_bytes().to_vec(),
370                ..ExternalSpec::default()
371            })
372            .collect(),
373        ..SerializedSpec::default()
374    })
375}
376
377/// A UnityFS bundle (LZ4 blocks of 160 bytes) of `entries`.
378#[must_use]
379pub fn bundle(entries: &[(&str, Vec<u8>)]) -> Vec<u8> {
380    crate::bundle::build(&bundle_spec(entries))
381}
382
383fn bundle_spec(entries: &[(&str, Vec<u8>)]) -> BundleSpec {
384    BundleSpec {
385        block_size: 160,
386        entries: entries
387            .iter()
388            .map(|(name, data)| EntrySpec {
389                name: name.as_bytes().to_vec(),
390                data: data.clone(),
391                flags: 4,
392            })
393            .collect(),
394        ..BundleSpec::default()
395    }
396}
397
398/// Raw bytes for a `.resS` entry: `n` bytes counting from `seed`.
399#[must_use]
400pub fn res_bytes(n: usize, seed: u8) -> Vec<u8> {
401    (0..n)
402        .map(|i| seed.wrapping_add(u8::try_from(i % 256).unwrap_or(0)))
403        .collect()
404}