Skip to main content

Module pptr

Module pptr 

Source
Expand description

PPtr and its dereference (classes/PPtr.py:15-107).

The rules, in UnityPy’s order:

  1. m_PathID == 0 raises ValueError.
  2. m_FileID == 0 is the pointer’s own file.
  3. Else externals[m_FileID - 1] (external_index): computed in i64 so i32::MIN - 1 does not wrap; the guard is only external_id >= len (FileNotFoundError, DerefError::FileIdPastEnd), then Python indexing: a negative m_FileID counts from the end, and one below -len is an IndexError (DerefError::FileIdBelowStart). The two are different exceptions. The container preload (helpers/ContainerHelper.py:43-46, except (FileNotFoundError, KeyError): continue) swallows DerefError::FileIdPastEnd, DerefError::NotFound and DerefError::MissingObject, and propagates DerefError::FileIdBelowStart, DerefError::RawTarget (an AttributeError), DerefError::Null (never reached: the preload skips null pointers first), DerefError::ContainerDropped and DerefError::Load.
  4. The file’s container (assetsfile.parent, PPtr.py:62-66): a bundle entry’s is its bundle; a file loaded at top level has the Environment that 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 a SerializedFile built outside any Environment, which super::Environment::deref never sees: the core has no such refusal. (Probe: two loose files a/CAB-A and b/CAB-B, A’s external archive:/CAB-B/CAB-B, resolve to B’s object in UnityPy 1.25.2.) A bundle entry whose bundle has been dropped (the Parent’s weak handle no longer upgrades) has no container to scan: UnityPy cannot reach that state (an object keeps assets_file.parent alive), so the core does not guess between “no sibling” and find_file, and fails with DerefError::ContainerDropped.
  5. The external path is cleaned (crate::pystr::clean_external_path) and compared with each key of the container’s files dict lower-cased with str.lower (no basename): a bundle’s directory paths, or the Environment’s files keys, the names given to load, dependencies included. The first equal key wins, even when its ZIP value is None: that raises FileNotFoundError without trying the CAB registry (classes/PPtr.py:75-88). Else find_file (the CAB registry, then the resolver), whose miss is FileNotFoundError: its None, and the walk’s own FileNotFoundError (a resolver’s super::CabResolver::find_file error naming crate::error::NotFound::Cab), are DerefError::NotFound.
  6. The target’s objects[m_PathID]: a missing id is a KeyError; a raw target or a container (a bundle under an Environment files key) has no objects (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_FileID and m_PathID.

Enums§

DerefError
Why a dereference failed, with the exception UnityPy raises.
ExternalIndexError
Why externals[m_FileID - 1] fails (rule 3).

Functions§

external_index
Rule 3: the index into externals that m_FileID names, as UnityPy computes it (PPtr.py:56-60): external_id = m_FileID - 1 in a wide integer, refused when >= len, then indexed as a Python list (a negative id counts from the end). Callers handle m_FileID == 0 (rule 2) first. Implemented by the scaffold.