1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
// Ported from UnityPy 1.25.2 (MIT): UnityPy/classes/PPtr.py, UnityPy/environment.py, UnityPy/files/File.py, UnityPy/helpers/ContainerHelper.py. See THIRD_PARTY_LICENSES.
//! `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).
use crateError;
use crateCellError;
use crateRawStr;
/// A pointer: `m_FileID` and `m_PathID`.
/// Why `externals[m_FileID - 1]` fails (rule 3).
/// 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.
/// Why a dereference failed, with the exception UnityPy raises.