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}