Skip to main content

unityrs_core/files/bundle/
open.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/files/BundleFile.py. See THIRD_PARTY_LICENSES.
2// Ported from UnityPy git 417d595 (MIT): UnityPy/files/BundleFile.py, UnityPy/helpers/CompressionHelper.py. See THIRD_PARTY_LICENSES.
3//! [`BundleFile::open`]: the header, blocks-info and directory, read as
4//! `read_fs` reads them, UnityPy's `files` dict, and where each block's
5//! stored bytes are. No data block is decoded.
6
7use std::ops::Range;
8use std::sync::Arc;
9
10use bytes::Bytes;
11
12use super::counts::DecodeCounts;
13use super::decode::{BlockContext, decode_one};
14use super::index::{Ends, RunIndex};
15use super::{BlockInfo, BundleFile, BundleHeader, DirEntry, FileSlot, LayoutKind};
16use crate::codec::Codec;
17use crate::codec::unitycn::UnityCnDecryptor;
18use crate::counters::Origin;
19use crate::detect::raw_by_name;
20use crate::error::{Error, Unsupported};
21use crate::files::Parent;
22use crate::limits::{Charge, Meter, MeteredVec, heap_cost};
23use crate::once::ResultCell;
24use crate::options::FileContext;
25use crate::raw::RawStr;
26use crate::stream::{Endian, Reader, ReaderKind};
27use crate::typetree::parse::string_to_null;
28use crate::version::{
29    FlagsClass, ResolvedVersion, flags_class, resolve_bundle, uses_block_alignment,
30};
31
32impl BundleFile {
33    /// Reads the header, blocks-info and directory of bytes (the memory
34    /// reader's rules). Decodes no data block. Everything it keeps is
35    /// charged to `meter`, the input's.
36    pub fn open(
37        name: RawStr,
38        data: Bytes,
39        parent: Option<Parent>,
40        meter: &Arc<Meter>,
41        ctx: &Arc<FileContext>,
42    ) -> Result<Arc<Self>, Error> {
43        Self::open_with_reader(name, data, parent, meter, ctx, ReaderKind::Memory)
44    }
45
46    /// [`Self::open`] by the rules of the reader UnityPy would read `data`
47    /// with ([`ReaderKind::Stream`] for a top-level file loaded from a path):
48    /// the header, the blocks-info section and the blocks' stored bytes are
49    /// read through it; the blocks-info table and the entries are memory
50    /// (UnityPy decodes them into bytes, `files/BundleFile.py:141-142`, `:173-186`).
51    pub fn open_with_reader(
52        name: RawStr,
53        data: Bytes,
54        parent: Option<Parent>,
55        meter: &Arc<Meter>,
56        ctx: &Arc<FileContext>,
57        reader: ReaderKind,
58    ) -> Result<Arc<Self>, Error> {
59        Self::open_at_depth(name, data, parent, meter, ctx, reader, 0)
60    }
61
62    #[expect(
63        clippy::too_many_lines,
64        reason = "format-gated header, writable CABs and charged container construction"
65    )]
66    pub(crate) fn open_at_depth(
67        name: RawStr,
68        data: Bytes,
69        parent: Option<Parent>,
70        meter: &Arc<Meter>,
71        ctx: &Arc<FileContext>,
72        reader: ReaderKind,
73        source_depth: u32,
74    ) -> Result<Arc<Self>, Error> {
75        if legacy_layout(&data, reader)? {
76            return super::legacy::open(name, data, parent, meter, ctx, reader, source_depth);
77        }
78        let mut charge = meter.charge(heap_cost((size_of::<Self>() + 16) as u64))?;
79        let mut r = Reader::with_kind(&data, Endian::Big, reader);
80        let FsHeader {
81            signature,
82            format,
83            version_player,
84            version_engine,
85            info_compressed,
86            info_uncompressed,
87            data_flags,
88            engine,
89            class,
90            encrypted,
91            block_alignment,
92            unitycn,
93        } = read_fs_header(&mut r, &data, &mut charge, ctx)?;
94        let blocks_ctx = BlockContext::new(ctx, encrypted, unitycn);
95        // :133-139: at the end, `Position = Length - compressedSize` (which a
96        // stream refuses when negative), the read, and back to the start.
97        let start = r.position();
98        let info_range = if data_flags & 0x80 != 0 {
99            let len = i128::try_from(data.len()).unwrap_or(i128::MAX);
100            r.set_position(len - i128::from(info_compressed))?;
101            let range = r.read_range(i64::from(info_compressed))?;
102            r.set_position(start)?;
103            range
104        } else {
105            r.read_range(i64::from(info_compressed))?
106        };
107        let info_read = u32::try_from(info_range.len()).unwrap_or(u32::MAX);
108        let blocks_info = BlockInfo {
109            uncompressed: info_uncompressed,
110            compressed: info_compressed,
111            bytes_read: info_read,
112            flags: data_flags,
113        };
114        let info = decode_one(
115            &blocks_ctx,
116            meter,
117            data.slice(info_range),
118            info_uncompressed,
119            data_flags,
120            0,
121        )?;
122        let (mut blocks, directory, offsets) = read_blocks_info(&info, format, meter)?;
123        // :170-171
124        if class == FlagsClass::New && data_flags & 0x200 != 0 {
125            r.align(16)?;
126        }
127        // :173-184: the blocks, read in order from here.
128        let (stored, lengths) = stored_blocks(&mut blocks, &offsets, &mut r, meter, ctx)?;
129        let files = files_dict(&directory, meter)?;
130        let entries = entry_cells(directory.len(), meter)?;
131        let header = BundleHeader {
132            signature,
133            format,
134            version_player,
135            version_engine,
136            layout: LayoutKind::Fs,
137            engine_version: Some(Ok(engine)),
138            data_flags: Some(data_flags),
139            flags_class: Some(class),
140            block_alignment,
141            encrypted,
142            hash: None,
143            crc: None,
144            blocks_info: Some(blocks_info),
145        };
146        let blocks = keep(blocks, &mut charge)?;
147        let directory = keep(directory, &mut charge)?;
148        let files = keep(files, &mut charge)?;
149        let lengths = keep(lengths, &mut charge)?;
150        let entries = keep(entries, &mut charge)?;
151        let twins = keep(twins(&directory, meter)?, &mut charge)?;
152        let stored = keep(stored, &mut charge)?;
153        let (ends, c) = Ends::new(blocks.len(), meter)?;
154        charge.absorb(c);
155        let runs = RunIndex::mutex(&mut charge)?;
156        let constructor_position = r.position();
157        Ok(Arc::new_cyclic(|this| Self {
158            writable: crate::files::cab::WritableCabs::new(meter),
159            changed: std::sync::atomic::AtomicBool::new(false),
160            name,
161            source: data,
162            constructor_position,
163            legacy_data: None,
164            header,
165            blocks,
166            directory,
167            files,
168            parent,
169            dependency_path: crate::files::DependencyPath::default(),
170            source_depth,
171            lengths,
172            ends,
173            runs,
174            counts: DecodeCounts::default(),
175            entries,
176            twins,
177            charge,
178            ctx: blocks_ctx,
179            stored,
180            this: this.clone(),
181            origin: Origin::opened(),
182        }))
183    }
184}
185
186/// Where each block's stored bytes are (`reader.read_bytes(compressedSize)`
187/// in order from `r`, by its reader's rules: a size is never negative, so
188/// the two readers read the same bytes), its `bytes_read` set; and the length cells, a stored
189/// block's filled with what was read (`lambda cd, _ucs: cd`) when stored
190/// blocks are their own bytes ([`crate::codec::Codecs::stores_as_is`]) and
191/// what was read is within the block cap
192/// ([`crate::limits::Limits::max_block_output`]). A stored block past the
193/// cap is left to its codec, which refuses it with
194/// [`crate::LimitKind::BlockOutput`] as it does in `load_all`, so a lazy read
195/// fails it as the eager load does.
196#[allow(clippy::type_complexity)]
197fn stored_blocks(
198    blocks: &mut MeteredVec<BlockInfo>,
199    offsets: &MeteredVec<u64>,
200    r: &mut Reader<'_>,
201    meter: &Arc<Meter>,
202    ctx: &FileContext,
203) -> Result<(MeteredVec<Range<usize>>, MeteredVec<ResultCell<u64, Error>>), Error> {
204    let mut stored = MeteredVec::new(meter);
205    let mut lengths = MeteredVec::new(meter);
206    let base = r.position();
207    for (i, b) in blocks.as_mut_slice().iter_mut().enumerate() {
208        // HEAD files/BundleFile.py:485-491: offsets are relative to the data
209        // start, independent of block order, gaps and alignment.
210        if let Some(offset) = offsets.as_slice().get(i) {
211            r.set_position(base + i128::from(*offset))?;
212        }
213        let range = r.read_range(i64::from(b.compressed))?;
214        b.bytes_read = u32::try_from(range.len()).unwrap_or(u32::MAX);
215        stored.push(range)?;
216        let cell = ResultCell::new();
217        if known_at_open(b, ctx) {
218            let _ = cell.set(Ok(u64::from(b.bytes_read)));
219        }
220        lengths.push(cell)?;
221    }
222    Ok((stored, lengths))
223}
224
225/// Whether the open takes block `b`'s length from its stored bytes
226/// ([`stored_blocks`]): a stored block, while stored blocks are their own
227/// bytes and what was read is within the block cap.
228pub(super) fn known_at_open(b: &BlockInfo, ctx: &FileContext) -> bool {
229    ctx.codecs.stores_as_is()
230        && Codec::from_flags(u32::from(b.flags_u16())) == Codec::None
231        && u64::from(b.bytes_read) <= ctx.limits.max_block_output
232}
233
234/// The header fields `read_fs` reads before the blocks-info section.
235struct FsHeader {
236    signature: RawStr,
237    format: u32,
238    version_player: RawStr,
239    version_engine: RawStr,
240    info_compressed: u32,
241    info_uncompressed: u32,
242    data_flags: u32,
243    engine: ResolvedVersion,
244    class: FlagsClass,
245    encrypted: bool,
246    block_alignment: bool,
247    unitycn: Option<UnityCnDecryptor>,
248}
249
250/// `BundleFile.__init__` up to the signature dispatch, then `read_fs` up to
251/// the blocks-info section (`files/BundleFile.py:36-51`, `:96-131`); leaves `r` where
252/// blocks-info would start. Its strings' searches and its engine version's
253/// parse are the work of `charge`'s meter, the input's, and the version's
254/// heap is charged to `charge`, the bundle's handle.
255fn read_fs_header(
256    r: &mut Reader<'_>,
257    data: &Bytes,
258    charge: &mut Charge,
259    ctx: &FileContext,
260) -> Result<FsHeader, Error> {
261    let meter = charge.meter().clone();
262    let meter = &meter;
263    // UnityPy files/BundleFile.py:36-39
264    let signature = string_to_null(r, data, meter)?;
265    let format = r.read_u32()?;
266    let version_player = string_to_null(r, data, meter)?;
267    let version_engine = string_to_null(r, data, meter)?;
268    // :41-51
269    match signature.as_bytes() {
270        b"UnityArchive" => return Err(Error::Unsupported(Unsupported::UnityArchive)),
271        b"UnityWeb" | b"UnityRaw" if format != 6 => {
272            return Err(Error::Unsupported(Unsupported::WebRawLayout));
273        }
274        b"UnityWeb" | b"UnityRaw" | b"UnityFS" => {}
275        _ => {
276            return Err(Error::BundleSignature(RawStr::charged(
277                signature.as_bytes(),
278                meter,
279            )?));
280        }
281    }
282    // :97-106
283    let _size = r.read_i64()?;
284    let info_compressed = r.read_u32()?;
285    let info_uncompressed = r.read_u32()?;
286    let data_flags = r.read_u32()?;
287    if signature.as_bytes() != b"UnityFS" {
288        r.read_i8()?;
289    }
290    // :108-121
291    let engine = resolve_bundle(&version_engine, &ctx.version_policy(), charge)?;
292    let class = flags_class(&engine.version)?;
293    // :123-124: the encryption flag, before the alignment.
294    let mask = match class {
295        FlagsClass::Old => 0x200,
296        FlagsClass::New => 0x1400,
297    };
298    let encrypted = data_flags & mask != 0;
299    let unitycn = if encrypted {
300        if ctx.decryptor.is_some() {
301            // A custom decryptor owns its header semantics; retain the existing
302            // hook's consumption of the 70-byte UnityCN envelope.
303            r.read_u32()?;
304            for _ in 0..2 {
305                r.read_bytes_short(32);
306                r.set_position(r.position() + 1)?;
307            }
308            None
309        } else {
310            Some(UnityCnDecryptor::read_with_key(r, || {
311                ctx.runtime_config
312                    .as_ref()
313                    .map_or(Ok(ctx.assetbundle_decrypt_key), |config| {
314                        config
315                            .resolve_decrypt_key(charge.meter())
316                            .map(|key| key.or(ctx.assetbundle_decrypt_key))
317                            .map_err(Error::from)
318                    })
319            })?)
320        }
321    } else {
322        None
323    };
324    // :129-131
325    let block_alignment = uses_block_alignment(format, &engine.version)?;
326    if block_alignment {
327        r.align(16)?;
328    }
329    Ok(FsHeader {
330        signature,
331        format,
332        version_player,
333        version_engine,
334        info_compressed,
335        info_uncompressed,
336        data_flags,
337        engine,
338        class,
339        encrypted,
340        block_alignment,
341        unitycn,
342    })
343}
344
345/// The blocks-info and directory tables (`files/BundleFile.py:141-165`), read
346/// big-endian from the decoded section; paths are slices of it.
347#[allow(clippy::type_complexity)]
348fn read_blocks_info(
349    info: &Bytes,
350    format: u32,
351    meter: &Arc<Meter>,
352) -> Result<(MeteredVec<BlockInfo>, MeteredVec<DirEntry>, MeteredVec<u64>), Error> {
353    let mut r = Reader::new(info, Endian::Big);
354    // The uncompressed-data hash, read and discarded (short at the end).
355    r.read_bytes_short(16);
356    let mut blocks = MeteredVec::new(meter);
357    let mut offsets = MeteredVec::new(meter);
358    for _ in 0..r.read_i32()?.max(0) {
359        let uncompressed = r.read_u32()?;
360        let compressed = r.read_u32()?;
361        let flags = u32::from(r.read_u16()?);
362        // HEAD helpers/CompressionHelper.py:158-172.
363        if format >= 9 {
364            offsets.push(r.read_u64()?)?;
365        }
366        blocks.push(BlockInfo {
367            uncompressed,
368            compressed,
369            bytes_read: 0,
370            flags,
371        })?;
372    }
373    let mut directory = MeteredVec::new(meter);
374    for _ in 0..r.read_i32()?.max(0) {
375        let offset = r.read_i64()?;
376        let size = r.read_i64()?;
377        let flags = r.read_u32()?;
378        let path = string_to_null(&mut r, info, meter)?;
379        directory.push(DirEntry {
380            offset,
381            size,
382            flags: Some(flags),
383            path,
384        })?;
385    }
386    Ok((blocks, directory, offsets))
387}
388
389/// UnityPy's `files` dict over the directory: each path at its first
390/// position, holding its last entry. Computed by sorting.
391pub(crate) fn files_dict(
392    dir: &MeteredVec<DirEntry>,
393    meter: &Arc<Meter>,
394) -> Result<MeteredVec<FileSlot>, Error> {
395    let rows = dir.as_slice();
396    let mut perm: MeteredVec<usize> = MeteredVec::with_capacity(meter, rows.len())?;
397    for i in 0..rows.len() {
398        perm.push(i)?;
399    }
400    let path = |i: &usize| rows.get(*i).map(|d| d.path.as_bytes()).unwrap_or_default();
401    // Stable by the index tiebreak, and in place: a stable sort's scratch
402    // (half the rows or more) would be heap no meter charged (plan 3.15).
403    perm.as_mut_slice()
404        .sort_unstable_by(|a, b| path(a).cmp(path(b)).then(a.cmp(b)));
405    let mut groups: MeteredVec<(usize, usize)> = MeteredVec::new(meter);
406    let all = perm.as_slice();
407    let mut at = 0;
408    while let Some(first) = all.get(at) {
409        let mut last = *first;
410        let mut end = at + 1;
411        while let Some(next) = all.get(end).filter(|n| path(n) == path(first)) {
412            last = *next;
413            end += 1;
414        }
415        groups.push((*first, last))?;
416        at = end;
417    }
418    groups.as_mut_slice().sort_unstable_by_key(|g| g.0);
419    let mut files = MeteredVec::with_capacity(meter, groups.len())?;
420    for (first, last) in groups.as_slice() {
421        files.push(FileSlot {
422            name: rows.get(*first).map(|d| d.path.clone()).unwrap_or_default(),
423            dir_index: *last,
424        })?;
425    }
426    Ok(files)
427}
428
429/// Each row's first twin (the `bundle` module docs, "Twins"): the first row,
430/// in directory order, whose offset, size and name rule
431/// ([`crate::detect::raw_by_name`]) are the row's own, or the row itself.
432/// Computed by sorting the rows' keys, the scratch charged.
433pub(super) fn twins(rows: &[DirEntry], meter: &Arc<Meter>) -> Result<MeteredVec<u32>, Error> {
434    let mut keys: MeteredVec<(i64, i64, bool, u32)> = MeteredVec::with_capacity(meter, rows.len())?;
435    let mut twins: MeteredVec<u32> = MeteredVec::with_capacity(meter, rows.len())?;
436    for (i, d) in rows.iter().enumerate() {
437        // A directory holds at most `i32::MAX` rows (its count is an `i32`).
438        let i = u32::try_from(i).unwrap_or(u32::MAX);
439        keys.push((d.offset, d.size, raw_by_name(d.path.as_bytes()), i))?;
440        twins.push(i)?;
441    }
442    keys.as_mut_slice().sort_unstable();
443    let mut first = None;
444    for &(offset, size, raw, i) in keys.as_slice() {
445        match first {
446            Some((key, f)) if key == (offset, size, raw) => {
447                if let Some(t) = usize::try_from(i)
448                    .ok()
449                    .and_then(|i| twins.as_mut_slice().get_mut(i))
450                {
451                    *t = f;
452                }
453            }
454            _ => first = Some(((offset, size, raw), i)),
455        }
456    }
457    Ok(twins)
458}
459
460/// A table as the bundle keeps it, its charge moved into the bundle's.
461pub(crate) fn keep<T>(table: MeteredVec<T>, charge: &mut Charge) -> Result<Box<[T]>, Error> {
462    let (b, c) = table.into_boxed_slice()?;
463    charge.absorb(c);
464    Ok(b)
465}
466
467fn legacy_layout(data: &Bytes, kind: ReaderKind) -> Result<bool, Error> {
468    if !(data.starts_with(b"UnityWeb\0") || data.starts_with(b"UnityRaw\0")) {
469        return Ok(false);
470    }
471    let mut r = Reader::with_kind(data, Endian::Big, kind);
472    r.set_position(9)?;
473    Ok(r.read_u32()? != 6)
474}
475
476fn entry_cells(
477    n: usize,
478    meter: &Arc<Meter>,
479) -> Result<MeteredVec<super::super::teardown::FileCell>, Error> {
480    let mut cells = MeteredVec::new(meter);
481    for _ in 0..n {
482        cells.push(super::super::teardown::FileCell::new())?;
483    }
484    Ok(cells)
485}