unityrs-core 1.0.0

Read and write Unity asset bundles, serialized files and typetrees.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
// Ported from UnityPy 1.25.2 (MIT): UnityPy/helpers/ImportHelper.py, UnityPy/files/File.py. See THIRD_PARTY_LICENSES.
//! Files: what `ImportHelper.parse_file` builds (`helpers/ImportHelper.py:127-156`).
//!
//! A [`File`] is a handle (`Arc`) on an immutable, parsed file. Containers
//! decode lazily and parse each entry once ([`BundleFile::entry`]); the
//! UnityPy load order, where every entry is parsed and a failing entry fails
//! the bundle, is [`BundleFile::load_all`].
//!
//! **Memory.** Every file charges its input's [`Meter`] for itself and for
//! every table it keeps, before it allocates them (plan section 3.15): a
//! top-level load makes the meter and passes it to [`parse_file`], and a
//! container passes its own to each entry it parses, so one input's files
//! share one bound however many there are. Each file keeps its [`Charge`]
//! (the bytes return when the file drops) and answers [`File::meter`].
//!
//! Owner: package C.

pub mod bundle;
pub(crate) mod cab;
pub use cab::WriteableCab;
mod changed;
pub mod save;
pub mod serialized;
pub use save::{SaveError, SaveLayout, SaveOptions};
mod teardown;
pub mod web;

use std::sync::{Arc, OnceLock, Weak};

use bytes::Bytes;

pub use bundle::{
    BlockInfo, BundleCounts, BundleFile, BundleHeader, BundlePacker, BundleSaveOptions, DirEntry,
    FileSlot, LayoutKind,
};
pub use serialized::{
    External, ObjectInfo, ScriptRef, SerializedFile, SerializedHeader, SerializedType,
};
pub use web::{WebFile, WebPacker, WebSaveOptions};

use crate::detect::{FileType, ParsedAs, check_entry_type, parsed_as, probe_container};
use crate::error::{Error, LimitError, LimitKind, Unsupported};
use crate::limits::{Charge, ChargeError, Meter, MeteredVec, heap_cost};
use crate::options::FileContext;
use crate::raw::RawStr;
use crate::stream::ReaderKind;

/// A parsed file.
#[derive(Clone, Debug)]
pub enum File {
    /// An `AssetsFile` that is not raw by the name rule.
    Serialized(Arc<SerializedFile>),
    /// A bundle.
    Bundle(Arc<BundleFile>),
    /// A WebFile.
    Web(Arc<WebFile>),
    /// What UnityPy keeps as a reader: resources, name-rule files, zip entries.
    Raw(Arc<RawFile>),
}

impl File {
    pub(crate) fn mark_dependency_root(&self) {
        self.set_dependency_path(MeteredVec::new(self.meter()));
    }

    fn set_dependency_path(&self, path: MeteredVec<usize>) {
        let identity = match self {
            Self::Serialized(file) => &file.dependency_path,
            Self::Bundle(file) => &file.dependency_path,
            Self::Web(file) => &file.dependency_path,
            Self::Raw(_) => return,
        };
        let set = identity.0.set(path);
        debug_assert!(set.is_ok());
    }
    /// A container's loaded ordered files dict, or an empty slice for a leaf.
    /// New resource writers are exposed by the container's `writeable_cabs`.
    #[must_use]
    pub fn container_files(&self) -> &[FileSlot] {
        match self {
            Self::Bundle(b) => b.files(),
            Self::Web(w) => w.files(),
            _ => &[],
        }
    }
    /// All container rows in original order, including duplicate names.
    #[must_use]
    pub fn container_directory(&self) -> &[DirEntry] {
        match self {
            Self::Bundle(b) => b.directory(),
            Self::Web(w) => w.directory(),
            _ => &[],
        }
    }
    /// Parse a container row. Leaf files have no rows.
    pub fn container_entry(&self, i: usize) -> Result<File, Error> {
        match self {
            Self::Bundle(b) => b.entry(i),
            Self::Web(w) => w.entry(i),
            _ => Err(Error::Malformed {
                what: "container entry",
                detail: "leaf file".into(),
            }),
        }
    }
    /// Open a child container, leaving serialized and raw entries lazy.
    /// A leaf still occupies its directory position in a file walk. Probe
    /// read failures and resource refusals are returned.
    pub fn child_container(&self, i: usize) -> Result<Option<Self>, Error> {
        if let Some(file) = self.parsed_container_entry(i) {
            return Ok(matches!(file, Self::Bundle(_) | Self::Web(_)).then(|| file.clone()));
        }
        let container = match self {
            Self::Bundle(bundle) => crate::env::registry::probe_bundle_entry(bundle, i)?,
            Self::Web(web) => probe_container(check_entry_type(
                &web.entry_bytes(i)?,
                &web.context().limits,
                web.meter(),
            ))?,
            _ => false,
        };
        if container {
            self.container_entry(i).map(Some)
        } else {
            Ok(None)
        }
    }

    /// The meter of the input this file belongs to.
    #[must_use]
    pub fn meter(&self) -> &Arc<Meter> {
        match self {
            Self::Serialized(f) => f.meter(),
            Self::Bundle(f) => f.meter(),
            Self::Web(f) => f.meter(),
            Self::Raw(f) => f.meter(),
        }
    }

    pub(crate) fn parsed_container_entry(&self, i: usize) -> Option<&Self> {
        let entries = match self {
            Self::Bundle(b) => &b.entries,
            Self::Web(w) => &w.entries,
            _ => return None,
        };
        entries.get(i)?.get()?.as_ref().ok()
    }

    /// What `check_file_type` called the bytes [`parse_file`] built this
    /// from, kept so a caller never detects them again (a gzip entry's
    /// detection inflates it): each kind but a reader has one type, and a
    /// reader keeps its own ([`RawFile::file_type`]).
    #[must_use]
    pub fn file_type(&self) -> FileType {
        match self {
            Self::Serialized(_) => FileType::AssetsFile,
            Self::Bundle(_) => FileType::BundleFile,
            Self::Web(_) => FileType::WebFile,
            Self::Raw(f) => f.file_type(),
        }
    }
}

/// Directory indices within a dependency source. The location survives a
/// reopen without holding any of the parent containers alive.
#[derive(Default)]
struct DependencyPath(OnceLock<MeteredVec<usize>>);

impl DependencyPath {
    fn parse_child(
        &self,
        meter: &Arc<Meter>,
        index: usize,
        parse: impl FnOnce() -> Result<File, Error>,
    ) -> Result<File, Error> {
        let Some(parent) = self.0.get() else {
            return parse();
        };
        let file = parse()?;
        if matches!(file, File::Raw(_)) {
            return Ok(file);
        }
        meter.count_decode(parent.len() as u64 + 1)?;
        let mut path = MeteredVec::with_capacity(meter, parent.len().saturating_add(1))?;
        path.extend_from_slice(parent.as_slice())?;
        path.push(index)?;
        file.set_dependency_path(path);
        Ok(file)
    }
}

/// A file UnityPy keeps as a reader.
#[derive(Debug)]
pub struct RawFile {
    /// The name it was loaded under.
    pub name: RawStr,
    /// Its bytes (a slice of the parent's buffer for an entry).
    pub data: Bytes,
    /// What `check_file_type` called `data`: `ResourceFile`, a zip entry's
    /// `Zip`, or an `AssetsFile` the name rule keeps as a reader.
    ty: FileType,
    /// The reader it is: a resource read from it follows its rules.
    reader: ReaderKind,
    /// The handle's own allocation, charged to the input.
    charge: Charge,
}

impl RawFile {
    /// A raw file of `data` under `name`, which `check_file_type` called
    /// `ty`, its allocation charged to `meter` first (`data` is a slice of a
    /// buffer already charged, or the caller's). A memory reader, as UnityPy
    /// keeps bytes and every entry of a container.
    pub fn new(
        name: RawStr,
        data: Bytes,
        ty: FileType,
        meter: &Arc<Meter>,
    ) -> Result<Arc<Self>, ChargeError> {
        Self::with_reader(name, data, ty, meter, ReaderKind::Memory)
    }

    /// [`Self::new`] as the reader `reader` ([`ReaderKind::Stream`] for a
    /// top-level file loaded from a path).
    pub fn with_reader(
        name: RawStr,
        data: Bytes,
        ty: FileType,
        meter: &Arc<Meter>,
        reader: ReaderKind,
    ) -> Result<Arc<Self>, ChargeError> {
        let charge = meter.charge(heap_cost(
            u64::try_from(std::mem::size_of::<Self>() + 16).unwrap_or(u64::MAX),
        ))?;
        Ok(Arc::new(Self {
            name,
            data,
            ty,
            reader,
            charge,
        }))
    }

    /// The reader UnityPy keeps it as, whose rules a resource read from it
    /// follows (`ResourceReader._get_resource_data`).
    #[must_use]
    pub fn reader_kind(&self) -> ReaderKind {
        self.reader
    }

    /// The meter of the input it belongs to.
    #[must_use]
    pub fn meter(&self) -> &Arc<Meter> {
        self.charge.meter()
    }

    /// What `check_file_type` called its bytes.
    #[must_use]
    pub fn file_type(&self) -> FileType {
        self.ty
    }
}

/// What a child knows of its container. A file loaded at top level has none
/// (`parent: None`): UnityPy makes the `Environment` that loaded it its
/// parent (`environment.py:154`), which is the container `PPtr.deref` scans
/// (plan section 3.13, rule 4). The input's meter travels separately, as
/// every file's [`File::meter`], top-level ones included.
#[derive(Clone, Debug)]
pub struct Parent {
    /// The container's name.
    pub name: RawStr,
    /// The container's kind.
    pub kind: ParentKind,
    /// How deep the child is: 1 for an entry of a top-level container. A
    /// container at [`crate::limits::Limits::max_container_depth`] refuses to
    /// parse an entry that is itself a container (`LimitKind::ContainerDepth`).
    pub depth: u32,
    /// The length of the buffer the child's bytes are a slice of, which any
    /// slice of them keeps alive: the container's decoded run that holds
    /// them, or, for stored blocks, the buffer of the container's own bytes
    /// (its own `pinned`). Never less than the child's own length, which is
    /// what a container that does not know it gives. A value read from the
    /// child copies its slices out when they would keep much more than
    /// themselves alive ([`crate::pin`]; plan section 8, R3).
    pub pinned: u64,
}

/// A container kind, as the `SerializedFile` version chain and `PPtr.deref`
/// distinguish them.
#[derive(Clone, Debug)]
pub enum ParentKind {
    /// A `BundleFile`, whose raw engine string chain 2 may take. Its fields
    /// may grow (P1b's sprites kind added `dir_index`), so a caller outside
    /// the core matches it with `..` and cannot build one.
    #[non_exhaustive]
    Bundle {
        /// `version_engine`, as read.
        version_engine: RawStr,
        /// The bundle, for `PPtr.deref`'s scan of its `files` dict (rule 5):
        /// weak, since the bundle holds its entries (`Arc::new_cyclic` at open).
        bundle: Weak<BundleFile>,
        /// The directory row the child was opened from
        /// ([`BundleFile::entry`]'s `dir_index`): of two rows of one path,
        /// the child knows which it is, where `files()` names only the last.
        dir_index: usize,
    },
    /// A `WebFile`, which gives no version.
    Web {
        /// The WebFile whose files dict is scanned for siblings.
        web: Weak<WebFile>,
    },
}

/// `parse_file`: builds the file `ty` says, under the name rule
/// ([`crate::detect::parsed_as`]), from bytes (UnityPy's memory reader). A
/// file with a `parent` is an entry. Everything it keeps is charged to
/// `meter`, the input's.
pub fn parse_file(
    name: RawStr,
    data: Bytes,
    ty: FileType,
    parent: Option<Parent>,
    meter: &Arc<Meter>,
    ctx: &Arc<FileContext>,
) -> Result<File, Error> {
    parse_file_with_reader(name, data, ty, parent, meter, ctx, ReaderKind::Memory)
}

/// [`parse_file`] by the rules of the reader UnityPy reads the file with:
/// [`ReaderKind::Stream`] for a top-level file loaded from a path
/// (`environment.py:136-139`; [`crate::env::Source::Path`]), whose
/// `SerializedFile`, bundle header or kept reader follows them. A
/// container's entries are memory whatever its reader. WebFile members use memory readers after inflation.
pub fn parse_file_with_reader(
    name: RawStr,
    data: Bytes,
    ty: FileType,
    parent: Option<Parent>,
    meter: &Arc<Meter>,
    ctx: &Arc<FileContext>,
    reader: ReaderKind,
) -> Result<File, Error> {
    parse_file_at_depth(name, data, ty, parent, meter, ctx, reader, 0)
}

/// Parse a source nested inside ZIPs without giving it a fictitious bundle
/// parent. ZIP members are Environment files, but their container depth still
/// contributes to bundles opened from them and those bundles' descendants.
#[allow(
    clippy::too_many_arguments,
    reason = "internal reader API plus independent ZIP depth"
)]
pub(crate) fn parse_file_at_depth(
    name: RawStr,
    data: Bytes,
    ty: FileType,
    parent: Option<Parent>,
    meter: &Arc<Meter>,
    ctx: &Arc<FileContext>,
    reader: ReaderKind,
    source_depth: u32,
) -> Result<File, Error> {
    parse_file_with_state(
        name,
        data,
        ty,
        parent,
        meter,
        ctx,
        reader,
        source_depth,
        &mut None,
    )
}

/// Parse with the endian assignment made to the constructor's input reader,
/// including when construction fails. Inflated readers do not change it.
#[allow(clippy::too_many_arguments)]
pub(crate) fn parse_file_with_state(
    name: RawStr,
    data: Bytes,
    ty: FileType,
    parent: Option<Parent>,
    meter: &Arc<Meter>,
    ctx: &Arc<FileContext>,
    reader: ReaderKind,
    source_depth: u32,
    endian: &mut Option<crate::stream::Endian>,
) -> Result<File, Error> {
    // UnityPy helpers/ImportHelper.py:127-156; a zip input is refused (P3).
    let kind = parsed_as(ty, name.as_bytes(), parent.is_some());
    if matches!(kind, ParsedAs::BundleFile | ParsedAs::WebFile)
        && parent.as_ref().map_or(source_depth, |p| p.depth) > ctx.limits.max_container_depth
    {
        return Err(Error::Limit(LimitError::refused(
            LimitKind::ContainerDepth,
            u64::from(parent.as_ref().map_or(source_depth, |p| p.depth)),
            u64::from(ctx.limits.max_container_depth),
        )));
    }
    Ok(match kind {
        ParsedAs::SerializedFile => File::Serialized(SerializedFile::parse_with_state(
            name, data, parent, meter, ctx, reader, endian,
        )?),
        ParsedAs::BundleFile => File::Bundle(BundleFile::open_at_depth(
            name,
            data,
            parent,
            meter,
            ctx,
            reader,
            source_depth,
        )?),
        ParsedAs::WebFile => File::Web(WebFile::open_with_state(
            name,
            data,
            parent,
            meter,
            ctx,
            reader,
            source_depth,
            endian,
        )?),
        ParsedAs::Zip => return Err(Error::Unsupported(Unsupported::Zip)),
        ParsedAs::Raw | ParsedAs::Error => {
            File::Raw(RawFile::with_reader(name, data, ty, meter, reader)?)
        }
    })
}