Skip to main content

unityrs_core/objmode/
mod.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPyBoost/TypeTreeHelper.cpp's object mode (clean_name, parse_class) and the attrs fields of UnityPy/classes/generated.py's Mesh, Sprite, VertexData, ChannelInfo, StreamInfo, SubMesh, StreamingInfo, CompressedMesh, PackedBitVector, BoneWeights4, BoneInfluence and SpriteRenderData, as MeshHandler reads them. See THIRD_PARTY_LICENSES.
2//! An object-mode view: a dict-mode value the core read, viewed as the
3//! objects UnityPy's object mode builds from it.
4//!
5//! UnityPy hands `MeshHandler` an object (`obj.read()`), which UnityPyBoost
6//! builds class by class (`parse_class`, `UnityPyBoost/TypeTreeHelper.cpp:458-583`;
7//! `PARITY.md` section 9.2): each class node's fields are its children's
8//! clean names (`clean_name`, `:28-65`), and the class named by the node's
9//! type is called with them. A class whose required field is missing, or a
10//! slotted class (every class here but `Mesh` and `Sprite`, `PARITY.md`
11//! section 9.2.1) given a field it lacks, falls back to an `UnknownObject`
12//! holding the fields as attributes. So a field the handler reads is the
13//! value of the last child of that clean name, and a missing one is the
14//! field's default (`None`) on a class that was built and an
15//! `AttributeError` on an `UnknownObject` ([`Obj::get`]).
16//!
17//! The core's value is a dict keyed by each child's raw name (the first
18//! child of a name holding its last value), so [`Obj`] finds the child by
19//! clean name in the node list and its value under its raw name, never
20//! copying.
21//!
22//! **What is refused** ([`ViewError::Malformed`], Tier U): a node whose
23//! type is not the class its field's typetree names (object mode would look
24//! up another class); a field whose value is not of a type some version's
25//! typetree gives it (an `int` field holding a string, a class field
26//! holding an `int`), or an integer outside the widest type any version
27//! gives it (`ChannelInfo`'s `UInt8`s, `StreamInfo`'s `UInt32`s). UnityPy's
28//! arithmetic on such values is uncharacterised, and the bounds keep every
29//! loop the handler runs proportional to its input. A message names a node's
30//! type by at most [`NAME_BYTES`] bytes of it ([`type_name`]), so a refusal
31//! allocates no more for a long one.
32//!
33//! **Work.** Each scan of a node's children counts one unit of decode work
34//! for every name the scan may compare, counted before it, on the meter
35//! [`Obj`] carries: [`Obj::get`] the children and the dict's entries, and
36//! the test of whether object mode builds a class ([`builds`]) each child
37//! against each field it looks for. So reading a class of N fields is work
38//! in N, wherever the handler reads it.
39
40use crate::limits::Meter;
41use crate::typetree::{NodeId, NodeList};
42use crate::{Map, Parsed, PrimArray, RawStr, Value};
43
44use self::error::ViewError as MeshError;
45mod error;
46pub use error::ViewError;
47
48/// The most bytes of a node's type a [`ViewError::Malformed`] message holds
49/// (module docs).
50pub const NAME_BYTES: usize = 64;
51
52/// `ty` for a message: its bytes as `escape_ascii` escapes them, at most
53/// [`NAME_BYTES`] of output, cut between two escapes and then followed by
54/// `…`.
55struct TypeName<'a>(&'a [u8]);
56fn type_name(ty: &[u8]) -> TypeName<'_> {
57    TypeName(ty)
58}
59impl std::fmt::Display for TypeName<'_> {
60    fn fmt(&self, out: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
61        use std::fmt::Write;
62        let mut written = 0;
63        for &b in self.0 {
64            let escaped = b.escape_ascii();
65            if written + escaped.len() > NAME_BYTES {
66                return out.write_str("…");
67            }
68            written += escaped.len();
69            for c in escaped {
70                out.write_char(char::from(c))?;
71            }
72        }
73        Ok(())
74    }
75}
76struct TypeNames(&'static [&'static str]);
77impl std::fmt::Display for TypeNames {
78    fn fmt(&self, out: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
79        for (i, ty) in self.0.iter().enumerate() {
80            if i > 0 {
81                out.write_str(" or ")?;
82            }
83            out.write_str(ty)?;
84        }
85        Ok(())
86    }
87}
88
89/// Counts `n` units of work on `meter` (module docs).
90fn count(meter: &Meter, n: usize) -> Result<(), MeshError> {
91    meter.count_decode(u64::try_from(n).unwrap_or(u64::MAX))?;
92    Ok(())
93}
94
95pub use classes::*;
96mod classes;
97
98/// Whether UnityPyBoost's `clean_name(name)`
99/// (`UnityPyBoost/TypeTreeHelper.cpp:28-65`) is `target`, a plain
100/// identifier: a leading `(int&)` and one trailing `?` dropped, and each of
101/// ` .:-[]` read as `_` (the `pass`/`from` and leading-digit rules cannot
102/// make any target here).
103fn clean_name_is(name: &[u8], target: &str) -> bool {
104    let name = name.strip_prefix(b"(int&)").unwrap_or(name);
105    let name = name.strip_suffix(b"?").unwrap_or(name);
106    let target = target.as_bytes();
107    name.len() == target.len()
108        && name.iter().zip(target).all(|(&a, &b)| {
109            let a = if b" .:-[]".contains(&a) { b'_' } else { a };
110            a == b
111        })
112}
113
114/// Whether object mode builds `node` as `class` rather than an
115/// `UnknownObject` (`UnityPyBoost/TypeTreeHelper.cpp:501-574`): every
116/// required field among its children's clean names, and, for a slotted
117/// class, none that is not a field. The comparisons are counted on `meter`
118/// first: each child against each required field, and, for a slotted
119/// class, against every field.
120fn builds(list: &NodeList, node: NodeId, class: &Class, meter: &Meter) -> Result<bool, MeshError> {
121    let kids = list.children(node);
122    let fields = class.required.len().saturating_add(class.optional.len());
123    let per_child = class
124        .required
125        .len()
126        .saturating_add(if class.slotted { fields } else { 0 });
127    count(meter, kids.len().saturating_mul(per_child))?;
128    let has = |f: &str| kids.iter().any(|&c| clean_name_is(list.name(c), f));
129    let is_field = |c: NodeId| {
130        class
131            .required
132            .iter()
133            .chain(class.optional)
134            .any(|f| clean_name_is(list.name(c), f))
135    };
136    Ok(class.required.iter().all(|f| has(f))
137        && (!class.slotted || kids.iter().all(|&c| is_field(c))))
138}
139
140/// One object, as object mode builds it from a class node (module docs),
141/// with the meter its reads count their work on.
142#[derive(Clone, Copy, Debug)]
143pub struct Obj<'a> {
144    list: &'a NodeList,
145    node: NodeId,
146    map: &'a Map,
147    built: bool,
148    meter: &'a Meter,
149}
150
151const _: () = crate::send_sync::<Obj<'static>>();
152
153impl<'a> Obj<'a> {
154    /// The root object of `parsed`, a node of `class`, its reads counted on
155    /// `meter`.
156    pub fn root(
157        parsed: &'a Parsed,
158        class: &'static Class,
159        meter: &'a Meter,
160    ) -> Result<Self, MeshError> {
161        let list = parsed.lists().first().ok_or_else(|| {
162            MeshError::malformed(format_args!("{}", "a value without a tree"), meter)
163        })?;
164        Self::new(
165            list,
166            list.root(),
167            parsed.value(),
168            class,
169            "the object",
170            meter,
171        )
172    }
173
174    /// `node`'s object, `value` its dict.
175    fn new(
176        list: &'a NodeList,
177        node: NodeId,
178        value: &'a Value,
179        class: &'static Class,
180        field: &str,
181        meter: &'a Meter,
182    ) -> Result<Self, MeshError> {
183        let ty = list.type_name(node);
184        if !class.types.iter().any(|t| t.as_bytes() == ty) {
185            return Err(MeshError::malformed(
186                format_args!(
187                    "{field} has type {}, not {}",
188                    type_name(ty),
189                    TypeNames(class.types)
190                ),
191                meter,
192            ));
193        }
194        let Value::Dict(map) = value else {
195            return Err(MeshError::malformed(
196                format_args!("{field} is not a class"),
197                meter,
198            ));
199        };
200        if map.list() != 0 {
201            return Err(MeshError::malformed(
202                format_args!("{field} is read through a referenced type"),
203                meter,
204            ));
205        }
206        Ok(Self {
207            list,
208            node,
209            map,
210            built: builds(list, node, class, meter)?,
211            meter,
212        })
213    }
214
215    /// Whether object mode built the class, not an `UnknownObject`.
216    #[must_use]
217    pub fn built(&self) -> bool {
218        self.built
219    }
220
221    /// The child whose clean name is `name`: the last, as object mode's
222    /// dict keeps the last value of a name.
223    fn child(&self, name: &str) -> Option<NodeId> {
224        self.list
225            .children(self.node)
226            .iter()
227            .rev()
228            .find(|&&c| clean_name_is(self.list.name(c), name))
229            .copied()
230    }
231
232    /// The attribute `name` (module docs): its value; `None`, the field's
233    /// default, on a class that was built; `AttributeError` on an
234    /// `UnknownObject`. Its scans, of the children and of the dict, are
235    /// counted first, a unit a name.
236    pub fn get(&self, name: &'static str) -> Result<Option<(NodeId, &'a Value)>, MeshError> {
237        let scanned = self
238            .list
239            .children(self.node)
240            .len()
241            .saturating_add(self.map.entries().len());
242        count(self.meter, scanned)?;
243        let found = self.child(name).and_then(|c| {
244            let raw = self.list.name(c);
245            self.map
246                .entries()
247                .iter()
248                .find(|(k, _)| self.list.name(*k) == raw)
249                .map(|(_, v)| (c, v))
250        });
251        match found {
252            Some(hit) => Ok(Some(hit)),
253            None if self.built => Ok(None),
254            None => Err(MeshError::NoAttribute(name)),
255        }
256    }
257
258    /// The attribute `name`, an integer from 0 to `max` (a Python `bool`
259    /// reads as its `int`, as Python's arithmetic takes it).
260    pub fn uint(&self, name: &'static str, max: u64) -> Result<Option<u64>, MeshError> {
261        let Some((_, v)) = self.get(name)? else {
262            return Ok(None);
263        };
264        let n = match v {
265            Value::Bool(b) => Some(u64::from(*b)),
266            Value::Int(i) => u64::try_from(*i).ok(),
267            Value::UInt(u) => Some(*u),
268            _ => {
269                return Err(MeshError::malformed(
270                    format_args!("{name} is not an integer"),
271                    self.meter,
272                ));
273            }
274        };
275        match n {
276            Some(n) if n <= max => Ok(Some(n)),
277            _ => Err(MeshError::malformed(
278                format_args!("{name} is out of its range"),
279                self.meter,
280            )),
281        }
282    }
283
284    /// The attribute `name`, a 32-bit signed integer (a `bool` as its
285    /// `int`).
286    pub fn int32(&self, name: &'static str) -> Result<Option<i64>, MeshError> {
287        let Some((_, v)) = self.get(name)? else {
288            return Ok(None);
289        };
290        let n = match v {
291            Value::Bool(b) => i64::from(*b),
292            Value::Int(i) if i32::try_from(*i).is_ok() => *i,
293            Value::Int(_) | Value::UInt(_) => {
294                return Err(MeshError::malformed(
295                    format_args!("{name} is out of its range"),
296                    self.meter,
297                ));
298            }
299            _ => {
300                return Err(MeshError::malformed(
301                    format_args!("{name} is not an integer"),
302                    self.meter,
303                ));
304            }
305        };
306        Ok(Some(n))
307    }
308
309    /// The attribute `name`, a `float` (a `float` or `double` leaf, read as
310    /// Python reads it: a `float`'s bits widened as `struct`'s `f` widens
311    /// them, [`widen`]).
312    pub fn float(&self, name: &'static str) -> Result<Option<f64>, MeshError> {
313        match self.get(name)? {
314            None => Ok(None),
315            Some((_, Value::F32(bits))) => Ok(Some(widen(*bits))),
316            Some((_, Value::F64(bits))) => Ok(Some(f64::from_bits(*bits))),
317            Some(_) => Err(MeshError::malformed(
318                format_args!("{name} is not a float"),
319                self.meter,
320            )),
321        }
322    }
323
324    /// The attribute `name`, `bytes` (`TypelessData`).
325    pub fn bytes(&self, name: &'static str) -> Result<Option<&'a [u8]>, MeshError> {
326        match self.get(name)? {
327            None => Ok(None),
328            Some((_, Value::Bytes(b))) => Ok(Some(b)),
329            Some(_) => Err(MeshError::malformed(
330                format_args!("{name} is not bytes"),
331                self.meter,
332            )),
333        }
334    }
335
336    /// The attribute `name`, a `str`.
337    pub fn string(&self, name: &'static str) -> Result<Option<&'a RawStr>, MeshError> {
338        match self.get(name)? {
339            None => Ok(None),
340            Some((_, Value::Str(s))) => Ok(Some(s)),
341            Some(_) => Err(MeshError::malformed(
342                format_args!("{name} is not a string"),
343                self.meter,
344            )),
345        }
346    }
347
348    /// The attribute `name`, an object of `class`.
349    pub fn class(
350        &self,
351        name: &'static str,
352        class: &'static Class,
353    ) -> Result<Option<Obj<'a>>, MeshError> {
354        match self.get(name)? {
355            None => Ok(None),
356            Some((node, v)) => Self::new(self.list, node, v, class, name, self.meter).map(Some),
357        }
358    }
359
360    /// The attribute `name`, a list of objects of `class`.
361    pub fn list(
362        &self,
363        name: &'static str,
364        class: &'static Class,
365    ) -> Result<Option<List<'a>>, MeshError> {
366        let Some((node, v)) = self.get(name)? else {
367            return Ok(None);
368        };
369        let items: &'a [Value] = match v {
370            Value::List(items) => items,
371            Value::Tuple(items) => items,
372            Value::Prims(p) if p.is_empty() => &[],
373            _ => {
374                return Err(MeshError::malformed(
375                    format_args!("{name} is not a list of classes"),
376                    self.meter,
377                ));
378            }
379        };
380        // UnityPy TypeTreeHelper.cpp:812-874: a vector's element is its
381        // `Array` child's second child.
382        let elem = match self.list.children(node) {
383            [array, ..] => match self.list.children(*array) {
384                [_, elem] => Some(*elem),
385                _ => None,
386            },
387            [] => None,
388        };
389        let Some(elem) = elem else {
390            return Err(MeshError::malformed(
391                format_args!("{name} is not a vector"),
392                self.meter,
393            ));
394        };
395        Ok(Some(List {
396            nodes: self.list,
397            elem,
398            items,
399            class,
400            name,
401            built: builds(self.list, elem, class, self.meter)?,
402            meter: self.meter,
403        }))
404    }
405
406    /// The attribute `name`, a list of integers.
407    pub fn ints(&self, name: &'static str) -> Result<Option<Ints<'a>>, MeshError> {
408        match self.get(name)? {
409            None => Ok(None),
410            Some((_, v)) => Ints::of(v, name, self.meter).map(Some),
411        }
412    }
413}
414
415/// A list of objects of one class (one element node, so one answer to
416/// whether object mode builds them).
417#[derive(Clone, Copy, Debug)]
418pub struct List<'a> {
419    nodes: &'a NodeList,
420    elem: NodeId,
421    items: &'a [Value],
422    class: &'static Class,
423    name: &'static str,
424    built: bool,
425    meter: &'a Meter,
426}
427
428const _: () = crate::send_sync::<List<'static>>();
429
430impl<'a> List<'a> {
431    /// The number of elements.
432    #[must_use]
433    pub fn len(&self) -> usize {
434        self.items.len()
435    }
436
437    /// Whether there are no elements.
438    #[must_use]
439    pub fn is_empty(&self) -> bool {
440        self.len() == 0
441    }
442
443    /// Element `i`, if there is one.
444    #[must_use]
445    pub fn get(&self, i: usize) -> Option<Result<Obj<'a>, MeshError>> {
446        let v = self.items.get(i)?;
447        Some(self.element(v))
448    }
449
450    fn element(&self, v: &'a Value) -> Result<Obj<'a>, MeshError> {
451        let ty = self.nodes.type_name(self.elem);
452        if !self.class.types.iter().any(|t| t.as_bytes() == ty) {
453            return Err(MeshError::malformed(
454                format_args!("{}'s elements have type {}", self.name, type_name(ty)),
455                self.meter,
456            ));
457        }
458        let Value::Dict(map) = v else {
459            return Err(MeshError::malformed(
460                format_args!("{}'s elements are not classes", self.name),
461                self.meter,
462            ));
463        };
464        if map.list() != 0 {
465            return Err(MeshError::malformed(
466                format_args!("{} is read through a referenced type", self.name),
467                self.meter,
468            ));
469        }
470        Ok(Obj {
471            list: self.nodes,
472            node: self.elem,
473            map,
474            built: self.built,
475            meter: self.meter,
476        })
477    }
478
479    /// The elements in order.
480    pub fn iter(&self) -> impl Iterator<Item = Result<Obj<'a>, MeshError>> + '_ {
481        self.items.iter().map(|v| self.element(v))
482    }
483}
484
485/// A list of integers: a primitive run, or a list or tuple of `int`s.
486#[derive(Clone, Copy, Debug)]
487pub enum Ints<'a> {
488    /// A primitive run.
489    Run(&'a PrimArray, &'a Meter),
490    /// A list or tuple of values, each checked as it is read.
491    Items(&'a [Value], &'static str, &'a Meter),
492    /// `bytes` (`TypelessData`), which `bytes()` copies as it is.
493    Raw(&'a [u8], &'a Meter),
494}
495
496const _: () = crate::send_sync::<Ints<'static>>();
497
498impl<'a> Ints<'a> {
499    fn meter(&self) -> &Meter {
500        match self {
501            Self::Run(_, m) | Self::Items(_, _, m) | Self::Raw(_, m) => m,
502        }
503    }
504
505    fn of(v: &'a Value, name: &'static str, meter: &'a Meter) -> Result<Self, MeshError> {
506        match v {
507            Value::Prims(p) => match p {
508                PrimArray::F32(_) | PrimArray::F64(_) if !p.is_empty() => Err(
509                    MeshError::malformed(format_args!("{name} is not a list of integers"), meter),
510                ),
511                _ => Ok(Self::Run(p, meter)),
512            },
513            Value::List(items) => Ok(Self::Items(items, name, meter)),
514            Value::Tuple(items) => Ok(Self::Items(items, name, meter)),
515            Value::Bytes(b) => Ok(Self::Raw(b, meter)),
516            _ => Err(MeshError::malformed(
517                format_args!("{name} is not a list"),
518                meter,
519            )),
520        }
521    }
522
523    /// The number of integers.
524    #[must_use]
525    pub fn len(&self) -> usize {
526        match self {
527            Self::Run(p, _) => p.len(),
528            Self::Items(items, _, _) => items.len(),
529            Self::Raw(b, _) => b.len(),
530        }
531    }
532
533    /// Whether there are no integers.
534    #[must_use]
535    pub fn is_empty(&self) -> bool {
536        self.len() == 0
537    }
538
539    /// Element `i` of `bytes(self)`: the value, which must be a byte
540    /// (`ValueError` "bytes must be in range(0, 256)" otherwise; a `bool`
541    /// is its `int`). `i` past the end reads as 0.
542    pub fn byte(&self, i: usize) -> Result<u8, MeshError> {
543        fn byte<T: TryInto<u8>>(v: Option<T>) -> Result<u8, MeshError> {
544            v.map_or(Ok(0), |v| v.try_into().map_err(|_| MeshError::ByteRange))
545        }
546        match self {
547            Self::Run(p, _) => match p {
548                PrimArray::U8(b) => Ok(b.get(i).copied().unwrap_or(0)),
549                PrimArray::Bool(v) => Ok(v.get(i).copied().map_or(0, u8::from)),
550                PrimArray::I8(v) => byte(v.get(i).copied()),
551                PrimArray::U16(v) => byte(v.get(i).copied()),
552                PrimArray::I16(v) => byte(v.get(i).copied()),
553                PrimArray::U32(v) => byte(v.get(i).copied()),
554                PrimArray::I32(v) => byte(v.get(i).copied()),
555                PrimArray::U64(v) => byte(v.get(i).copied()),
556                PrimArray::I64(v) => byte(v.get(i).copied()),
557                // Refused by `of` unless empty.
558                PrimArray::F32(_) | PrimArray::F64(_) => Ok(0),
559            },
560            Self::Items(items, name, _) => match items.get(i) {
561                None => Ok(0),
562                Some(Value::Bool(b)) => Ok(u8::from(*b)),
563                Some(Value::Int(v)) => byte(Some(*v)),
564                Some(Value::UInt(v)) => byte(Some(*v)),
565                Some(_) => Err(MeshError::malformed(
566                    format_args!("{name} holds a value that is not an integer"),
567                    self.meter(),
568                )),
569            },
570            Self::Raw(b, _) => Ok(b.get(i).copied().unwrap_or(0)),
571        }
572    }
573
574    /// Item `i` as `m_Data[i]` reads it (`helpers/PackedBitVector.py:56`):
575    /// `None` past the end, where Python raises `IndexError`; a value that
576    /// is no byte, which no typetree's `UInt8` holds, is `Malformed`.
577    pub fn item(&self, i: usize) -> Result<Option<u8>, MeshError> {
578        if i >= self.len() {
579            return Ok(None);
580        }
581        match self.byte(i) {
582            Ok(b) => Ok(Some(b)),
583            Err(MeshError::ByteRange) => Err(MeshError::malformed(
584                format_args!("{}", "m_Data holds a value past a byte"),
585                self.meter(),
586            )),
587            Err(e) => Err(e),
588        }
589    }
590
591    /// Whether Python holds it as `bytes`, whose index error reads "index
592    /// out of range", not a list's.
593    #[must_use]
594    pub fn is_bytes(&self) -> bool {
595        matches!(self, Self::Raw(_, _))
596    }
597
598    /// The bytes themselves, where they need no check (a `U8` run, or
599    /// `bytes`).
600    #[must_use]
601    pub fn as_u8(&self) -> Option<&'a [u8]> {
602        match self {
603            Self::Run(PrimArray::U8(b), _) => Some(b),
604            Self::Raw(b, _) => Some(b),
605            _ => None,
606        }
607    }
608}
609
610fn widen(bits: u32) -> f64 {
611    let value = f32::from_bits(bits);
612    if value.is_nan() {
613        f64::from_bits(
614            (u64::from(bits >> 31) << 63)
615                | 0x7ff0_0000_0000_0000
616                | (u64::from((bits & 0x007f_ffff) | 0x0040_0000) << 29),
617        )
618    } else {
619        f64::from(value)
620    }
621}
622
623#[cfg(test)]
624mod tests {
625    use super::{NAME_BYTES, type_name};
626
627    #[test]
628    fn a_type_name_is_cut_between_escapes() {
629        assert_eq!(type_name(b"Mesh").to_string(), "Mesh");
630        let exact = "x".repeat(NAME_BYTES);
631        assert_eq!(type_name(exact.as_bytes()).to_string(), exact);
632        let long = "y".repeat(1 << 20);
633        assert_eq!(
634            type_name(long.as_bytes()).to_string(),
635            format!("{}…", &long[..NAME_BYTES])
636        );
637        // Each 0xFF escapes to four bytes, `\xff`: sixteen fit.
638        let cut = type_name(&[0xFF; 100]).to_string();
639        assert_eq!(cut, format!("{}…", "\\xff".repeat(NAME_BYTES / 4)));
640        // An escape that would cross the bound is left out whole.
641        let mut ty = vec![b'a'; NAME_BYTES - 2];
642        ty.push(0xFF);
643        assert_eq!(
644            type_name(&ty).to_string(),
645            format!("{}…", "a".repeat(NAME_BYTES - 2))
646        );
647    }
648}