Skip to main content

Module env

Module env 

Source
Expand description

Multi-file scenes for the Environment tests: bundles whose objects point into each other, resources in sibling entries and in other bundles.

A scene is the files a caller loads, in order, and the files a resolver can return (UnityPy’s env.path). Every object is one of three shapes, each with its own type record so a file may mix them freely:

  • a named object (Obj::named): m_Name and m_Ptr0, m_Ptr1, … (PPtr<Object>), as class 1;
  • a streamed texture (Obj::streamed): m_Name and m_StreamData (offset, size, path), as class 28;
  • an AssetBundle (Obj::asset_bundle): m_Name, m_PreloadTable, m_Container and, unless left out, m_MainAsset, as class 142.

tools/fixtures/env.py asks cargo for scenes and records what UnityPy 1.25.2 does with each (crates/unityrs-core/tests/fixtures/d/).

Owner: package D.

Structs§

Bundle
The AssetBundle’s fields.
DepScene
A scene some of whose loads are dependencies (UnityPy’s load_file(..., is_dependency=True), the core’s Environment::load_dependency).
FindAsk
One find_file(name, is_dependency) call.
FindScene
A scene and the find_file calls made on it, in order, once its files are loaded.
Obj
One object.
RaceScene
A scene whose container preload walk races a load another thread makes: other is loaded at one point of the walk, each in turn (tools/fixtures/env.py records UnityPy’s walk with the load made at each point and, for a load of more than one key, with only its first key made there). Exactly one file of the scene holds an AssetBundle, so the walk is of one table; other registers only keys a file of the scene registered first, so UnityPy’s pass, which fails when its dict of CABs grows under it, finishes wherever the load is made.
Row
One container row: the path, its preload span and the asset pointer.
Scene
Named files, as a caller would load them.

Enums§

Body
What an object holds.

Functions§

asset_bundle_modes
AssetBundles read in object mode: two fields whose names clean to one key (the last wins), one without m_MainAsset (UnknownObject), and one without m_Container (the file fails).
bad_cab
A bundle of a good CAB, its .resS and a CAB that fails to parse: the load fails, files stays empty, and the first two are registered.
bundle
A UnityFS bundle (LZ4 blocks of 160 bytes) of entries.
container_other_file
A container row whose asset is in another file (m_FileID 1): UnityPy keys its path by path id alone, so the object of that path id in the container’s own file gets it; the core keys only a row whose asset is in the container’s own file (PARITY.md section 19.2), so neither file’s object does.
cross_bundle_pointer
Two bundles: an object in the first points (m_FileID 1) at an object in the second’s CAB; the first also holds a .resS the object reads.
dependency_reads
Reads from inside dependencies: d.bundle holds CAB-D, its .resS and its sibling CAB-DE; n.bundle holds the same shape inside the nested bundle INNER (CAB-N, CAB-N.resS, CAB-NE); e.bundle holds CAB-E and CAB-E.resS; all three are loaded as dependencies. CAB-D’s and CAB-N’s pointers name a sibling, CAB-E (another dependency, found by find_file’s registry lookup) and, from CAB-D, CAB-R (only the resolver has it, lower-cased as find_file asks); their textures read their own .resS, CAB-E.resS and, from CAB-D, CAB-X.resS, which a resource fallback loads (a bundle of that name whose one entry is the .resS). Every dereference and resource read starts from a dependency’s file, so each charges the dependency pool (review round 8: a pool refusal there failed the call, with no eviction and no retry).
dependency_scenes
Every scene some of whose loads are dependencies, by name: what tools/fixtures/env.py records with those loads made as UnityPy’s load_file(..., is_dependency=True).
deref_rules
One bundle whose first CAB holds a pointer for every dereference rule: null, a missing path id, m_FileID past the end, a negative id in range and one below it, i32::MIN, an external nobody has, a raw sibling, a sibling matched by its lower-cased name, and one found by find_file under a key with a directory.
deref_sibling_nested
A pointer to INNER, a nested bundle beside the asking CAB, then one to CAB-I inside it: the first matches the sibling (a bundle, which holds no objects), the second is find_file’s, which finds CAB-I (an eager load registered it). Under LoadMode::Lazy the first dereference names the nested bundle, which registers its entries as a get of its name does, so the second finds CAB-I too (plan 3.13 (b)).
fallback_file_pointer
A resource read’s fallback loads, through the resolver, a file whose object points (m_FileID 1) at a CAB of the loaded bundle. UnityPy’s load_file parses the fallback’s file with the Environment as its container (environment.py:107-108, :154), so the pointer resolves as a top-level file’s does.
find_file_kinds
Loaded: a bundle of a CAB and its .resS, a raw file and a SerializedFile at top level. The resolver (UnityPy’s env.path): a bundle of a CAB and its .resS, a SerializedFile, a raw file, a second bundle and a WebFile of one CAB. find_file is asked for each loaded kind by its CAB name (the registry), for each resolver file by its name (UnityPy’s path/name step), for a CAB a resolver load registered, for a resolver file again (now in the registry), for a name nothing answers (the walk’s FileNotFoundError), for the second bundle with is_dependency=False, and last for the WebFile, which P1 refuses (plan section 1).
find_file_listing
What a find_file load lists, under each flag. Loaded: a bundle whose CAB holds a named object and an AssetBundle with one container row. The resolver: two such bundles, such a SerializedFile and a raw file. find_file is asked for the first bundle as a dependency (UnityPy’s default, a dereference’s), then with is_dependency=False for the second bundle, the SerializedFile and the raw file, then for the SerializedFile again, now the registry’s. UnityPy lists each load in env.files, and the objects and container rows of those loaded with is_dependency=False in env.objects and env.container, which EnvOptions::batch() leaves out (PARITY.md section 19.3).
find_scenes
Every find_file scene, by name: what tools/fixtures/env.py records.
last_block_fails
A bundle with a block after its last entry’s bytes that fails to decode (plan 3.13 (c)).
listings
The six listings the core’s unit test env::listing_tests makes in every order, each load’s number its index: x, y, X, x, y and x, the last as a dependency. Each file is a SerializedFile holding one named object whose path id is its load’s number + 1, so a listing’s file and object tell its load. A key is listed again by a later load and by an earlier one, after it moved, two keys lower to one name, and the last x is a dependency’s, which objects skips. Not a scene of super::scenes: tools/fixtures/env_race.py records UnityPy’s env.files after every set of these loads, made in the order of their numbers (review round 16’s follow-up: the test’s expected values were a hand-written model of a Python dict).
listings_raced
Two SerializedFiles, each with one container row naming its own object: p (object 10, assets/a.prefab) and q (object 30, assets/b.prefab). A plain scene (super::scenes): the core’s unit test env::race_tests loads them on two threads, the first stopped between its registration and its files entry while the second loads whole, under these names and both under x, against UnityPy’s two orders of each (tools/fixtures/env_race.py; review round 16: files took the order the threads listed in, the registry the loads’ order), and three loads, p under x and y and then q under x, the first stopped while the other two load whole, against UnityPy’s order of their numbers (a key listed by a later load before the first lists moves to the first’s number).
loose_external_pointer
Two loose SerializedFiles loaded at top level under names with directories (a/CAB-A, b/CAB-B): an object in A points (m_FileID 1, external archive:/CAB-B/CAB-B) at an object in B. The pointer resolves, as in UnityPy, whose Environment is a top-level file’s container (find_file finds cab-b); without B it is DerefError::NotFound.
nested_after_cab
A bundle whose second entry is a bundle under the path of the first, a CAB (plan 3.13 (b)).
nested_between_loads
a.bundle and b.bundle each hold a plain SerializedFile named n; c.bundle holds e0, then a nested bundle named n of CAB-Z, whose container row assets/z.prefab reaches its object 7 through the preload table. Loaded in this order, an eager load registers CAB-Z at c.bundle’s load, and the container gives object 7 the row’s path. The core’s unit test env::race_tests loads c.bundle on a thread stopped after its first key while b.bundle loads and a container pass runs (tools/fixtures/env_race.py records UnityPy’s run of that order): c.bundle’s n then ranks between the key’s position and its value, so its registration changes no key, and under LoadMode::Lazy it lists its dropped slot, whose reach registers CAB-Z (review round 16: that listing started no container index generation, so no pass walked CAB-Z’s table and object 7 had no path).
nested_dropped_evicted
f.bundle holds CAB-F; the dependency a.bundle holds the nested bundle INNER of CAB-D, whose row assets/d.prefab has a preload span reaching CAB-F’s object 1; the dependency b.bundle holds CAB-B; and p.bundle holds a raw entry INNER, which drops a.bundle’s. An eager load registered CAB-D at a.bundle’s load, so the container pass walks its table and CAB-F’s object 1 gets the path assets/d.prefab. Under LoadMode::Lazy, with options that evict a.bundle when b.bundle loads, the dropped INNER is an evicted dependency’s, which the container pass opens again to reach (plan section 9, Q13, revised after review round 6: nothing reached it, and the path was missing).
nested_duplicates
A bundle of two nested bundles that each hold a CAB of one name, with a container row whose preload span reaches object 3: an eager load registers both in directory order, so the second’s is the key’s value, the container lists its row alone and the preload walks its table alone. Under LoadMode::Lazy each is registered when its nested bundle is reached, in either order with the same result, and the container pass reaches both before it walks (review round 4: the pass walked the first one’s table, at a key the second’s replaced after the walk had passed it, and never the second’s).
nested_evicted
nested_dropped_evicted without p.bundle: the dependency a.bundle’s INNER stays the key’s value. An eager load registered CAB-D at a.bundle’s load, so the container pass walks its table and CAB-F’s object 1 gets the path assets/d.prefab. Under LoadMode::Lazy, with options that evict a.bundle when b.bundle loads, the container pass reaches INNER through its own slot, opening a.bundle again; a pool that refuses that open, or any later read or registration of the reach, makes room by evicting the other dependencies and tries once more, as every other dependency read does (plan section 3.13; review round 7: the reach’s open failed every pass).
nested_raw_replaced
o.bundle holds the nested bundle INNER of three raw entries, which p.bundle’s raw entry INNER drops: an eager load registered the three at the first load. Under LoadMode::Lazy the second registration drops the first’s unread slot, so it reaches it first (review round 5: a reach of this shape that the input’s meter refused was redone by every lookup by name, uncounted).
nested_reloaded
resource_in_nested_cab’s o.bundle, loaded a second time from the same bytes as o2.bundle (a replay hands two files of equal bytes one allocation, as a caller that loads one input twice does): an eager load registers CAB-I and its .resS at each load, so the read from either load’s texture finds the .resS. Under LoadMode::Lazy the reload’s slot for INNER stands in for the first load’s, and a reader inside the first load’s INNER reaches it through the reload’s handle (review round 5: it reached nothing, and the read missed every candidate).
nested_reloaded_spans
o.bundle holds the nested bundle INNER of CAB-I, whose row assets/i.prefab has a preload span reaching object 2 of CAB-Z, and then CAB-Z, whose own row’s span reaches its object 2 too; it is loaded a second time from the same bytes as o2.bundle. An eager load registers CAB-I before CAB-Z at each load, so the container lists CAB-I’s row first and its walk gives CAB-Z’s object 2 the path assets/i.prefab. Under LoadMode::Lazy the reload’s slot for INNER stands in for the first load’s, and its entries take the first load’s positions (review round 6: they took the reload’s, after CAB-Z, so the container listed CAB-Z’s row first and its walk gave object 2 the path assets/z.prefab).
nested_reloaded_spans_raced
nested_reloaded_spans with CAB-O before INNER and CAB-J before CAB-I inside it, so a test can stop the first load after its first key, before it registers INNER, and stop a reach of the reload’s INNER between two of its keys. An eager load gives the container and the paths of nested_reloaded_spans. Under LoadMode::Lazy, when the first load registers its INNER while the reload’s slot is being reached, a container pass that runs once both loads have returned must walk CAB-I before CAB-Z (review round 7: the reach marked the slot reached and only then moved its entries to the first load’s positions, so a pass in between walked CAB-Z first and gave its object 2 the path assets/z.prefab for good).
nested_replaced_unread
o.bundle holds the nested bundle INNER of CAB-I (with a container row), then p.bundle holds a SerializedFile named INNER: the second load’s INNER is the key’s value. An eager load registered CAB-I at the first load, so it is a key and its row is listed. Under LoadMode::Lazy the second registration drops the first’s unread slot, so it reaches it first (review round 4: CAB-I was never registered).
preload_below_start
A preload pointer below the externals: IndexError, raised.
preload_loads_new_cab
A loose file whose preload pointer names a CAB only the resolver has: the container pass’s find_file registers it, and UnityPy’s loop over env.cabs raises RuntimeError (the dict changed size); the next pass ends.
preload_nested_external
A preload whose first and third elements name CAB-I in the nested bundle INNER of another bundle, and whose second names INNER itself. An eager load registered CAB-I at load, so the first element finds it and CAB-I’s object 5 gets the row’s path. Under LoadMode::Lazy the container pass reaches INNER before it walks (plan 3.13 (b)), so the first element finds CAB-I too (review round 3: the walk kept the first element’s miss).
preload_paths
Container paths (obj.container): rows whose spans overlap (the first row to reach an object gives its path), a row’s own asset (which beats any span), two rows of one asset (the last wins), and a span reaching an object in a sibling CAB.
preload_raw_target
A preload pointer at a raw sibling: AttributeError, raised.
preload_revisits_after_load
The review’s case. CAB-B’s table is CAB-Q’s 6, then q’s 5; row a spans both, row b the first alone. At row a’s first index cab-q is the caller’s copy, which has no object 6 (KeyError, skipped); its second, q, is matched by suffix in env.path (environment.py:345-354), whose cab-q replaces the caller’s under that key and gets row a’s path for its 5. UnityPy’s row b dereferences the first index again and finds the new copy, whose 6 gets row b’s path.
preload_revisits_ahead
A load in a row puts back an index of the same row that an earlier row dereferenced, ahead of the load, and one behind it. CAB-B’s table is CAB-Q’s 6, q’s 5 and CAB-Q’s 7; row a spans the last alone, row b all three, row c the first alone. Row a finds 7 in the caller’s CAB-Q; row b misses 6 there, then q loads env.path’s cab-q by suffix (environment.py:345-354), which takes the key, so row b’s third index finds the new copy’s 7, and row c’s first its 6.
preload_skips
A container whose preload table points every way the preload skips: past the externals, at a file nobody has, at a missing object, null, and rows whose spans fall outside the table.
race_scenes
Every race scene, by name: what tools/fixtures/env.py records.
res_bytes
Raw bytes for a .resS entry: n bytes counting from seed.
resolver_loads
A loaded bundle whose CAB points at, and reads a resource from, files only the resolver has: find_file loads cab-dep’s bundle as a dependency (a container, so the pointer has no target), whose own copy of CAB-H then replaces the loaded one’s key, and cab-loose, a SerializedFile it resolves into; the resource fallback loads CAB-H2.resS under the name it asked for, twice (the first and last candidates are one name).
resource_in_nested_cab
A texture in CAB-I, inside the nested bundle INNER, whose stream names CAB-I.resS, INNER’s other entry: an eager load registered both at load, so the read finds the .resS by name. Under LoadMode::Lazy a reader reached through env.objects() (or a batch job’s own handle) reaches its own container before the lookup (review round 4: the read missed every candidate and raised FileNotFoundError).
resource_in_own_nested
A texture whose stream names inner, a nested bundle of its own bundle that holds inner.resS: UnityPy’s candidates miss inner (an eager load gives a nested bundle no key) and read inner.resS. Under LoadMode::Lazy inner is a key, and asking for it as the first candidate registers inner.resS for the last (review round 3: the read through the texture’s own bundle skipped that registration and failed).
row
A row pointing at asset, with its preload span.
scenes
Every scene, by name: what tools/fixtures/env.py records.
serialized
A SerializedFile (format 22, little-endian, type trees on) holding objects, each with its own type record, and the given external paths.
web_file
A plain WebFile (UnityWebData1.0, no compression) of entries, as files/WebFile.py:40-56 reads one: the signature to its NUL, the header length, an (offset, size, name length, name) row per entry, the data.