unityrs_core/object.rs
1// Ported from UnityPy 1.25.2 (MIT): UnityPy/files/ObjectReader.py. See THIRD_PARTY_LICENSES.
2//! `ObjectReader` (`files/ObjectReader.py:44-311`): one object of a
3//! `SerializedFile`, read on demand.
4//!
5//! An [`ObjectRef`] is a cheap handle: an `Arc` on the file and the row's
6//! index in the file's object table, which it reads on demand. It owns no
7//! copy of the row and nothing else, so a batch can hold millions and clone
8//! them freely: every handle of a file shares the one table the file's
9//! parse charged to the input's meter (plan section 3.12). Reading goes
10//! through [`crate::walk::read_typetree_with_reader`], by the rules of the
11//! file's reader ([`SerializedFile::reader_kind`]), with the tree that
12//! [`ObjectRef::tree`] resolves (plan section 3.12: explicit, embedded, then
13//! the provider chain with the class and packed version as its key).
14//!
15//! Owner: package D. The constructor and getters are implemented by the
16//! scaffold.
17
18use std::sync::Arc;
19
20use bytes::Bytes;
21
22use crate::budget::DecodeBuf;
23use crate::error::{Error, LimitKind};
24use crate::files::{ObjectInfo, SerializedFile, SerializedType};
25use crate::provider::{NoTree, TreeRef, TreeRequest, TreeSource};
26use crate::typetree::Tree;
27use crate::value::Parsed;
28use crate::walk::{ParseError, ReadCtx, WriteCtx, WriteError, WriteRules};
29
30/// One object of a `SerializedFile`: the file and the index of its row
31/// (module docs).
32#[derive(Clone, Debug)]
33pub struct ObjectRef {
34 file: Arc<SerializedFile>,
35 index: u32,
36}
37
38/// What [`ObjectRef::info`] would answer for an index [`ObjectRef::new`] did
39/// not check. Never returned: `new` checks the index, and a file's object
40/// table never changes after its parse.
41static NO_ROW: ObjectInfo = ObjectInfo {
42 path_id: 0,
43 byte_start: 0,
44 byte_size: 0,
45 type_id: 0,
46 class_id: 0,
47 type_index: None,
48 is_destroyed: None,
49 is_stripped: None,
50 script_type_index: None,
51};
52
53impl ObjectRef {
54 /// Read only the MonoBehaviour head, ignoring trailing script fields
55 /// (`files/ObjectReader.py:325-330`). With no override, request class 114
56 /// from the providers, even when the object stores an embedded tree.
57 pub fn parse_monobehaviour_head(
58 &self,
59 nodes: Option<&Arc<Tree>>,
60 ) -> Result<Parsed, ParseError> {
61 if let Some(nodes) = nodes {
62 return self.read_typetree_object(Some(nodes), false);
63 }
64 let tree = self
65 .file
66 .version()
67 .map(|version| {
68 self.file.context().providers.lookup(&TreeRequest {
69 class_id: 114,
70 version: &version.version,
71 script: None,
72 })
73 })
74 .transpose()?
75 .flatten()
76 .ok_or(ParseError::NoTypeTree {
77 class_id: 114,
78 why: self
79 .file
80 .context()
81 .providers
82 .why_none(114, self.file.version().map(|v| &v.version)),
83 })?;
84 self.read_typetree_object(Some(&tree.tree), false)
85 }
86
87 /// The object at `index` in [`SerializedFile::object_infos`], or `None`
88 /// past the table's end.
89 #[must_use]
90 pub fn new(file: Arc<SerializedFile>, index: u32) -> Option<Self> {
91 file.object_infos().get(usize::try_from(index).ok()?)?;
92 Some(Self { file, index })
93 }
94
95 /// The file it belongs to.
96 #[must_use]
97 pub fn file(&self) -> &Arc<SerializedFile> {
98 &self.file
99 }
100
101 /// Its index in [`SerializedFile::object_infos`].
102 #[must_use]
103 pub fn index(&self) -> u32 {
104 self.index
105 }
106
107 /// Its table row, read from the file's table (no copy).
108 #[must_use]
109 pub fn info(&self) -> &ObjectInfo {
110 usize::try_from(self.index)
111 .ok()
112 .and_then(|i| self.file.object_infos().get(i))
113 .unwrap_or(&NO_ROW)
114 }
115
116 /// `path_id`.
117 #[must_use]
118 pub fn path_id(&self) -> i64 {
119 self.info().path_id
120 }
121
122 /// `class_id`.
123 #[must_use]
124 pub fn class_id(&self) -> i32 {
125 self.info().class_id
126 }
127
128 /// The type record it resolves to, if any.
129 #[must_use]
130 pub fn serialized_type(&self) -> Option<&SerializedType> {
131 self.file.types().get(self.info().type_index?)
132 }
133
134 /// `get_raw_data`: `byte_size` bytes from `byte_start`, cut short at the
135 /// end of the file (a slice of the file's buffer, no copy, so it keeps
136 /// that whole buffer alive while it lives: a bundle entry's run, unlike
137 /// [`Self::read_typetree`]'s value, which [`crate::pin`] copies out of a
138 /// much larger run), by the file's reader's rules
139 /// ([`SerializedFile::reader_kind`]): the stream
140 /// reader (a file loaded from a path) refuses a negative `byte_start`, or
141 /// one at or above 2^63, as UnityPy's does on every machine, where the
142 /// memory reader slices from the end or reads nothing. A `byte_start`
143 /// past the largest file the file system takes is UnityPy's `OSError`
144 /// on that machine; the stream reader takes it and reads nothing
145 /// ([`crate::stream::ReaderKind`], `PARITY.md` section 19.3).
146 pub fn raw_data(&self) -> Result<Bytes, Error> {
147 // UnityPy files/ObjectReader.py:278-283: `reset()`, then
148 // `read_bytes(byte_size)`.
149 let info = self.info();
150 let data = self.file.data();
151 let kind = self.file.reader_kind();
152 let start = kind.seek(info.byte_start)?;
153 let (range, _) = kind.read(data.len(), start, i64::from(info.byte_size))?;
154 Ok(data.slice(range))
155 }
156
157 /// The tree a read would use: `nodes` when given, else the type record's,
158 /// else the provider chain's class tree (`ObjectReader.py:285-307`), with
159 /// no script (`TreeRequest::script` is `None`). `Ok(None)` where UnityPy
160 /// raises: [`Self::why_no_tree`] says which exception. The
161 /// `MonoBehaviour` script hook needs the Environment to dereference
162 /// `m_Script`: [`crate::env::Environment::object_tree`].
163 pub fn tree(&self, nodes: Option<&Arc<Tree>>) -> Result<Option<TreeRef>, ParseError> {
164 // UnityPy files/ObjectReader.py:285-307
165 if let Some(tree) = nodes {
166 return Ok(Some(TreeRef {
167 tree: tree.clone(),
168 source: TreeSource::Explicit,
169 }));
170 }
171 // :296-297: the type record's own tree, when it has one.
172 if let Some(st) = self.serialized_type()
173 && let Some(tree) = st.tree(&self.file.context().limits)
174 {
175 return Ok(Some(TreeRef {
176 tree: tree?,
177 source: TreeSource::Embedded,
178 }));
179 }
180 // :298-299: `get_typetree_node(class_id, version)`. A file below
181 // format 7 has no version: UnityPy's `assets_file.version` is unset,
182 // so the `ObjectReader.version` property's `AttributeError` falls to
183 // `ObjectReader.__getattr__` (:223-225), which returns `None`, and
184 // `get_typetree_node` raises with that `None` (`why_no_tree` names
185 // which exception: `NoTree::NoVersion` for the comparison). No tree.
186 let Some(version) = self.file.version() else {
187 return Ok(None);
188 };
189 let req = TreeRequest {
190 class_id: self.class_id(),
191 version: &version.version,
192 script: None,
193 };
194 Ok(self.file.context().providers.lookup(&req)?)
195 }
196
197 /// Why [`Self::tree`] finds none for this object without `nodes` (its
198 /// type record holds none, and no provider has its class's): the
199 /// exception UnityPy raises there ([`NoTree`],
200 /// [`ProviderChain::why_none`] for the file's version, or for none below
201 /// format 7). `None` where no provider says. What
202 /// [`ParseError::NoTypeTree`] and [`WriteError::NoTypeTree`] carry.
203 ///
204 /// [`ProviderChain::why_none`]: crate::provider::ProviderChain::why_none
205 #[must_use]
206 pub fn why_no_tree(&self) -> Option<NoTree> {
207 let version = self.file.version().map(|v| &v.version);
208 self.file
209 .context()
210 .providers
211 .why_none(self.class_id(), version)
212 }
213
214 /// `read_typetree(nodes, wrap=False, check_read)`.
215 pub fn read_typetree(
216 &self,
217 nodes: Option<&Arc<Tree>>,
218 check_read: bool,
219 ) -> Result<Parsed, ParseError> {
220 self.read_typetree_mode(nodes, check_read, false)
221 }
222
223 /// Read the dictionary on the supplied meter with exact serialized
224 /// float bits, including signalling NaNs used by some animation slots.
225 /// Tree resolution stays scoped to the owning file.
226 pub fn read_typetree_lossless(
227 &self,
228 nodes: Option<&Arc<Tree>>,
229 check_read: bool,
230 meter: &Arc<crate::limits::Meter>,
231 ) -> Result<Parsed, ParseError> {
232 self.read_fields_mode(nodes, check_read, false, None, Some(meter))
233 }
234
235 /// Read object-mode values into the dict model, retaining the Python
236 /// reader's pointer and referenced-type validation. The binding constructs
237 /// Python classes from these values; the core fallback also uses this mode.
238 pub fn read_typetree_object(
239 &self,
240 nodes: Option<&Arc<Tree>>,
241 check_read: bool,
242 ) -> Result<Parsed, ParseError> {
243 self.read_typetree_mode(nodes, check_read, true)
244 }
245
246 /// Read each child's node and value without collapsing duplicate names.
247 /// A later reader error is returned with the completed construction prefix.
248 pub fn read_object_fields(&self) -> Result<(Parsed, crate::walk::FieldProgress), ParseError> {
249 self.read_object_fields_with_nodes(None)
250 }
251
252 /// Read object fields using an explicit tree before the file's own tree.
253 pub fn read_object_fields_with_nodes(
254 &self,
255 nodes: Option<&Arc<Tree>>,
256 ) -> Result<(Parsed, crate::walk::FieldProgress), ParseError> {
257 let mut progress = crate::walk::FieldProgress::default();
258 let parsed = self.read_fields_mode(nodes, false, true, Some(&mut progress), None)?;
259 Ok((parsed, progress))
260 }
261
262 fn read_typetree_mode(
263 &self,
264 nodes: Option<&Arc<Tree>>,
265 check_read: bool,
266 object_mode: bool,
267 ) -> Result<Parsed, ParseError> {
268 self.read_fields_mode(nodes, check_read, object_mode, None, None)
269 }
270
271 fn read_fields_mode(
272 &self,
273 nodes: Option<&Arc<Tree>>,
274 check_read: bool,
275 object_mode: bool,
276 progress: Option<&mut crate::walk::FieldProgress>,
277 lossless_meter: Option<&Arc<crate::limits::Meter>>,
278 ) -> Result<Parsed, ParseError> {
279 // UnityPy files/ObjectReader.py:244-262
280 let Some(tree) = self.tree(nodes)? else {
281 return Err(ParseError::NoTypeTree {
282 class_id: self.class_id(),
283 why: self.why_no_tree(),
284 });
285 };
286 let file = &self.file;
287 let mut options = file.context().read_options();
288 if lossless_meter.is_some() {
289 options.floats = crate::walk::FloatMode::Lossless;
290 }
291 let ctx = ReadCtx {
292 endian: file.header().endian,
293 ref_types: file.ref_types_view(),
294 options: &options,
295 meter: lossless_meter.unwrap_or_else(|| file.meter()),
296 };
297 let info = self.info();
298 let mut read = crate::walk::read_with_fields(
299 file.data(),
300 info.byte_start,
301 info.byte_size,
302 &tree.tree,
303 &ctx,
304 check_read,
305 (file.reader_kind(), file.header().version >= 23, object_mode),
306 progress,
307 );
308 // A value kept past the file's handles keeps alive the buffer its
309 // slices are of: copied out of a run much larger than they are
310 // (`crate::pin`; plan section 8, R3), `check_read`'s value too.
311 let value = match &mut read {
312 Ok(value) => Some(value),
313 Err(ParseError::CheckRead { parsed, .. }) => Arc::get_mut(parsed),
314 Err(_) => None,
315 };
316 if let Some(value) = value {
317 file.unpin(value, lossless_meter).map_err(|error| {
318 crate::walk::charge_error(u64::try_from(value.bytes_read).unwrap_or(0), error)
319 })?;
320 }
321 read
322 }
323
324 /// The type record's own tree once it is compiled (the tree
325 /// [`Self::tree`] resolves with no `nodes` for an object whose record
326 /// stores one), without compiling or waiting: `None` until a read has
327 /// compiled it, or when the record has none.
328 #[must_use]
329 pub fn compiled_tree(&self) -> Option<&Arc<Tree>> {
330 self.serialized_type()?.compiled_tree()
331 }
332
333 /// [`Self::read_typetree`] with `tree` as `nodes`, its values handed to
334 /// `sink` as they are read ([`crate::walk::emit`]), and the bytes read;
335 /// or `None` where the direct read gives up, and the full read is to be
336 /// made instead. Only an object of `byte_size > 0` (UnityPyBoost's
337 /// reader) is read; a `check_read` mismatch gives up too. The read's
338 /// work, and `extra_work` of the caller's, are counted on the file's
339 /// meter in one check-and-add once the values are made; work the
340 /// allowance cannot hold gives up, counting nothing, and the read stops
341 /// as soon as its own work passes what the allowance holds. Copies none
342 /// of the file's bytes out ([`crate::pin`]): the sink's values are its
343 /// own.
344 pub fn emit_typetree<S: crate::walk::emit::Sink>(
345 &self,
346 tree: &Tree,
347 check_read: bool,
348 sink: &mut S,
349 extra_work: impl FnOnce(&S) -> u64,
350 ) -> Option<(S::Obj, i64)> {
351 let meter = self.file.meter();
352 let (value, bytes_read, work) = self
353 .emit_typetree_uncounted(tree, check_read, sink, meter.work_left())
354 .ok()?;
355 let work = work.checked_add(extra_work(sink))?;
356 meter.try_count_work(work).then_some((value, bytes_read))
357 }
358
359 /// [`Self::emit_typetree`]'s read, its work (at most `max_work`, or it
360 /// gives up) returned, not counted: the caller counts it. A read that
361 /// gives up returns the work it did (`Err`), for the caller to count.
362 pub fn emit_typetree_uncounted<S: crate::walk::emit::Sink>(
363 &self,
364 tree: &Tree,
365 check_read: bool,
366 sink: &mut S,
367 max_work: u64,
368 ) -> Result<(S::Obj, i64, u64), u64> {
369 let info = self.info();
370 let file = &self.file;
371 if info.byte_size == 0 || file.meter().work_used_up().is_some() {
372 return Err(0);
373 }
374 let options = file.context().read_options();
375 // UnityPy TypeTreeHelper.py:146-153: the memory reader's slice of
376 // `byte_size` bytes from `byte_start`, as `read_with_fields` takes it.
377 let kind = file.reader_kind();
378 let start = kind.seek(info.byte_start).map_err(|_| 0_u64)?;
379 let (range, _) = kind
380 .read(file.data().len(), start, i64::from(info.byte_size))
381 .map_err(|_| 0_u64)?;
382 let data = file.data().get(range).ok_or(0_u64)?;
383 let read = crate::walk::emit::emit(
384 data,
385 tree,
386 file.header().endian == crate::stream::Endian::Big,
387 options.floats,
388 options.limits.max_value_depth,
389 max_work,
390 sink,
391 )?;
392 let bytes_read = i64::try_from(read.bytes_read).map_err(|_| read.work)?;
393 if check_read && bytes_read != i64::from(info.byte_size) {
394 return Err(read.work);
395 }
396 Ok((read.value, bytes_read, read.work))
397 }
398
399 /// `parse_as_dict(check_read=check_read)`: [`Self::read_typetree`] with
400 /// the resolved tree.
401 pub fn parse_as_dict(&self, check_read: bool) -> Result<Parsed, ParseError> {
402 self.read_typetree(None, check_read)
403 }
404
405 /// Replace the bytes file save will write, and mark every parent changed.
406 /// Reads continue using the original reader, as UnityPy does.
407 pub fn set_raw_data(&self, data: impl AsRef<[u8]>) -> Result<(), crate::files::SaveError> {
408 self.file.set_raw_data(self.index, data.as_ref())
409 }
410
411 /// Restore the original save payload, marking this file and its parents.
412 /// Reads continue using the original reader throughout.
413 pub fn clear_raw_data(&self) {
414 self.file.clear_raw_data(self.index);
415 }
416
417 /// Write and install a typetree, as `files/ObjectReader.py:264-276` does.
418 /// A failed write or replacement leaves the file's previous edit intact.
419 pub fn save_typetree(
420 &self,
421 value: &Parsed,
422 nodes: Option<&Arc<Tree>>,
423 rules: WriteRules,
424 ) -> Result<Bytes, crate::files::SaveError> {
425 let bytes = self.write_typetree(value, nodes, rules)?;
426 self.set_raw_data(&bytes)?;
427 Ok(bytes)
428 }
429
430 /// `save_typetree`'s bytes: UnityPy's writer (or `rules`) over `value`,
431 /// written into a buffer charged to the file's input meter, whose charge
432 /// rides in the returned `Bytes`.
433 pub fn write_typetree(
434 &self,
435 value: &Parsed,
436 nodes: Option<&Arc<Tree>>,
437 rules: WriteRules,
438 ) -> Result<Bytes, WriteError> {
439 // UnityPy files/ObjectReader.py:264-276
440 // `_get_typetree_node` raised: the writer never ran.
441 let tree = match self.tree(nodes) {
442 Ok(Some(t)) => t.tree,
443 Ok(None) => {
444 return Err(WriteError::NoTypeTree {
445 class_id: self.class_id(),
446 why: self.why_no_tree(),
447 });
448 }
449 Err(e) => return Err(WriteError::Tree(Box::new(e))),
450 };
451 let file = &self.file;
452 let limits = file.context().limits;
453 let ctx = WriteCtx {
454 endian: file.header().endian,
455 ref_types: file.ref_types_view(),
456 rules,
457 limits: &limits,
458 };
459 let mut out = DecodeBuf::new(file.meter(), 0, u64::MAX, LimitKind::InputMemory)
460 .map_err(WriteError::Charge)?;
461 crate::walk::write::write(value, &tree, &ctx, &mut out)?;
462 out.into_bytes().map_err(WriteError::Charge)
463 }
464}
465
466#[cfg(test)]
467mod tests {
468 use std::mem::size_of;
469 use std::sync::Arc;
470
471 use super::ObjectRef;
472 use crate::files::{ObjectInfo, SerializedFile};
473
474 #[test]
475 fn a_handle_holds_the_file_and_an_index_and_reads_its_row_from_the_table() {
476 // Round 4 (Codex): every handle held its own copy of the row, so
477 // handles kept or cloned by a caller duplicated the object table
478 // outside the meter that paid for it.
479 assert_eq!(
480 size_of::<ObjectRef>(),
481 size_of::<Arc<SerializedFile>>() + size_of::<u64>()
482 );
483 let row = |path_id| ObjectInfo {
484 path_id,
485 byte_start: 0,
486 byte_size: 4,
487 type_id: 0,
488 class_id: 114,
489 type_index: None,
490 is_destroyed: None,
491 is_stripped: None,
492 script_type_index: None,
493 };
494 let file = SerializedFile::for_tests(vec![row(7), row(-3)]);
495 let o = ObjectRef::new(file.clone(), 1).unwrap();
496 assert!(
497 std::ptr::eq(o.info(), &raw const file.object_infos()[1]),
498 "the file's own row"
499 );
500 assert_eq!((o.path_id(), o.class_id()), (-3, 114));
501 assert!(ObjectRef::new(file.clone(), 2).is_none());
502 let ids: Vec<i64> = file.objects().map(|o| o.path_id()).collect();
503 assert_eq!(ids, [7, -3]);
504 }
505}