Skip to main content

unityrs_core/files/
mod.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/helpers/ImportHelper.py, UnityPy/files/File.py. See THIRD_PARTY_LICENSES.
2//! Files: what `ImportHelper.parse_file` builds (`helpers/ImportHelper.py:127-156`).
3//!
4//! A [`File`] is a handle (`Arc`) on an immutable, parsed file. Containers
5//! decode lazily and parse each entry once ([`BundleFile::entry`]); the
6//! UnityPy load order, where every entry is parsed and a failing entry fails
7//! the bundle, is [`BundleFile::load_all`].
8//!
9//! **Memory.** Every file charges its input's [`Meter`] for itself and for
10//! every table it keeps, before it allocates them (plan section 3.15): a
11//! top-level load makes the meter and passes it to [`parse_file`], and a
12//! container passes its own to each entry it parses, so one input's files
13//! share one bound however many there are. Each file keeps its [`Charge`]
14//! (the bytes return when the file drops) and answers [`File::meter`].
15//!
16//! Owner: package C.
17
18pub mod bundle;
19pub(crate) mod cab;
20pub use cab::WriteableCab;
21mod changed;
22pub mod save;
23pub mod serialized;
24pub use save::{SaveError, SaveLayout, SaveOptions};
25mod teardown;
26pub mod web;
27
28use std::sync::{Arc, OnceLock, Weak};
29
30use bytes::Bytes;
31
32pub use bundle::{
33    BlockInfo, BundleCounts, BundleFile, BundleHeader, BundlePacker, BundleSaveOptions, DirEntry,
34    FileSlot, LayoutKind,
35};
36pub use serialized::{
37    External, ObjectInfo, ScriptRef, SerializedFile, SerializedHeader, SerializedType,
38};
39pub use web::{WebFile, WebPacker, WebSaveOptions};
40
41use crate::detect::{FileType, ParsedAs, check_entry_type, parsed_as, probe_container};
42use crate::error::{Error, LimitError, LimitKind, Unsupported};
43use crate::limits::{Charge, ChargeError, Meter, MeteredVec, heap_cost};
44use crate::options::FileContext;
45use crate::raw::RawStr;
46use crate::stream::ReaderKind;
47
48/// A parsed file.
49#[derive(Clone, Debug)]
50pub enum File {
51    /// An `AssetsFile` that is not raw by the name rule.
52    Serialized(Arc<SerializedFile>),
53    /// A bundle.
54    Bundle(Arc<BundleFile>),
55    /// A WebFile.
56    Web(Arc<WebFile>),
57    /// What UnityPy keeps as a reader: resources, name-rule files, zip entries.
58    Raw(Arc<RawFile>),
59}
60
61impl File {
62    pub(crate) fn mark_dependency_root(&self) {
63        self.set_dependency_path(MeteredVec::new(self.meter()));
64    }
65
66    fn set_dependency_path(&self, path: MeteredVec<usize>) {
67        let identity = match self {
68            Self::Serialized(file) => &file.dependency_path,
69            Self::Bundle(file) => &file.dependency_path,
70            Self::Web(file) => &file.dependency_path,
71            Self::Raw(_) => return,
72        };
73        let set = identity.0.set(path);
74        debug_assert!(set.is_ok());
75    }
76    /// A container's loaded ordered files dict, or an empty slice for a leaf.
77    /// New resource writers are exposed by the container's `writeable_cabs`.
78    #[must_use]
79    pub fn container_files(&self) -> &[FileSlot] {
80        match self {
81            Self::Bundle(b) => b.files(),
82            Self::Web(w) => w.files(),
83            _ => &[],
84        }
85    }
86    /// All container rows in original order, including duplicate names.
87    #[must_use]
88    pub fn container_directory(&self) -> &[DirEntry] {
89        match self {
90            Self::Bundle(b) => b.directory(),
91            Self::Web(w) => w.directory(),
92            _ => &[],
93        }
94    }
95    /// Parse a container row. Leaf files have no rows.
96    pub fn container_entry(&self, i: usize) -> Result<File, Error> {
97        match self {
98            Self::Bundle(b) => b.entry(i),
99            Self::Web(w) => w.entry(i),
100            _ => Err(Error::Malformed {
101                what: "container entry",
102                detail: "leaf file".into(),
103            }),
104        }
105    }
106    /// Open a child container, leaving serialized and raw entries lazy.
107    /// A leaf still occupies its directory position in a file walk. Probe
108    /// read failures and resource refusals are returned.
109    pub fn child_container(&self, i: usize) -> Result<Option<Self>, Error> {
110        if let Some(file) = self.parsed_container_entry(i) {
111            return Ok(matches!(file, Self::Bundle(_) | Self::Web(_)).then(|| file.clone()));
112        }
113        let container = match self {
114            Self::Bundle(bundle) => crate::env::registry::probe_bundle_entry(bundle, i)?,
115            Self::Web(web) => probe_container(check_entry_type(
116                &web.entry_bytes(i)?,
117                &web.context().limits,
118                web.meter(),
119            ))?,
120            _ => false,
121        };
122        if container {
123            self.container_entry(i).map(Some)
124        } else {
125            Ok(None)
126        }
127    }
128
129    /// The meter of the input this file belongs to.
130    #[must_use]
131    pub fn meter(&self) -> &Arc<Meter> {
132        match self {
133            Self::Serialized(f) => f.meter(),
134            Self::Bundle(f) => f.meter(),
135            Self::Web(f) => f.meter(),
136            Self::Raw(f) => f.meter(),
137        }
138    }
139
140    pub(crate) fn parsed_container_entry(&self, i: usize) -> Option<&Self> {
141        let entries = match self {
142            Self::Bundle(b) => &b.entries,
143            Self::Web(w) => &w.entries,
144            _ => return None,
145        };
146        entries.get(i)?.get()?.as_ref().ok()
147    }
148
149    /// What `check_file_type` called the bytes [`parse_file`] built this
150    /// from, kept so a caller never detects them again (a gzip entry's
151    /// detection inflates it): each kind but a reader has one type, and a
152    /// reader keeps its own ([`RawFile::file_type`]).
153    #[must_use]
154    pub fn file_type(&self) -> FileType {
155        match self {
156            Self::Serialized(_) => FileType::AssetsFile,
157            Self::Bundle(_) => FileType::BundleFile,
158            Self::Web(_) => FileType::WebFile,
159            Self::Raw(f) => f.file_type(),
160        }
161    }
162}
163
164/// Directory indices within a dependency source. The location survives a
165/// reopen without holding any of the parent containers alive.
166#[derive(Default)]
167struct DependencyPath(OnceLock<MeteredVec<usize>>);
168
169impl DependencyPath {
170    fn parse_child(
171        &self,
172        meter: &Arc<Meter>,
173        index: usize,
174        parse: impl FnOnce() -> Result<File, Error>,
175    ) -> Result<File, Error> {
176        let Some(parent) = self.0.get() else {
177            return parse();
178        };
179        let file = parse()?;
180        if matches!(file, File::Raw(_)) {
181            return Ok(file);
182        }
183        meter.count_decode(parent.len() as u64 + 1)?;
184        let mut path = MeteredVec::with_capacity(meter, parent.len().saturating_add(1))?;
185        path.extend_from_slice(parent.as_slice())?;
186        path.push(index)?;
187        file.set_dependency_path(path);
188        Ok(file)
189    }
190}
191
192/// A file UnityPy keeps as a reader.
193#[derive(Debug)]
194pub struct RawFile {
195    /// The name it was loaded under.
196    pub name: RawStr,
197    /// Its bytes (a slice of the parent's buffer for an entry).
198    pub data: Bytes,
199    /// What `check_file_type` called `data`: `ResourceFile`, a zip entry's
200    /// `Zip`, or an `AssetsFile` the name rule keeps as a reader.
201    ty: FileType,
202    /// The reader it is: a resource read from it follows its rules.
203    reader: ReaderKind,
204    /// The handle's own allocation, charged to the input.
205    charge: Charge,
206}
207
208impl RawFile {
209    /// A raw file of `data` under `name`, which `check_file_type` called
210    /// `ty`, its allocation charged to `meter` first (`data` is a slice of a
211    /// buffer already charged, or the caller's). A memory reader, as UnityPy
212    /// keeps bytes and every entry of a container.
213    pub fn new(
214        name: RawStr,
215        data: Bytes,
216        ty: FileType,
217        meter: &Arc<Meter>,
218    ) -> Result<Arc<Self>, ChargeError> {
219        Self::with_reader(name, data, ty, meter, ReaderKind::Memory)
220    }
221
222    /// [`Self::new`] as the reader `reader` ([`ReaderKind::Stream`] for a
223    /// top-level file loaded from a path).
224    pub fn with_reader(
225        name: RawStr,
226        data: Bytes,
227        ty: FileType,
228        meter: &Arc<Meter>,
229        reader: ReaderKind,
230    ) -> Result<Arc<Self>, ChargeError> {
231        let charge = meter.charge(heap_cost(
232            u64::try_from(std::mem::size_of::<Self>() + 16).unwrap_or(u64::MAX),
233        ))?;
234        Ok(Arc::new(Self {
235            name,
236            data,
237            ty,
238            reader,
239            charge,
240        }))
241    }
242
243    /// The reader UnityPy keeps it as, whose rules a resource read from it
244    /// follows (`ResourceReader._get_resource_data`).
245    #[must_use]
246    pub fn reader_kind(&self) -> ReaderKind {
247        self.reader
248    }
249
250    /// The meter of the input it belongs to.
251    #[must_use]
252    pub fn meter(&self) -> &Arc<Meter> {
253        self.charge.meter()
254    }
255
256    /// What `check_file_type` called its bytes.
257    #[must_use]
258    pub fn file_type(&self) -> FileType {
259        self.ty
260    }
261}
262
263/// What a child knows of its container. A file loaded at top level has none
264/// (`parent: None`): UnityPy makes the `Environment` that loaded it its
265/// parent (`environment.py:154`), which is the container `PPtr.deref` scans
266/// (plan section 3.13, rule 4). The input's meter travels separately, as
267/// every file's [`File::meter`], top-level ones included.
268#[derive(Clone, Debug)]
269pub struct Parent {
270    /// The container's name.
271    pub name: RawStr,
272    /// The container's kind.
273    pub kind: ParentKind,
274    /// How deep the child is: 1 for an entry of a top-level container. A
275    /// container at [`crate::limits::Limits::max_container_depth`] refuses to
276    /// parse an entry that is itself a container (`LimitKind::ContainerDepth`).
277    pub depth: u32,
278    /// The length of the buffer the child's bytes are a slice of, which any
279    /// slice of them keeps alive: the container's decoded run that holds
280    /// them, or, for stored blocks, the buffer of the container's own bytes
281    /// (its own `pinned`). Never less than the child's own length, which is
282    /// what a container that does not know it gives. A value read from the
283    /// child copies its slices out when they would keep much more than
284    /// themselves alive ([`crate::pin`]; plan section 8, R3).
285    pub pinned: u64,
286}
287
288/// A container kind, as the `SerializedFile` version chain and `PPtr.deref`
289/// distinguish them.
290#[derive(Clone, Debug)]
291pub enum ParentKind {
292    /// A `BundleFile`, whose raw engine string chain 2 may take. Its fields
293    /// may grow (P1b's sprites kind added `dir_index`), so a caller outside
294    /// the core matches it with `..` and cannot build one.
295    #[non_exhaustive]
296    Bundle {
297        /// `version_engine`, as read.
298        version_engine: RawStr,
299        /// The bundle, for `PPtr.deref`'s scan of its `files` dict (rule 5):
300        /// weak, since the bundle holds its entries (`Arc::new_cyclic` at open).
301        bundle: Weak<BundleFile>,
302        /// The directory row the child was opened from
303        /// ([`BundleFile::entry`]'s `dir_index`): of two rows of one path,
304        /// the child knows which it is, where `files()` names only the last.
305        dir_index: usize,
306    },
307    /// A `WebFile`, which gives no version.
308    Web {
309        /// The WebFile whose files dict is scanned for siblings.
310        web: Weak<WebFile>,
311    },
312}
313
314/// `parse_file`: builds the file `ty` says, under the name rule
315/// ([`crate::detect::parsed_as`]), from bytes (UnityPy's memory reader). A
316/// file with a `parent` is an entry. Everything it keeps is charged to
317/// `meter`, the input's.
318pub fn parse_file(
319    name: RawStr,
320    data: Bytes,
321    ty: FileType,
322    parent: Option<Parent>,
323    meter: &Arc<Meter>,
324    ctx: &Arc<FileContext>,
325) -> Result<File, Error> {
326    parse_file_with_reader(name, data, ty, parent, meter, ctx, ReaderKind::Memory)
327}
328
329/// [`parse_file`] by the rules of the reader UnityPy reads the file with:
330/// [`ReaderKind::Stream`] for a top-level file loaded from a path
331/// (`environment.py:136-139`; [`crate::env::Source::Path`]), whose
332/// `SerializedFile`, bundle header or kept reader follows them. A
333/// container's entries are memory whatever its reader. WebFile members use memory readers after inflation.
334pub fn parse_file_with_reader(
335    name: RawStr,
336    data: Bytes,
337    ty: FileType,
338    parent: Option<Parent>,
339    meter: &Arc<Meter>,
340    ctx: &Arc<FileContext>,
341    reader: ReaderKind,
342) -> Result<File, Error> {
343    parse_file_at_depth(name, data, ty, parent, meter, ctx, reader, 0)
344}
345
346/// Parse a source nested inside ZIPs without giving it a fictitious bundle
347/// parent. ZIP members are Environment files, but their container depth still
348/// contributes to bundles opened from them and those bundles' descendants.
349#[allow(
350    clippy::too_many_arguments,
351    reason = "internal reader API plus independent ZIP depth"
352)]
353pub(crate) fn parse_file_at_depth(
354    name: RawStr,
355    data: Bytes,
356    ty: FileType,
357    parent: Option<Parent>,
358    meter: &Arc<Meter>,
359    ctx: &Arc<FileContext>,
360    reader: ReaderKind,
361    source_depth: u32,
362) -> Result<File, Error> {
363    parse_file_with_state(
364        name,
365        data,
366        ty,
367        parent,
368        meter,
369        ctx,
370        reader,
371        source_depth,
372        &mut None,
373    )
374}
375
376/// Parse with the endian assignment made to the constructor's input reader,
377/// including when construction fails. Inflated readers do not change it.
378#[allow(clippy::too_many_arguments)]
379pub(crate) fn parse_file_with_state(
380    name: RawStr,
381    data: Bytes,
382    ty: FileType,
383    parent: Option<Parent>,
384    meter: &Arc<Meter>,
385    ctx: &Arc<FileContext>,
386    reader: ReaderKind,
387    source_depth: u32,
388    endian: &mut Option<crate::stream::Endian>,
389) -> Result<File, Error> {
390    // UnityPy helpers/ImportHelper.py:127-156; a zip input is refused (P3).
391    let kind = parsed_as(ty, name.as_bytes(), parent.is_some());
392    if matches!(kind, ParsedAs::BundleFile | ParsedAs::WebFile)
393        && parent.as_ref().map_or(source_depth, |p| p.depth) > ctx.limits.max_container_depth
394    {
395        return Err(Error::Limit(LimitError::refused(
396            LimitKind::ContainerDepth,
397            u64::from(parent.as_ref().map_or(source_depth, |p| p.depth)),
398            u64::from(ctx.limits.max_container_depth),
399        )));
400    }
401    Ok(match kind {
402        ParsedAs::SerializedFile => File::Serialized(SerializedFile::parse_with_state(
403            name, data, parent, meter, ctx, reader, endian,
404        )?),
405        ParsedAs::BundleFile => File::Bundle(BundleFile::open_at_depth(
406            name,
407            data,
408            parent,
409            meter,
410            ctx,
411            reader,
412            source_depth,
413        )?),
414        ParsedAs::WebFile => File::Web(WebFile::open_with_state(
415            name,
416            data,
417            parent,
418            meter,
419            ctx,
420            reader,
421            source_depth,
422            endian,
423        )?),
424        ParsedAs::Zip => return Err(Error::Unsupported(Unsupported::Zip)),
425        ParsedAs::Raw | ParsedAs::Error => {
426            File::Raw(RawFile::with_reader(name, data, ty, meter, reader)?)
427        }
428    })
429}