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_Nameandm_Ptr0,m_Ptr1, … (PPtr<Object>), as class 1; - a streamed texture (
Obj::streamed):m_Nameandm_StreamData(offset,size,path), as class 28; - an AssetBundle (
Obj::asset_bundle):m_Name,m_PreloadTable,m_Containerand, 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’sEnvironment::load_dependency). - FindAsk
- One
find_file(name, is_dependency)call. - Find
Scene - A scene and the
find_filecalls made on it, in order, once its files are loaded. - Obj
- One object.
- Race
Scene - A scene whose container preload walk races a load another thread makes:
otheris loaded at one point of the walk, each in turn (tools/fixtures/env.pyrecords 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;otherregisters 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 withoutm_MainAsset(UnknownObject), and one withoutm_Container(the file fails).- bad_cab
- A bundle of a good CAB, its
.resSand a CAB that fails to parse: the load fails,filesstays 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_FileID1): 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.mdsection 19.2), so neither file’s object does. - cross_
bundle_ pointer - Two bundles: an object in the first points (
m_FileID1) at an object in the second’s CAB; the first also holds a.resSthe object reads. - dependency_
reads - Reads from inside dependencies:
d.bundleholdsCAB-D, its.resSand its siblingCAB-DE;n.bundleholds the same shape inside the nested bundleINNER(CAB-N,CAB-N.resS,CAB-NE);e.bundleholdsCAB-EandCAB-E.resS; all three are loaded as dependencies.CAB-D’s andCAB-N’s pointers name a sibling,CAB-E(another dependency, found byfind_file’s registry lookup) and, fromCAB-D,CAB-R(only the resolver has it, lower-cased asfind_fileasks); their textures read their own.resS,CAB-E.resSand, fromCAB-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.pyrecords with those loads made as UnityPy’sload_file(..., is_dependency=True). - deref_
rules - One bundle whose first CAB holds a pointer for every dereference rule:
null, a missing path id,
m_FileIDpast 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 byfind_fileunder a key with a directory. - deref_
sibling_ nested - A pointer to
INNER, a nested bundle beside the asking CAB, then one toCAB-Iinside it: the first matches the sibling (a bundle, which holds no objects), the second isfind_file’s, which findsCAB-I(an eager load registered it). UnderLoadMode::Lazythe first dereference names the nested bundle, which registers its entries as agetof its name does, so the second findsCAB-Itoo (plan 3.13 (b)). - fallback_
file_ pointer - A resource read’s fallback loads, through the resolver, a file whose
object points (
m_FileID1) at a CAB of the loaded bundle. UnityPy’sload_fileparses 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 aSerializedFileat top level. The resolver (UnityPy’senv.path): a bundle of a CAB and its.resS, aSerializedFile, a raw file, a second bundle and a WebFile of one CAB.find_fileis asked for each loaded kind by its CAB name (the registry), for each resolver file by its name (UnityPy’spath/namestep), for a CAB a resolver load registered, for a resolver file again (now in the registry), for a name nothing answers (the walk’sFileNotFoundError), for the second bundle withis_dependency=False, and last for the WebFile, which P1 refuses (plan section 1). - find_
file_ listing - What a
find_fileload 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 aSerializedFileand a raw file.find_fileis asked for the first bundle as a dependency (UnityPy’s default, a dereference’s), then withis_dependency=Falsefor the second bundle, theSerializedFileand the raw file, then for theSerializedFileagain, now the registry’s. UnityPy lists each load inenv.files, and the objects and container rows of those loaded withis_dependency=Falseinenv.objectsandenv.container, whichEnvOptions::batch()leaves out (PARITY.mdsection 19.3). - find_
scenes - Every
find_filescene, by name: whattools/fixtures/env.pyrecords. - 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_testsmakes in every order, each load’s number its index:x,y,X,x,yandx, the last as a dependency. Each file is aSerializedFileholding 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 lastxis a dependency’s, whichobjectsskips. Not a scene ofsuper::scenes:tools/fixtures/env_race.pyrecords UnityPy’senv.filesafter 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) andq(object 30,assets/b.prefab). A plain scene (super::scenes): the core’s unit testenv::race_testsloads them on two threads, the first stopped between its registration and itsfilesentry while the second loads whole, under these names and both underx, against UnityPy’s two orders of each (tools/fixtures/env_race.py; review round 16:filestook the order the threads listed in, the registry the loads’ order), and three loads,punderxandyand thenqunderx, 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_FileID1, externalarchive:/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_filefindscab-b); without B it isDerefError::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.bundleandb.bundleeach hold a plainSerializedFilenamedn;c.bundleholdse0, then a nested bundle namednofCAB-Z, whose container rowassets/z.prefabreaches its object 7 through the preload table. Loaded in this order, an eager load registersCAB-Zatc.bundle’s load, and the container gives object 7 the row’s path. The core’s unit testenv::race_testsloadsc.bundleon a thread stopped after its first key whileb.bundleloads and a container pass runs (tools/fixtures/env_race.pyrecords UnityPy’s run of that order):c.bundle’snthen ranks between the key’s position and its value, so its registration changes no key, and underLoadMode::Lazyit lists its dropped slot, whose reach registersCAB-Z(review round 16: that listing started no container index generation, so no pass walkedCAB-Z’s table and object 7 had no path).- nested_
dropped_ evicted f.bundleholdsCAB-F; the dependencya.bundleholds the nested bundleINNERofCAB-D, whose rowassets/d.prefabhas a preload span reachingCAB-F’s object 1; the dependencyb.bundleholdsCAB-B; andp.bundleholds a raw entryINNER, which dropsa.bundle’s. An eager load registeredCAB-Data.bundle’s load, so the container pass walks its table andCAB-F’s object 1 gets the pathassets/d.prefab. UnderLoadMode::Lazy, with options that evicta.bundlewhenb.bundleloads, the droppedINNERis 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::Lazyeach 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_evictedwithoutp.bundle: the dependencya.bundle’sINNERstays the key’s value. An eager load registeredCAB-Data.bundle’s load, so the container pass walks its table andCAB-F’s object 1 gets the pathassets/d.prefab. UnderLoadMode::Lazy, with options that evicta.bundlewhenb.bundleloads, the container pass reachesINNERthrough its own slot, openinga.bundleagain; 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.bundleholds the nested bundleINNERof three raw entries, whichp.bundle’s raw entryINNERdrops: an eager load registered the three at the first load. UnderLoadMode::Lazythe 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’so.bundle, loaded a second time from the same bytes aso2.bundle(a replay hands two files of equal bytes one allocation, as a caller that loads one input twice does): an eager load registersCAB-Iand its.resSat each load, so the read from either load’s texture finds the.resS. UnderLoadMode::Lazythe reload’s slot forINNERstands in for the first load’s, and a reader inside the first load’sINNERreaches it through the reload’s handle (review round 5: it reached nothing, and the read missed every candidate).- nested_
reloaded_ spans o.bundleholds the nested bundleINNERofCAB-I, whose rowassets/i.prefabhas a preload span reaching object 2 ofCAB-Z, and thenCAB-Z, whose own row’s span reaches its object 2 too; it is loaded a second time from the same bytes aso2.bundle. An eager load registersCAB-IbeforeCAB-Zat each load, so the container listsCAB-I’s row first and its walk givesCAB-Z’s object 2 the pathassets/i.prefab. UnderLoadMode::Lazythe reload’s slot forINNERstands in for the first load’s, and its entries take the first load’s positions (review round 6: they took the reload’s, afterCAB-Z, so the container listedCAB-Z’s row first and its walk gave object 2 the pathassets/z.prefab).- nested_
reloaded_ spans_ raced nested_reloaded_spanswithCAB-ObeforeINNERandCAB-JbeforeCAB-Iinside it, so a test can stop the first load after its first key, before it registersINNER, and stop a reach of the reload’sINNERbetween two of its keys. An eager load gives the container and the paths ofnested_reloaded_spans. UnderLoadMode::Lazy, when the first load registers itsINNERwhile the reload’s slot is being reached, a container pass that runs once both loads have returned must walkCAB-IbeforeCAB-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 walkedCAB-Zfirst and gave its object 2 the pathassets/z.prefabfor good).- nested_
replaced_ unread o.bundleholds the nested bundleINNERofCAB-I(with a container row), thenp.bundleholds aSerializedFilenamedINNER: the second load’sINNERis the key’s value. An eager load registeredCAB-Iat the first load, so it is a key and its row is listed. UnderLoadMode::Lazythe second registration drops the first’s unread slot, so it reaches it first (review round 4:CAB-Iwas 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_fileregisters it, and UnityPy’s loop overenv.cabsraisesRuntimeError(the dict changed size); the next pass ends. - preload_
nested_ external - A preload whose first and third elements name
CAB-Iin the nested bundleINNERof another bundle, and whose second namesINNERitself. An eager load registeredCAB-Iat load, so the first element finds it andCAB-I’s object 5 gets the row’s path. UnderLoadMode::Lazythe container pass reachesINNERbefore it walks (plan 3.13 (b)), so the first element findsCAB-Itoo (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 isCAB-Q’s 6, thenq’s 5; rowaspans both, rowbthe first alone. At rowa’s first indexcab-qis the caller’s copy, which has no object 6 (KeyError, skipped); its second,q, is matched by suffix inenv.path(environment.py:345-354), whosecab-qreplaces the caller’s under that key and gets rowa’s path for its 5. UnityPy’s rowbdereferences the first index again and finds the new copy, whose 6 gets rowb’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 isCAB-Q’s 6,q’s 5 andCAB-Q’s 7; rowaspans the last alone, rowball three, rowcthe first alone. Rowafinds 7 in the caller’sCAB-Q; rowbmisses 6 there, thenqloadsenv.path’scab-qby suffix (environment.py:345-354), which takes the key, so rowb’s third index finds the new copy’s 7, and rowc’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.pyrecords. - res_
bytes - Raw bytes for a
.resSentry:nbytes counting fromseed. - resolver_
loads - A loaded bundle whose CAB points at, and reads a resource from, files
only the resolver has:
find_fileloadscab-dep’s bundle as a dependency (a container, so the pointer has no target), whose own copy ofCAB-Hthen replaces the loaded one’s key, andcab-loose, aSerializedFileit resolves into; the resource fallback loadsCAB-H2.resSunder 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 bundleINNER, whose stream namesCAB-I.resS,INNER’s other entry: an eager load registered both at load, so the read finds the.resSby name. UnderLoadMode::Lazya reader reached throughenv.objects()(or a batch job’s own handle) reaches its own container before the lookup (review round 4: the read missed every candidate and raisedFileNotFoundError). - resource_
in_ own_ nested - A texture whose stream names
inner, a nested bundle of its own bundle that holdsinner.resS: UnityPy’s candidates missinner(an eager load gives a nested bundle no key) and readinner.resS. UnderLoadMode::Lazyinneris a key, and asking for it as the first candidate registersinner.resSfor 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.pyrecords. - serialized
- A
SerializedFile(format 22, little-endian, type trees on) holdingobjects, each with its own type record, and the given external paths. - web_
file - A plain WebFile (
UnityWebData1.0, no compression) ofentries, asfiles/WebFile.py:40-56reads one: the signature to its NUL, the header length, an(offset, size, name length, name)row per entry, the data.