Expand description
Unity versions with UnityPy’s semantics, and UnityPy’s two version chains.
UnityVersion.from_str (helpers/UnityVersion.py:62-88) matches
^(\d+)\.(\d+)\.(\d+)(.+?)?(\d+)?(.*)$ (helpers/UnityVersion.py:7-10)
with Python re (DOTALL; \d is any Unicode Nd digit). The type is one
character (the lazy group takes exactly the non-digit the greedy build
group leaves), lower-cased: a 0, b 1,
c 2, f 3, p 4, x 5, anything else 255, nothing at all f. The packed
value is major<<48 | minor<<32 | build<<16 | type<<8 | number, a plain OR
of unbounded integers, so wide fields spill (docs/CANONICAL_DUMP.md 4.2).
Each group goes through Python 3.11’s int(), which refuses a string of
more than PY_INT_MAX_STR_DIGITS digits (sys.get_int_max_str_digits(),
leading zeros and any Nd digit counted): from_str then raises
ValueError, exactly as for a string that does not match, so both chains
treat it as VersionError::NoMatch (the bundle chain falls back, the
SerializedFile chain fails).
Chain 1, the bundle (files/BundleFile.py:523-536): the engine string; when
it does not parse or its 16-bit major is 0, the fallback; with no fallback,
an error. It decides the flag set (:113-121) and the format-6 alignment
(:129-131).
Chain 2, the SerializedFile (files/SerializedFile.py:351-360): its own
string (format 7 and up); when empty or 0.0.0, the parent bundle’s
engine string (a WebFile parent does not count); when still empty or
0.0.0, the fallback; then from_str, which fails on a string that does
not match whatever the fallback holds.
No copy. A version keeps the bytes it was parsed from (UnityVersion::raw),
and a VersionError::NoMatch the string that did not match. Both chains
and UnityVersion::parse take the string as the file’s own
RawStr (a slice of its buffer, or the parent bundle’s engine string,
or the policy’s fallback) and keep a clone of it, a reference count: a
version string can be up to 32,767 bytes (read_string_to_null’s
window) and every parse of an entry keeps its own version, so a copy
would be an uncharged allocation per parse. The one heap a version owns
is a packed integer of 2^128 or more (UnityVersion::heap_bytes),
which the chains charge, at heap_cost, to the handle charge of the
file that keeps the version before the limbs are allocated.
Work. Every parse of an entry parses its version again (the
SerializedFile chain may parse the parent bundle’s engine string, which
that parse did not read). So the chains count a parse’s work on the
input’s meter, as its DecodeWork (crate::limits::Meter), each step
before it runs: the bytes it scans, and LIMB_WORK for each limb a
step multiplies or merges. A group’s digits are taken 19 at a time, each
chunk one multiply over the limbs the value holds so far, and each merge
over the group’s own (review round 6 found every step going through all
226 limbs of a fixed array, uncounted: about 12 limbs a digit, and 2,260
for the ten bytes of 2022.3.0f1, ten steps of 226). So a group below
2^128 costs at most three limbs a step, linear in the string (every
version a real file holds); a group of d significant digits past that
costs about d * d / 730 limbs, quadratic as CPython’s own int() is,
which is why Python caps a group at PY_INT_MAX_STR_DIGITS: at most
about 6 limbs a digit, under 50 counted a byte of the string (tests,
a_versions_packing_counts_the_limbs_it_holds_as_the_inputs_work). A
refused step stops the parse, its scanned bytes counted.
UnityVersion::parse, for a caller’s own string, counts nothing.
Owner: package C. The Unicode Nd table (crate::tables::nd_digit) is
generated from the oracle’s Python 3.11 (tools/gen/, package A).
Structs§
- Packed
- The packed integer, exactly. Most versions fit
u128; a major of 2^80 or more does not, and the canonical dump writes the exact integer. Ordered, compared and hashed as Python’sint(implemented by the scaffold). - Resolved
Version - A chain’s result.
- Unity
Version - A parsed Unity version: the raw bytes and UnityPy’s packed integer.
- Version
Policy - The fallback and the overrides.
Enums§
- Flags
Class - UnityPy’s choice between
ArchiveFlagsandArchiveFlagsOld. - Version
Error - Version failures.
- Version
Source - Why a version is what it is.
Constants§
- LIMB_
WORK - The work counted for each limb a step multiplies or merges: a limb’s 8 bytes, as a bundle read counts 8 bytes a step (and as the dump counts each limb its decimal conversion divides).
- MAX_
LIMBS - The most limbs a packed version a parse makes holds
(
super::Packed::big_limbs): every step stays within the 226-limb scratch it packs in, so a writer can convert any input’s version in a scratch of its own of this size (unityrs_dump::json::write_packed). - PY_
INT_ MAX_ STR_ DIGITS - Python 3.11’s
sys.get_int_max_str_digits():int()refuses a longer digit string, so a version group longer than this does not parse.
Functions§
- flags_
class files/BundleFile.py:113-121:ArchiveFlagsOldbelow 2020, and below 2020.3.34, 2021.3.2 and 2022.1.1 on those lines.- resolve_
bundle - Chain 1:
BundleFile.parse_version.engineis the header’sversion_engine, kept by the result without a copy (module docs). Each parse’s work is counted oncharge’s meter, the input’s, and the result’s heap is charged tocharge, the handle charge of the bundle that keeps it, before it is allocated (module docs, “Work”): the error is aVersionErroror such a refusal. - resolve_
serialized - Chain 2:
SerializedFile.set_version.ownis the file’s string (format 7 and up);parent_engineisSomeonly when the parent is a bundle (its header’sversion_engine). The string the chain picks is kept by the result without a copy (module docs). The parse’s work and the result’s heap go tocharge, asresolve_bundle’s do. - uses_
block_ alignment files/BundleFile.py:129-131: the 16-byte alignment after the header applies at format 7 and up, or with a 2019 engine at 2019.4.15 or later.