Skip to main content

unityrs_testkit/env/catalog/
nested.rs

1//! The scenes of nested containers (plan 3.13, difference (b)).
2
3use super::{Bundle, DepScene, Obj, Scene, bundle, named, res_bytes, row, serialized};
4
5/// A bundle of two nested bundles that each hold a CAB of one name, with a
6/// container row whose preload span reaches object 3: an eager load
7/// registers both in directory order, so the second's is the key's value,
8/// the container lists its row alone and the preload walks its table alone.
9/// Under `LoadMode::Lazy` each is registered when its nested bundle is
10/// reached, in either order with the same result, and the container pass
11/// reaches both before it walks (review round 4: the pass walked the first
12/// one's table, at a key the second's replaced after the walk had passed
13/// it, and never the second's).
14#[must_use]
15pub fn nested_duplicates() -> Scene {
16    let inner = |name: &str| {
17        let cab = serialized(
18            &[],
19            &[
20                Obj::named(1, name, &[]),
21                Obj::named(3, "x3", &[]),
22                Obj::asset_bundle(
23                    2,
24                    Bundle {
25                        preload: vec![(0, 3)],
26                        rows: vec![row(&format!("assets/{name}.prefab"), (0, 1), (0, 1))],
27                        ..Bundle::default()
28                    },
29                ),
30            ],
31        );
32        bundle(&[("CAB-DUP", cab)])
33    };
34    Scene {
35        files: vec![named(
36            "dup.bundle",
37            bundle(&[("N1", inner("from-n1")), ("N2", inner("from-n2"))]),
38        )],
39        resolver: Vec::new(),
40    }
41}
42
43/// `o.bundle`: `CAB-O` and a nested bundle `INNER` of `inner`'s entries.
44fn outer_with_inner(cab_o: Vec<u8>, inner: &[(&str, Vec<u8>)]) -> (Vec<u8>, Vec<u8>) {
45    named(
46        "o.bundle",
47        bundle(&[("CAB-O", cab_o), ("INNER", bundle(inner))]),
48    )
49}
50
51/// A preload whose first and third elements name `CAB-I` in the nested
52/// bundle `INNER` of another bundle, and whose second names `INNER` itself.
53/// An eager load registered `CAB-I` at load, so the first element finds it
54/// and `CAB-I`'s object 5 gets the row's path. Under `LoadMode::Lazy` the
55/// container pass reaches `INNER` before it walks (plan 3.13 (b)), so the
56/// first element finds `CAB-I` too (review round 3: the walk kept the first
57/// element's miss).
58#[must_use]
59pub fn preload_nested_external() -> Scene {
60    let f = serialized(
61        &["archive:/CAB-I/CAB-I", "archive:/O/INNER"],
62        &[
63            Obj::named(1, "f1", &[]),
64            Obj::asset_bundle(
65                2,
66                Bundle {
67                    preload: vec![(1, 5), (2, 9), (1, 5)],
68                    rows: vec![row("assets/x.prefab", (0, 3), (0, 1))],
69                    ..Bundle::default()
70                },
71            ),
72        ],
73    );
74    let o = serialized(&[], &[Obj::named(7, "o7", &[])]);
75    let i = serialized(&[], &[Obj::named(5, "i5", &[])]);
76    Scene {
77        files: vec![
78            named("f.bundle", bundle(&[("CAB-F", f)])),
79            outer_with_inner(o, &[("CAB-I", i)]),
80        ],
81        resolver: Vec::new(),
82    }
83}
84
85/// A texture whose stream names `inner`, a nested bundle of its own bundle
86/// that holds `inner.resS`: UnityPy's candidates miss `inner` (an eager load
87/// gives a nested bundle no key) and read `inner.resS`. Under
88/// `LoadMode::Lazy` `inner` is a key, and asking for it as the first
89/// candidate registers `inner.resS` for the last (review round 3: the read
90/// through the texture's own bundle skipped that registration and failed).
91#[must_use]
92pub fn resource_in_own_nested() -> Scene {
93    let o = serialized(&[], &[Obj::streamed(1, "tex", "archive:/O/inner", 0, 4)]);
94    Scene {
95        files: vec![named(
96            "o.bundle",
97            bundle(&[
98                ("CAB-O", o),
99                ("inner", bundle(&[("inner.resS", res_bytes(8, 40))])),
100            ]),
101        )],
102        resolver: Vec::new(),
103    }
104}
105
106/// A pointer to `INNER`, a nested bundle beside the asking CAB, then one to
107/// `CAB-I` inside it: the first matches the sibling (a bundle, which holds
108/// no objects), the second is `find_file`'s, which finds `CAB-I` (an eager
109/// load registered it). Under `LoadMode::Lazy` the first dereference names
110/// the nested bundle, which registers its entries as a `get` of its name
111/// does, so the second finds `CAB-I` too (plan 3.13 (b)).
112#[must_use]
113pub fn deref_sibling_nested() -> Scene {
114    let o = serialized(
115        &["archive:/O/INNER", "archive:/CAB-I/CAB-I"],
116        &[Obj::named(7, "o7", &[(1, 5), (2, 5)])],
117    );
118    let i = serialized(&[], &[Obj::named(5, "i5", &[])]);
119    Scene {
120        files: vec![outer_with_inner(o, &[("CAB-I", i)])],
121        resolver: Vec::new(),
122    }
123}
124
125/// A texture in `CAB-I`, inside the nested bundle `INNER`, whose stream
126/// names `CAB-I.resS`, `INNER`'s other entry: an eager load registered both
127/// at load, so the read finds the `.resS` by name. Under `LoadMode::Lazy` a
128/// reader reached through `env.objects()` (or a batch job's own handle)
129/// reaches its own container before the lookup (review round 4: the read
130/// missed every candidate and raised `FileNotFoundError`).
131#[must_use]
132pub fn resource_in_nested_cab() -> Scene {
133    let i = serialized(
134        &[],
135        &[Obj::streamed(1, "tex", "archive:/CAB-I/CAB-I.resS", 0, 4)],
136    );
137    Scene {
138        files: vec![named(
139            "o.bundle",
140            bundle(&[(
141                "INNER",
142                bundle(&[("CAB-I", i), ("CAB-I.resS", res_bytes(8, 40))]),
143            )]),
144        )],
145        resolver: Vec::new(),
146    }
147}
148
149/// `o.bundle` holds the nested bundle `INNER` of `CAB-I` (with a container
150/// row), then `p.bundle` holds a `SerializedFile` named `INNER`: the second
151/// load's `INNER` is the key's value. An eager load registered `CAB-I` at
152/// the first load, so it is a key and its row is listed. Under
153/// `LoadMode::Lazy` the second registration drops the first's unread slot,
154/// so it reaches it first (review round 4: `CAB-I` was never registered).
155#[must_use]
156pub fn nested_replaced_unread() -> Scene {
157    let i = serialized(
158        &[],
159        &[
160            Obj::named(5, "i5", &[]),
161            Obj::asset_bundle(
162                2,
163                Bundle {
164                    rows: vec![row("assets/i.prefab", (0, 0), (0, 5))],
165                    ..Bundle::default()
166                },
167            ),
168        ],
169    );
170    let p = serialized(&[], &[Obj::named(1, "p1", &[])]);
171    Scene {
172        files: vec![
173            named("o.bundle", bundle(&[("INNER", bundle(&[("CAB-I", i)]))])),
174            named("p.bundle", bundle(&[("INNER", p)])),
175        ],
176        resolver: Vec::new(),
177    }
178}
179
180/// `resource_in_nested_cab`'s `o.bundle`, loaded a second time from the same
181/// bytes as `o2.bundle` (a replay hands two files of equal bytes one
182/// allocation, as a caller that loads one input twice does): an eager load
183/// registers `CAB-I` and its `.resS` at each load, so the read from either
184/// load's texture finds the `.resS`. Under `LoadMode::Lazy` the reload's slot
185/// for `INNER` stands in for the first load's, and a reader inside the first
186/// load's `INNER` reaches it through the reload's handle (review round 5: it
187/// reached nothing, and the read missed every candidate).
188#[must_use]
189pub fn nested_reloaded() -> Scene {
190    let mut scene = resource_in_nested_cab();
191    let (_, data) = scene.files[0].clone();
192    scene.files.push(named("o2.bundle", data));
193    scene
194}
195
196/// `o.bundle` holds the nested bundle `INNER` of three raw entries, which
197/// `p.bundle`'s raw entry `INNER` drops: an eager load registered the three
198/// at the first load. Under `LoadMode::Lazy` the second registration drops
199/// the first's unread slot, so it reaches it first (review round 5: a reach
200/// of this shape that the input's meter refused was redone by every lookup
201/// by name, uncounted).
202#[must_use]
203pub fn nested_raw_replaced() -> Scene {
204    let inner = bundle(&[
205        ("R0.resS", res_bytes(4, 10)),
206        ("R1.resS", res_bytes(4, 20)),
207        ("R2.resS", res_bytes(4, 30)),
208    ]);
209    Scene {
210        files: vec![
211            named("o.bundle", bundle(&[("INNER", inner)])),
212            named("p.bundle", bundle(&[("INNER", res_bytes(4, 50))])),
213        ],
214        resolver: Vec::new(),
215    }
216}
217
218/// `o.bundle` holds the nested bundle `INNER` of `CAB-I`, whose row
219/// `assets/i.prefab` has a preload span reaching object 2 of `CAB-Z`, and
220/// then `CAB-Z`, whose own row's span reaches its object 2 too; it is
221/// loaded a second time from the same bytes as `o2.bundle`. An eager load
222/// registers `CAB-I` before `CAB-Z` at each load, so the container lists
223/// `CAB-I`'s row first and its walk gives `CAB-Z`'s object 2 the path
224/// `assets/i.prefab`. Under `LoadMode::Lazy` the reload's slot for `INNER`
225/// stands in for the first load's, and its entries take the first load's
226/// positions (review round 6: they took the reload's, after `CAB-Z`, so the
227/// container listed `CAB-Z`'s row first and its walk gave object 2 the path
228/// `assets/z.prefab`).
229#[must_use]
230pub fn nested_reloaded_spans() -> Scene {
231    let i = serialized(
232        &["archive:/CAB-Z/CAB-Z"],
233        &[
234            Obj::named(1, "i1", &[]),
235            Obj::asset_bundle(
236                3,
237                Bundle {
238                    preload: vec![(1, 2)],
239                    rows: vec![row("assets/i.prefab", (0, 1), (0, 1))],
240                    ..Bundle::default()
241                },
242            ),
243        ],
244    );
245    let z = serialized(
246        &[],
247        &[
248            Obj::named(2, "z2", &[]),
249            Obj::named(4, "z4", &[]),
250            Obj::asset_bundle(
251                3,
252                Bundle {
253                    preload: vec![(0, 2)],
254                    rows: vec![row("assets/z.prefab", (0, 1), (0, 4))],
255                    ..Bundle::default()
256                },
257            ),
258        ],
259    );
260    let o = bundle(&[("INNER", bundle(&[("CAB-I", i)])), ("CAB-Z", z)]);
261    Scene {
262        files: vec![named("o.bundle", o.clone()), named("o2.bundle", o)],
263        resolver: Vec::new(),
264    }
265}
266
267/// [`nested_reloaded_spans`] with `CAB-O` before `INNER` and `CAB-J` before
268/// `CAB-I` inside it, so a test can stop the first load after its first
269/// key, before it registers `INNER`, and stop a reach of the reload's
270/// `INNER` between two of its keys. An eager load gives the container and
271/// the paths of [`nested_reloaded_spans`]. Under `LoadMode::Lazy`, when the
272/// first load registers its `INNER` while the reload's slot is being
273/// reached, a container pass that runs once both loads have returned must
274/// walk `CAB-I` before `CAB-Z` (review round 7: the reach marked the slot
275/// reached and only then moved its entries to the first load's positions,
276/// so a pass in between walked `CAB-Z` first and gave its object 2 the path
277/// `assets/z.prefab` for good).
278#[must_use]
279pub fn nested_reloaded_spans_raced() -> Scene {
280    let i = serialized(
281        &["archive:/CAB-Z/CAB-Z"],
282        &[
283            Obj::named(1, "i1", &[]),
284            Obj::asset_bundle(
285                3,
286                Bundle {
287                    preload: vec![(1, 2)],
288                    rows: vec![row("assets/i.prefab", (0, 1), (0, 1))],
289                    ..Bundle::default()
290                },
291            ),
292        ],
293    );
294    let z = serialized(
295        &[],
296        &[
297            Obj::named(2, "z2", &[]),
298            Obj::named(4, "z4", &[]),
299            Obj::asset_bundle(
300                3,
301                Bundle {
302                    preload: vec![(0, 2)],
303                    rows: vec![row("assets/z.prefab", (0, 1), (0, 4))],
304                    ..Bundle::default()
305                },
306            ),
307        ],
308    );
309    let o_cab = serialized(&[], &[Obj::named(1, "o1", &[])]);
310    let j = serialized(&[], &[Obj::named(1, "j1", &[])]);
311    let o = bundle(&[
312        ("CAB-O", o_cab),
313        ("INNER", bundle(&[("CAB-J", j), ("CAB-I", i)])),
314        ("CAB-Z", z),
315    ]);
316    Scene {
317        files: vec![named("o.bundle", o.clone()), named("o2.bundle", o)],
318        resolver: Vec::new(),
319    }
320}
321
322/// `f.bundle` holds `CAB-F`; the dependency `a.bundle` holds the nested
323/// bundle `INNER` of `CAB-D`, whose row `assets/d.prefab` has a preload span
324/// reaching `CAB-F`'s object 1; the dependency `b.bundle` holds `CAB-B`; and
325/// `p.bundle` holds a raw entry `INNER`, which drops `a.bundle`'s. An eager
326/// load registered `CAB-D` at `a.bundle`'s load, so the container pass walks
327/// its table and `CAB-F`'s object 1 gets the path `assets/d.prefab`. Under
328/// `LoadMode::Lazy`, with options that evict `a.bundle` when `b.bundle`
329/// loads, the dropped `INNER` is an evicted dependency's, which the
330/// container pass opens again to reach (plan section 9, Q13, revised after
331/// review round 6: nothing reached it, and the path was missing).
332#[must_use]
333pub fn nested_dropped_evicted() -> DepScene {
334    let f = serialized(&[], &[Obj::named(1, "f1", &[])]);
335    let d = serialized(
336        &["archive:/CAB-F/CAB-F"],
337        &[
338            Obj::named(1, "d1", &[]),
339            Obj::asset_bundle(
340                2,
341                Bundle {
342                    preload: vec![(1, 1)],
343                    rows: vec![row("assets/d.prefab", (0, 1), (0, 1))],
344                    ..Bundle::default()
345                },
346            ),
347        ],
348    );
349    let b = serialized(&[], &[Obj::named(1, "b1", &[])]);
350    DepScene {
351        scene: Scene {
352            files: vec![
353                named("f.bundle", bundle(&[("CAB-F", f)])),
354                named("a.bundle", bundle(&[("INNER", bundle(&[("CAB-D", d)]))])),
355                named("b.bundle", bundle(&[("CAB-B", b)])),
356                named("p.bundle", bundle(&[("INNER", res_bytes(4, 50))])),
357            ],
358            resolver: Vec::new(),
359        },
360        dependencies: vec![1, 2],
361    }
362}
363
364/// [`nested_dropped_evicted`] without `p.bundle`: the dependency
365/// `a.bundle`'s `INNER` stays the key's value. An eager load registered
366/// `CAB-D` at `a.bundle`'s load, so the container pass walks its table and
367/// `CAB-F`'s object 1 gets the path `assets/d.prefab`. Under
368/// `LoadMode::Lazy`, with options that evict `a.bundle` when `b.bundle`
369/// loads, the container pass reaches `INNER` through its own slot, opening
370/// `a.bundle` again; a pool that refuses that open, or any later read or
371/// registration of the reach, makes room by evicting the other
372/// dependencies and tries once more, as every other dependency read does
373/// (plan section 3.13; review round 7: the reach's open failed every pass).
374#[must_use]
375pub fn nested_evicted() -> DepScene {
376    let mut scene = nested_dropped_evicted();
377    scene.scene.files.truncate(3);
378    scene
379}
380
381/// Reads from inside dependencies: `d.bundle` holds `CAB-D`, its `.resS`
382/// and its sibling `CAB-DE`; `n.bundle` holds the same shape inside the
383/// nested bundle `INNER` (`CAB-N`, `CAB-N.resS`, `CAB-NE`); `e.bundle`
384/// holds `CAB-E` and `CAB-E.resS`; all three are loaded as dependencies.
385/// `CAB-D`'s and `CAB-N`'s pointers name a sibling, `CAB-E` (another
386/// dependency, found by `find_file`'s registry lookup) and, from `CAB-D`,
387/// `CAB-R` (only the resolver has it, lower-cased as `find_file` asks); their
388/// textures read their own `.resS`, `CAB-E.resS` and, from `CAB-D`,
389/// `CAB-X.resS`, which a resource fallback loads (a bundle of that name
390/// whose one entry is the `.resS`). Every dereference and resource read
391/// starts from a dependency's file, so each charges the dependency pool
392/// (review round 8: a pool refusal there failed the call, with no eviction
393/// and no retry).
394#[must_use]
395pub fn dependency_reads() -> DepScene {
396    let d = serialized(
397        &[
398            "archive:/CAB-DE/CAB-DE",
399            "archive:/CAB-E/CAB-E",
400            "archive:/CAB-R/CAB-R",
401        ],
402        &[
403            Obj::named(1, "d1", &[(1, 7), (2, 1), (3, 1)]),
404            Obj::streamed(2, "dtex", "archive:/CAB-D/CAB-D.resS", 4, 8),
405            Obj::streamed(3, "etex", "archive:/CAB-E/CAB-E.resS", 2, 4),
406            Obj::streamed(4, "xtex", "archive:/CAB-X/CAB-X.resS", 1, 3),
407        ],
408    );
409    let n = serialized(
410        &["archive:/CAB-NE/CAB-NE", "archive:/CAB-E/CAB-E"],
411        &[
412            Obj::named(1, "n1", &[(1, 3), (2, 1)]),
413            Obj::streamed(2, "ntex", "archive:/CAB-N/CAB-N.resS", 2, 6),
414        ],
415    );
416    DepScene {
417        scene: Scene {
418            files: vec![
419                named(
420                    "d.bundle",
421                    bundle(&[
422                        ("CAB-D", d),
423                        ("CAB-D.resS", res_bytes(64, 7)),
424                        ("CAB-DE", serialized(&[], &[Obj::named(7, "de7", &[])])),
425                    ]),
426                ),
427                named(
428                    "n.bundle",
429                    bundle(&[(
430                        "INNER",
431                        bundle(&[
432                            ("CAB-N", n),
433                            ("CAB-N.resS", res_bytes(32, 40)),
434                            ("CAB-NE", serialized(&[], &[Obj::named(3, "ne3", &[])])),
435                        ]),
436                    )]),
437                ),
438                named(
439                    "e.bundle",
440                    bundle(&[
441                        ("CAB-E", serialized(&[], &[Obj::named(1, "e1", &[])])),
442                        ("CAB-E.resS", res_bytes(16, 90)),
443                    ]),
444                ),
445            ],
446            resolver: vec![
447                named("cab-r", serialized(&[], &[Obj::named(1, "r1", &[])])),
448                named("CAB-X.resS", bundle(&[("CAB-X.resS", res_bytes(8, 120))])),
449            ],
450        },
451        dependencies: vec![0, 1, 2],
452    }
453}
454
455/// `a.bundle` and `b.bundle` each hold a plain `SerializedFile` named `n`;
456/// `c.bundle` holds `e0`, then a nested bundle named `n` of `CAB-Z`, whose
457/// container row `assets/z.prefab` reaches its object 7 through the
458/// preload table. Loaded in this order, an eager load registers `CAB-Z` at
459/// `c.bundle`'s load, and the container gives object 7 the row's path.
460/// The core's unit test `env::race_tests` loads `c.bundle` on a thread
461/// stopped after its first key while `b.bundle` loads and a container pass
462/// runs (`tools/fixtures/env_race.py` records UnityPy's run of that order):
463/// `c.bundle`'s `n` then ranks between the key's position and its value,
464/// so its registration changes no key, and under `LoadMode::Lazy` it
465/// lists its dropped slot, whose reach registers `CAB-Z` (review round 16:
466/// that listing started no container index generation, so no pass walked
467/// `CAB-Z`'s table and object 7 had no path).
468#[must_use]
469pub fn nested_between_loads() -> Scene {
470    let plain = |name: &str| serialized(&[], &[Obj::named(1, name, &[])]);
471    let z = serialized(
472        &[],
473        &[
474            Obj::named(5, "z5", &[]),
475            Obj::named(7, "z7", &[]),
476            Obj::asset_bundle(
477                2,
478                Bundle {
479                    preload: vec![(0, 7)],
480                    rows: vec![row("assets/z.prefab", (0, 1), (0, 5))],
481                    ..Bundle::default()
482                },
483            ),
484        ],
485    );
486    let e0 = serialized(&[], &[Obj::named(3, "e0", &[])]);
487    Scene {
488        files: vec![
489            named("a.bundle", bundle(&[("n", plain("a1"))])),
490            named(
491                "c.bundle",
492                bundle(&[("e0", e0), ("n", bundle(&[("CAB-Z", z)]))]),
493            ),
494            named("b.bundle", bundle(&[("n", plain("b1"))])),
495        ],
496        resolver: Vec::new(),
497    }
498}