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}