Expand description
PPtr and its dereference (classes/PPtr.py:15-107).
The rules, in UnityPy’s order:
m_PathID == 0raisesValueError.m_FileID == 0is the pointer’s own file.- Else
externals[m_FileID - 1](external_index): computed ini64soi32::MIN - 1does not wrap; the guard is onlyexternal_id >= len(FileNotFoundError,DerefError::FileIdPastEnd), then Python indexing: a negativem_FileIDcounts from the end, and one below-lenis anIndexError(DerefError::FileIdBelowStart). The two are different exceptions. The container preload (helpers/ContainerHelper.py:43-46,except (FileNotFoundError, KeyError): continue) swallowsDerefError::FileIdPastEnd,DerefError::NotFoundandDerefError::MissingObject, and propagatesDerefError::FileIdBelowStart,DerefError::RawTarget(anAttributeError),DerefError::Null(never reached: the preload skips null pointers first),DerefError::ContainerDroppedandDerefError::Load. - The file’s container (
assetsfile.parent,PPtr.py:62-66): a bundle entry’s is its bundle; a file loaded at top level has theEnvironmentthat loaded it as its parent (environment.py:154,files/File.py:36), so its container is that Environment. UnityPy’s “no container is set” is raised only for aSerializedFilebuilt outside any Environment, whichsuper::Environment::derefnever sees: the core has no such refusal. (Probe: two loose filesa/CAB-Aandb/CAB-B, A’s externalarchive:/CAB-B/CAB-B, resolve to B’s object in UnityPy 1.25.2.) A bundle entry whose bundle has been dropped (theParent’s weak handle no longer upgrades) has no container to scan: UnityPy cannot reach that state (an object keepsassets_file.parentalive), so the core does not guess between “no sibling” andfind_file, and fails withDerefError::ContainerDropped. - The external path is cleaned (
crate::pystr::clean_external_path) and compared with each key of the container’sfilesdict lower-cased withstr.lower(no basename): a bundle’s directory paths, or the Environment’sfileskeys, the names given toload, dependencies included. The first equal key wins, even when its ZIP value is None: that raisesFileNotFoundErrorwithout trying the CAB registry (classes/PPtr.py:75-88). Elsefind_file(the CAB registry, then the resolver), whose miss isFileNotFoundError: itsNone, and the walk’s ownFileNotFoundError(a resolver’ssuper::CabResolver::find_fileerror namingcrate::error::NotFound::Cab), areDerefError::NotFound. - The target’s
objects[m_PathID]: a missing id is aKeyError; a raw target or a container (a bundle under an Environmentfileskey) has noobjects(AttributeError).
Owner: package D. The types and external_index are frozen (the
scaffold implements external_index; tests/fixtures/scaffold/pptr_external.json
pins it).
Structs§
- PPtr
- A pointer:
m_FileIDandm_PathID.
Enums§
- Deref
Error - Why a dereference failed, with the exception UnityPy raises.
- External
Index Error - Why
externals[m_FileID - 1]fails (rule 3).
Functions§
- external_
index - Rule 3: the index into
externalsthatm_FileIDnames, as UnityPy computes it (PPtr.py:56-60):external_id = m_FileID - 1in a wide integer, refused when>= len, then indexed as a Python list (a negative id counts from the end). Callers handlem_FileID == 0(rule 2) first. Implemented by the scaffold.