Skip to main content

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}