Skip to main content

unityrs_core/version/
mod.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/helpers/UnityVersion.py, UnityPy/files/BundleFile.py, UnityPy/files/SerializedFile.py. See THIRD_PARTY_LICENSES.
2//! Unity versions with UnityPy's semantics, and UnityPy's two version chains.
3//!
4//! `UnityVersion.from_str` (`helpers/UnityVersion.py:62-88`) matches
5//! `^(\d+)\.(\d+)\.(\d+)(.+?)?(\d+)?(.*)$` (`helpers/UnityVersion.py:7-10`)
6//! with Python `re` (DOTALL; `\d` is any Unicode `Nd` digit). The type is one
7//! character (the lazy group takes exactly the non-digit the greedy `build`
8//! group leaves), lower-cased: `a` 0, `b` 1,
9//! `c` 2, `f` 3, `p` 4, `x` 5, anything else 255, nothing at all `f`. The packed
10//! value is `major<<48 | minor<<32 | build<<16 | type<<8 | number`, a plain OR
11//! of unbounded integers, so wide fields spill (`docs/CANONICAL_DUMP.md` 4.2).
12//! Each group goes through Python 3.11's `int()`, which refuses a string of
13//! more than [`PY_INT_MAX_STR_DIGITS`] digits (`sys.get_int_max_str_digits()`,
14//! leading zeros and any `Nd` digit counted): `from_str` then raises
15//! `ValueError`, exactly as for a string that does not match, so both chains
16//! treat it as [`VersionError::NoMatch`] (the bundle chain falls back, the
17//! `SerializedFile` chain fails).
18//!
19//! Chain 1, the bundle (`files/BundleFile.py:523-536`): the engine string; when
20//! it does not parse or its 16-bit major is 0, the fallback; with no fallback,
21//! an error. It decides the flag set (`:113-121`) and the format-6 alignment
22//! (`:129-131`).
23//!
24//! Chain 2, the `SerializedFile` (`files/SerializedFile.py:351-360`): its own
25//! string (format 7 and up); when empty or `0.0.0`, the parent *bundle's*
26//! engine string (a `WebFile` parent does not count); when still empty or
27//! `0.0.0`, the fallback; then `from_str`, which fails on a string that does
28//! not match whatever the fallback holds.
29//!
30//! **No copy.** A version keeps the bytes it was parsed from ([`UnityVersion::raw`]),
31//! and a [`VersionError::NoMatch`] the string that did not match. Both chains
32//! and [`UnityVersion::parse`] take the string as the file's own
33//! [`RawStr`] (a slice of its buffer, or the parent bundle's engine string,
34//! or the policy's fallback) and keep a clone of it, a reference count: a
35//! version string can be up to 32,767 bytes (`read_string_to_null`'s
36//! window) and every parse of an entry keeps its own version, so a copy
37//! would be an uncharged allocation per parse. The one heap a version owns
38//! is a packed integer of 2^128 or more ([`UnityVersion::heap_bytes`]),
39//! which the chains charge, at [`heap_cost`], to the handle charge of the
40//! file that keeps the version before the limbs are allocated.
41//!
42//! **Work.** Every parse of an entry parses its version again (the
43//! `SerializedFile` chain may parse the parent bundle's engine string, which
44//! that parse did not read). So the chains count a parse's work on the
45//! input's meter, as its `DecodeWork` ([`crate::limits::Meter`]), each step
46//! before it runs: the bytes it scans, and [`LIMB_WORK`] for each limb a
47//! step multiplies or merges. A group's digits are taken 19 at a time, each
48//! chunk one multiply over the limbs the value holds so far, and each merge
49//! over the group's own (review round 6 found every step going through all
50//! 226 limbs of a fixed array, uncounted: about 12 limbs a digit, and 2,260
51//! for the ten bytes of `2022.3.0f1`, ten steps of 226). So a group below
52//! 2^128 costs at most three limbs a step, linear in the string (every
53//! version a real file holds); a group of `d` significant digits past that
54//! costs about `d * d / 730` limbs, quadratic as `CPython`'s own `int()` is,
55//! which is why Python caps a group at [`PY_INT_MAX_STR_DIGITS`]: at most
56//! about 6 limbs a digit, under 50 counted a byte of the string (`tests`,
57//! `a_versions_packing_counts_the_limbs_it_holds_as_the_inputs_work`). A
58//! refused step stops the parse, its scanned bytes counted.
59//! [`UnityVersion::parse`], for a caller's own string, counts nothing.
60//!
61//! Owner: package C. The Unicode `Nd` table ([`crate::tables::nd_digit`]) is
62//! generated from the oracle's Python 3.11 (`tools/gen/`, package A).
63
64use std::cmp::Ordering;
65use std::hash::{Hash, Hasher};
66use std::sync::Arc;
67
68use crate::error::Error;
69use crate::limits::{Charge, heap_cost};
70use crate::raw::RawStr;
71
72mod packed;
73mod parse;
74
75pub use packed::Packed;
76pub use parse::{LIMB_WORK, MAX_LIMBS};
77
78/// Python 3.11's `sys.get_int_max_str_digits()`: `int()` refuses a longer
79/// digit string, so a version group longer than this does not parse.
80pub const PY_INT_MAX_STR_DIGITS: usize = 4300;
81
82/// A parsed Unity version: the raw bytes and UnityPy's packed integer.
83#[derive(Clone, Debug)]
84pub struct UnityVersion {
85    raw: RawStr,
86    packed: Packed,
87}
88
89impl UnityVersion {
90    /// `UnityVersion.from_str` on the raw bytes. The pattern is applied to the
91    /// surrogate-escaped string Python sees, so invalid UTF-8 bytes match `.`
92    /// and never `\d`; a group of more than [`PY_INT_MAX_STR_DIGITS`] digits
93    /// is [`VersionError::NoMatch`] (module docs). The version, or the
94    /// `NoMatch`, keeps a clone of `raw` (no copy: module docs). Its work is
95    /// counted nowhere: this is for a caller's own string; an input's are
96    /// parsed by the chains, which count it (module docs, "Work").
97    pub fn parse(raw: &RawStr) -> Result<Self, VersionError> {
98        match parse::parse_packed(raw.as_bytes(), parse::Work::new(None)) {
99            Ok(Some(packed)) => Ok(Self {
100                raw: raw.clone(),
101                packed,
102            }),
103            // Uncounted and uncharged, the parse is never refused.
104            Ok(None) | Err(_) => Err(VersionError::NoMatch(raw.clone())),
105        }
106    }
107
108    /// [`Self::parse`] of an input's string, its work counted on `charge`'s
109    /// meter (the input's) before each step runs, and a packed integer of
110    /// 2^128 or more charged to `charge` before its limbs are allocated
111    /// (module docs, "Work"). The outer error is the meter's refusal
112    /// ([`crate::LimitKind::DecodeWork`], or the charge's).
113    pub(crate) fn parse_charged(
114        raw: &RawStr,
115        charge: &mut Charge,
116    ) -> Result<Result<Self, VersionError>, Error> {
117        Ok(
118            match parse::parse_packed(raw.as_bytes(), parse::Work::new(Some(charge)))? {
119                Some(packed) => Ok(Self {
120                    raw: raw.clone(),
121                    packed,
122                }),
123                None => Err(VersionError::NoMatch(raw.clone())),
124            },
125        )
126    }
127
128    /// `UnityVersion(int)`: a version from a packed integer, as a TPK stores
129    /// its versions (`helpers/Tpk.py:464`). It has no raw string (`raw()` is
130    /// empty). Implemented by the scaffold, so `unityrs-tpk` (package A) can
131    /// pick a TPK entry by core's ordering before package C lands.
132    #[must_use]
133    pub fn from_packed(packed: u64) -> Self {
134        Self {
135            raw: RawStr::default(),
136            packed: Packed::from_u128(u128::from(packed)),
137        }
138    }
139
140    /// The bytes it was parsed from.
141    pub fn raw(&self) -> &RawStr {
142        &self.raw
143    }
144
145    /// The packed integer, exactly.
146    pub fn packed(&self) -> &Packed {
147        &self.packed
148    }
149
150    /// The heap this version owns: a packed integer of 2^128 or more's
151    /// limbs. The raw string is a shared slice and owns none. Implemented
152    /// by the scaffold; the chains charge it, at [`heap_cost`], to the
153    /// handle of the file that keeps it.
154    #[must_use]
155    pub fn heap_bytes(&self) -> usize {
156        self.packed.heap_bytes()
157    }
158
159    /// What its heap is charged at: the limbs' block, at [`heap_cost`].
160    fn heap_charge(&self) -> u64 {
161        match self.heap_bytes() {
162            0 => 0,
163            n => heap_cost(u64::try_from(n).unwrap_or(u64::MAX)),
164        }
165    }
166
167    /// The packed value when it fits `u64` (TPK lookups compare these).
168    /// Implemented by the scaffold.
169    pub fn packed_u64(&self) -> Option<u64> {
170        self.packed.as_u128().and_then(|v| u64::try_from(v).ok())
171    }
172
173    /// `(major, minor, build, type, number)`, each cut to its slot (16, 16, 16,
174    /// 8 and 8 bits). A type byte other than 0-5 and 255 raises, as
175    /// `UnityVersionType(...)` does (`UnityVersion.py:41-42`, `:109-110`).
176    pub fn as_tuple(&self) -> Result<(u16, u16, u16, u8, u8), VersionError> {
177        // UnityPy helpers/UnityVersion.py:28-54, :109-110
178        let ty = u8::try_from(self.packed.bits(8, 8)).unwrap_or(u8::MAX);
179        if !(ty <= 5 || ty == 255) {
180            return Err(VersionError::TypeByte(ty));
181        }
182        let field = |shift: u32| u16::try_from(self.packed.bits(shift, 16)).unwrap_or(u16::MAX);
183        Ok((
184            field(48),
185            field(32),
186            field(16),
187            ty,
188            u8::try_from(self.packed.bits(0, 8)).unwrap_or(u8::MAX),
189        ))
190    }
191
192    /// The 16-bit major, as UnityPy's `major` property cuts it.
193    #[must_use]
194    pub fn major(&self) -> u16 {
195        // UnityPy helpers/UnityVersion.py:28-30
196        u16::try_from(self.packed.bits(48, 16)).unwrap_or(u16::MAX)
197    }
198
199    /// `self < other` as Python compares `as_tuple()` with a shorter tuple
200    /// (`version < (2020, 3, 34)`).
201    pub fn lt_tuple(&self, other: &[u16]) -> Result<bool, VersionError> {
202        // UnityPy helpers/UnityVersion.py:122-127: tuple order, a shorter
203        // tuple that is a prefix being the smaller.
204        let (major, minor, build, ty, number) = self.as_tuple()?;
205        let mine = [major, minor, build, u16::from(ty), u16::from(number)];
206        Ok(mine.as_slice() < other)
207    }
208}
209
210impl PartialEq for UnityVersion {
211    /// Equality is on the packed integer, as Python's `int` equality.
212    fn eq(&self, other: &Self) -> bool {
213        self.packed == other.packed
214    }
215}
216
217impl Eq for UnityVersion {}
218
219impl Hash for UnityVersion {
220    fn hash<H: Hasher>(&self, state: &mut H) {
221        self.packed.hash(state);
222    }
223}
224
225impl Ord for UnityVersion {
226    /// As Python compares the `int`s (`Tpk.py:472-481`'s `exactVersion >= version`).
227    fn cmp(&self, other: &Self) -> Ordering {
228        self.packed.cmp(&other.packed)
229    }
230}
231
232impl PartialOrd for UnityVersion {
233    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
234        Some(self.cmp(other))
235    }
236}
237
238/// Why a version is what it is.
239#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
240pub enum VersionSource {
241    /// The file's own string.
242    Own,
243    /// The parent bundle's engine string (chain 2 only).
244    ParentBundle,
245    /// `config.FALLBACK_UNITY_VERSION`.
246    Fallback,
247    /// An opt-in override, never silent: reported in the API, the batch
248    /// manifest and the dump's `producer`.
249    Forced,
250}
251
252/// A chain's result.
253#[derive(Clone, Debug, PartialEq, Eq)]
254pub struct ResolvedVersion {
255    /// The version.
256    pub version: UnityVersion,
257    /// Where it came from.
258    pub source: VersionSource,
259}
260
261/// The fallback and the overrides.
262#[derive(Clone, Debug, Default)]
263#[non_exhaustive]
264pub struct VersionPolicy {
265    /// UnityPy's `config.FALLBACK_UNITY_VERSION`, as a string (UnityPy parses it
266    /// each time it is used; a bad string fails there). `None` raises where
267    /// UnityPy raises (`config.py:25-32`); the oracle leaves it unset.
268    pub fallback: Option<RawStr>,
269    /// Shared warning filter/emitter for `config.get_fallback_version`.
270    /// Bindings install their Python warning emitter; native callers may opt
271    /// into collecting warnings. Called before parsing the fallback string.
272    pub fallback_warnings: Option<Arc<dyn crate::config::FallbackWarningSink>>,
273    /// Replaces chain 1's result.
274    pub force_bundle: Option<UnityVersion>,
275    /// Replaces chain 2's result.
276    pub force_serialized: Option<UnityVersion>,
277}
278
279/// UnityPy's choice between `ArchiveFlags` and `ArchiveFlagsOld`.
280#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
281pub enum FlagsClass {
282    /// `ArchiveFlags`.
283    New,
284    /// `ArchiveFlagsOld`.
285    Old,
286}
287
288/// Version failures.
289#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
290#[non_exhaustive]
291pub enum VersionError {
292    /// The string does not match the pattern.
293    #[error("invalid version string {0}")]
294    NoMatch(RawStr),
295    /// A type byte outside 0-5 and 255 in a comparison.
296    #[error("invalid version type byte {0}")]
297    TypeByte(u8),
298    /// No usable version and no fallback set.
299    #[error(
300        "No valid Unity version found, and the fallback version is not correctly configured. Please explicitly set the value of UnityPy.config.FALLBACK_UNITY_VERSION."
301    )]
302    NoFallback,
303}
304
305/// Chain 1: `BundleFile.parse_version`. `engine` is the header's
306/// `version_engine`, kept by the result without a copy (module docs). Each
307/// parse's work is counted on `charge`'s meter, the input's, and the
308/// result's heap is charged to `charge`, the handle charge of the bundle
309/// that keeps it, before it is allocated (module docs, "Work"): the error
310/// is a [`VersionError`] or such a refusal.
311pub fn resolve_bundle(
312    engine: &RawStr,
313    policy: &VersionPolicy,
314    charge: &mut Charge,
315) -> Result<ResolvedVersion, Error> {
316    if let Some(v) = &policy.force_bundle {
317        return forced(v, charge);
318    }
319    // UnityPy files/BundleFile.py:523-536: a string that does not parse, or
320    // whose 16-bit major is 0, takes the fallback.
321    match UnityVersion::parse_charged(engine, charge)? {
322        Ok(version) if version.major() != 0 => {
323            return Ok(ResolvedVersion {
324                version,
325                source: VersionSource::Own,
326            });
327        }
328        Ok(dropped) => charge.release(dropped.heap_charge()),
329        Err(_) => {}
330    }
331    fallback(policy, charge, true)
332}
333
334/// A forced version, its heap charged before the copy.
335fn forced(v: &UnityVersion, charge: &mut Charge) -> Result<ResolvedVersion, Error> {
336    charge.grow(v.heap_charge())?;
337    Ok(ResolvedVersion {
338        version: v.clone(),
339        source: VersionSource::Forced,
340    })
341}
342
343/// `UnityVersion.from_str(config.get_fallback_version())` (`config.py:25-32`):
344/// no fallback raises; a fallback that does not match raises too.
345fn fallback(
346    policy: &VersionPolicy,
347    charge: &mut Charge,
348    bundle: bool,
349) -> Result<ResolvedVersion, Error> {
350    let s = policy.fallback.as_ref().ok_or(VersionError::NoFallback)?;
351    let s = policy.fallback_warnings.as_ref().map_or_else(
352        || Ok(s.clone()),
353        |warnings| warnings.warn_value_at(s, bundle),
354    )?;
355    Ok(ResolvedVersion {
356        version: UnityVersion::parse_charged(&s, charge)??,
357        source: VersionSource::Fallback,
358    })
359}
360
361/// `not s or s == "0.0.0"` (`SerializedFile.py:353`, `:358`).
362fn unusable(s: &RawStr) -> bool {
363    s.is_empty() || s.as_bytes() == b"0.0.0"
364}
365
366/// Chain 2: `SerializedFile.set_version`. `own` is the file's string (format
367/// 7 and up); `parent_engine` is `Some` only when the parent is a bundle
368/// (its header's `version_engine`). The string the chain picks is kept by
369/// the result without a copy (module docs). The parse's work and the
370/// result's heap go to `charge`, as [`resolve_bundle`]'s do.
371pub fn resolve_serialized(
372    own: &RawStr,
373    parent_engine: Option<&RawStr>,
374    policy: &VersionPolicy,
375    charge: &mut Charge,
376) -> Result<ResolvedVersion, Error> {
377    if let Some(v) = &policy.force_serialized {
378        return forced(v, charge);
379    }
380    // UnityPy files/SerializedFile.py:351-360
381    let (mut s, mut source) = (own, VersionSource::Own);
382    if unusable(s) {
383        if let Some(parent) = parent_engine {
384            (s, source) = (parent, VersionSource::ParentBundle);
385        }
386        if unusable(s) {
387            return fallback(policy, charge, false);
388        }
389    }
390    Ok(ResolvedVersion {
391        version: UnityVersion::parse_charged(s, charge)??,
392        source,
393    })
394}
395
396/// `files/BundleFile.py:113-121`: `ArchiveFlagsOld` below 2020, and below 2020.3.34,
397/// 2021.3.2 and 2022.1.1 on those lines.
398pub fn flags_class(engine: &UnityVersion) -> Result<FlagsClass, VersionError> {
399    // UnityPy files/BundleFile.py:113-121; `version[0]` is `as_tuple()[0]`,
400    // which raises as the comparison before it does.
401    let v = engine;
402    let major = v.as_tuple()?.0;
403    let old = v.lt_tuple(&[2020])?
404        || (major == 2020 && v.lt_tuple(&[2020, 3, 34])?)
405        || (major == 2021 && v.lt_tuple(&[2021, 3, 2])?)
406        || (major == 2022 && v.lt_tuple(&[2022, 1, 1])?);
407    Ok(if old {
408        FlagsClass::Old
409    } else {
410        FlagsClass::New
411    })
412}
413
414/// `files/BundleFile.py:129-131`: the 16-byte alignment after the header applies at
415/// format 7 and up, or with a 2019 engine at 2019.4.15 or later.
416pub fn uses_block_alignment(format: u32, engine: &UnityVersion) -> Result<bool, VersionError> {
417    // UnityPy files/BundleFile.py:129: `or` short-circuits, so from format 7
418    // the version is never compared.
419    if format >= 7 {
420        return Ok(true);
421    }
422    Ok(engine.as_tuple()?.0 == 2019 && !engine.lt_tuple(&[2019, 4, 15])?)
423}
424
425#[cfg(test)]
426mod tests;