Skip to main content

unityrs_core/files/serialized/
write.rs

1// Ported from UnityPy 1.25.2 (MIT): UnityPy/files/SerializedFile.py, UnityPy/files/ObjectReader.py. See THIRD_PARTY_LICENSES.
2// Ported from UnityPy git 417d595 (MIT): UnityPy/files/SerializedFile.py, UnityPy/helpers/TypeTreeNode.py. See THIRD_PARTY_LICENSES.
3//! File save (`files/SerializedFile.py:389-493`), type records
4//! (`files/SerializedFile.py:151-198`) and object rows
5//! (`files/ObjectReader.py:132-179`). Types and metadata retain file order;
6//! objects use the already charged path index, including duplicate-id collapse.
7//! Every temporary and the returned bytes charge the input's meter.
8
9use super::{External, ObjectInfo, SerializedFile, SerializedHeader, SerializedType};
10use crate::RawStr;
11use crate::files::save::{SaveError, SaveLayout, SaveOptions, Writer, narrow, required};
12use crate::stream::Endian;
13use bytes::Bytes;
14
15#[path = "write_head.rs"]
16mod head_writer;
17
18/// Caller-owned metadata and object payload snapshot. All retained storage must
19/// be charged by the caller before constructing it. Object rows are emitted in
20/// supplied order, including repeated path ids; dictionary keys are irrelevant.
21pub struct SerializedSaveSnapshot<'a> {
22    /// Current header (sizes and offsets are recomputed).
23    pub header: SerializedHeader,
24    /// Current Unity version string.
25    pub unity_version: Option<RawStr>,
26    /// Current raw build target.
27    pub target_platform: Option<i32>,
28    /// Whether type records carry trees.
29    pub enable_type_tree: bool,
30    /// Pre-format-14 path-id width switch.
31    pub big_id_enabled: i32,
32    /// Current object metadata and payloads, sorted by signed path id. Each
33    /// row's `byte_size` is its logical payload length, which may differ from
34    /// the buffer's byte count (Python's `len(data)` versus `nbytes`).
35    pub objects: &'a [(ObjectInfo, Bytes)],
36    /// Current external reference list, replacing loaded and pending entries.
37    pub externals: &'a [External],
38    /// Current user information string.
39    pub user_information: Option<RawStr>,
40}
41const _: () = crate::send_sync::<SerializedSaveSnapshot<'static>>();
42
43impl SerializedFile {
44    /// Save metadata and objects, sorting by signed path id and padding every
45    /// data block to eight bytes. The result owns its meter charge. Saving
46    /// never clears `is_changed` or rewrites the loaded reader's metadata.
47    ///
48    /// Old trees, required pre-v13 trees, and pre-v9's data offset are
49    /// corrected under both layouts (Tier C writing). Otherwise `UnityPy`
50    /// matches UnityPy 1.25.2's uncompressed save through format 22 and
51    /// HEAD 417d595 for formats 23-26. HEAD's absent per-type node assertion
52    /// and formats above 26 refuse before building or charging output.
53    ///
54    /// `Semantic` refuses with a `Range` collision an output that detection
55    /// would not reload as a SerializedFile (a bundle signature or gzip magic
56    /// in the header's sizes, the brotli marker at 0x20 in metadata or object
57    /// bytes below format 22); the `UnityPy` layout writes it unchecked.
58    pub fn save(&self, options: SaveOptions) -> Result<Bytes, SaveError> {
59        self.save_impl(options, None)
60    }
61
62    /// Serialize a metered snapshot without modifying the loaded file or edits.
63    pub fn save_with_snapshot(
64        &self,
65        options: SaveOptions,
66        snapshot: &SerializedSaveSnapshot<'_>,
67    ) -> Result<Bytes, SaveError> {
68        self.save_impl(options, Some(snapshot))
69    }
70
71    fn save_impl(
72        &self,
73        options: SaveOptions,
74        snapshot: Option<&SerializedSaveSnapshot<'_>>,
75    ) -> Result<Bytes, SaveError> {
76        let h = snapshot.map_or(&self.header, |s| &s.header);
77        let v = h.version;
78        let enabled = snapshot.map_or(self.enable_type_tree, |s| s.enable_type_tree);
79        let big_id = snapshot.map_or(self.big_id_enabled, |s| s.big_id_enabled);
80        if v > 26 {
81            return Err(SaveError::HeadTierWritesNotImplemented);
82        }
83        if v >= 23 && enabled {
84            for t in self
85                .types
86                .iter()
87                .chain(self.ref_types.iter().flat_map(|r| r.iter()))
88            {
89                self.meter().count_decode(1)?;
90                required(t.nodes.as_ref(), "HEAD type node")?;
91            }
92        }
93        let mut meta = Writer::metadata(self.meter(), h.endian, options.layout)?;
94        let mut data = Writer::new(self.meter(), h.endian)?;
95        if v >= 7 {
96            meta.cstr(
97                required(
98                    snapshot.map_or(self.unity_version.as_ref(), |s| s.unity_version.as_ref()),
99                    "unity_version",
100                )?
101                .as_bytes(),
102            )?;
103        }
104        if v >= 8 {
105            meta.i32(required(
106                snapshot.map_or(self.target_platform, |s| s.target_platform),
107                "target_platform",
108            )?)?;
109        }
110        // Below 13 the reader unconditionally expects trees, even when the
111        // config flag was false at load. Keep the parsed trees (Tier C).
112        let trees = enabled || v < 13;
113        if v >= 13 {
114            meta.boolean(trees)?;
115        }
116        meta.count(self.types.len())?;
117        for (i, t) in self.types.iter().enumerate() {
118            t.write((self, h), &mut meta, trees, false, i, options)?;
119        }
120        if (7..14).contains(&v) {
121            meta.i32(big_id)?;
122        }
123        meta.count(snapshot.map_or(self.by_path.len(), |s| s.objects.len()))?;
124        // A save sees one consistent set of replacements. No read or write
125        // can re-enter this mutex; allocations follow MemoryBudget's contract.
126        let edits = self
127            .edits
128            .lock()
129            .unwrap_or_else(std::sync::PoisonError::into_inner);
130        let count = snapshot.map_or(self.by_path.len(), |s| s.objects.len());
131        for position in 0..count {
132            let raw;
133            let (row, payload) = if let Some(snapshot) = snapshot {
134                let (row, bytes) = required(snapshot.objects.get(position), "object row")?;
135                (row, bytes.as_ref())
136            } else {
137                let index = *required(self.by_path.get(position), "object index")?;
138                let row = required(self.object_infos.get(index as usize), "object row")?;
139                let payload = if let Some((_, replacement)) = edits
140                    .as_slice()
141                    .binary_search_by_key(&index, |(i, _)| *i)
142                    .ok()
143                    .and_then(|at| edits.as_slice().get(at))
144                {
145                    replacement.as_ref()
146                } else {
147                    raw = self.original_data(row)?;
148                    raw.as_ref()
149                };
150                (row, payload)
151            };
152            self.write_object(
153                row,
154                payload,
155                &mut meta,
156                &mut data,
157                (v, big_id, snapshot.is_none()),
158            )?;
159        }
160        drop(edits);
161        self.write_references(&mut meta, trees, options, snapshot)?;
162        meta.end_metadata()?;
163        self.finish_file(h, &meta, &data, options.layout)
164    }
165
166    fn write_object(
167        &self,
168        row: &ObjectInfo,
169        payload: &[u8],
170        meta: &mut Writer,
171        data: &mut Writer,
172        settings: (u32, i32, bool),
173    ) -> Result<(), SaveError> {
174        let (v, big_id, native) = settings;
175        if big_id != 0 {
176            meta.i64(row.path_id)?;
177        } else if v < 14 {
178            meta.i32(narrow(row.path_id, "path_id")?)?;
179        } else {
180            meta.align(4)?;
181            meta.i64(row.path_id)?;
182        }
183        if v >= 22 {
184            meta.i64(narrow(data.len(), "byte_start")?)?;
185        } else {
186            meta.u32(narrow(data.len(), "byte_start")?)?;
187        }
188        meta.u32(if native {
189            narrow(payload.len(), "byte_size")?
190        } else {
191            row.byte_size
192        })?;
193        data.bytes(payload)?;
194        data.align(8)?;
195        meta.i32(row.type_id)?;
196        if v < 16 {
197            meta.u16(narrow(row.class_id, "class_id")?)?;
198        }
199        if v < 11 {
200            meta.u16(required(row.is_destroyed, "is_destroyed")?)?;
201        }
202        if (11..17).contains(&v) {
203            let script = if native {
204                row.type_index
205                    .and_then(|i| self.types.get(i))
206                    .map(|t| t.script_type_index)
207            } else {
208                row.script_type_index
209            };
210            meta.i16(required(script, "script_type_index")?)?;
211        }
212        if v == 15 || v == 16 {
213            meta.bytes(&required(row.is_stripped, "is_stripped")?.to_ne_bytes())?;
214        }
215        Ok(())
216    }
217
218    fn write_references(
219        &self,
220        meta: &mut Writer,
221        trees: bool,
222        options: SaveOptions,
223        snapshot: Option<&SerializedSaveSnapshot<'_>>,
224    ) -> Result<(), SaveError> {
225        let h = snapshot.map_or(&self.header, |s| &s.header);
226        let v = h.version;
227        if v >= 11 {
228            meta.count(self.script_types.len())?;
229            for s in &self.script_types {
230                meta.i32(s.file_index)?;
231                if v < 14 {
232                    meta.i32(narrow(s.identifier, "script identifier")?)?;
233                } else {
234                    meta.align(4)?;
235                    meta.i64(s.identifier)?;
236                }
237            }
238        }
239        let pending = self
240            .pending_externals
241            .lock()
242            .unwrap_or_else(std::sync::PoisonError::into_inner);
243        meta.count(
244            snapshot
245                .map_or(self.externals.len(), |s| s.externals.len())
246                .checked_add(if snapshot.is_some() { 0 } else { pending.len() })
247                .ok_or(SaveError::Range("externals"))?,
248        )?;
249        let externals = snapshot.map_or(self.externals.as_ref(), |s| s.externals);
250        for e in externals
251            .iter()
252            .chain(pending.as_slice().iter().filter(|_| snapshot.is_none()))
253        {
254            if v >= 6 {
255                meta.cstr(required(e.temp_empty.as_ref(), "temp_empty")?.as_bytes())?;
256            }
257            if v >= 5 {
258                meta.fixed16(required(e.guid.as_ref(), "guid")?, "guid")?;
259                meta.i32(required(e.kind, "external type")?)?;
260            }
261            meta.cstr(e.path.as_bytes())?;
262        }
263        if v >= 20 {
264            let refs = required(self.ref_types.as_ref(), "ref_types")?;
265            meta.count(refs.len())?;
266            for (i, t) in refs.iter().enumerate() {
267                t.write(
268                    (self, h),
269                    meta,
270                    trees,
271                    true,
272                    self.types
273                        .len()
274                        .checked_add(i)
275                        .ok_or(SaveError::Range("HEAD type index"))?,
276                    options,
277                )?;
278            }
279        }
280        if v >= 26 {
281            head_writer::write_shared((self, h), meta, options)?;
282        }
283        if v >= 5 {
284            meta.cstr(
285                required(
286                    snapshot.map_or(self.user_information.as_ref(), |s| {
287                        s.user_information.as_ref()
288                    }),
289                    "userInformation",
290                )?
291                .as_bytes(),
292            )?;
293        }
294        Ok(())
295    }
296
297    fn finish_file(
298        &self,
299        h: &SerializedHeader,
300        meta: &Writer,
301        data: &Writer,
302        layout: SaveLayout,
303    ) -> Result<Bytes, SaveError> {
304        let v = h.version;
305        let mut out = Writer::new(self.meter(), Endian::Big)?;
306        let size = meta
307            .len()
308            .checked_add(usize::from(v < 9))
309            .ok_or(SaveError::Range("metadata_size"))?;
310        let header: usize = if v >= 22 {
311            48
312        } else if v >= 9 {
313            20
314        } else {
315            16
316        };
317        let end = header
318            .checked_add(meta.len())
319            .ok_or(SaveError::Range("data_offset"))?;
320        let offset = if v < 9 {
321            16
322        } else {
323            end.checked_add((16 - end % 16) % 16)
324                .ok_or(SaveError::Range("data_offset"))?
325        };
326        let total = if v < 9 {
327            header
328                .checked_add(size)
329                .and_then(|n| n.checked_add(data.len()))
330        } else {
331            offset.checked_add(data.len())
332        }
333        .ok_or(SaveError::Range("file_size"))?;
334        out.u32(if v >= 22 {
335            0
336        } else {
337            narrow(size, "metadata_size")?
338        })?;
339        out.u32(if v >= 22 {
340            0
341        } else {
342            narrow(total, "file_size")?
343        })?;
344        out.u32(v)?;
345        out.u32(if v >= 22 {
346            0
347        } else {
348            narrow(offset, "data_offset")?
349        })?;
350        if v >= 9 {
351            out.boolean(h.endian == Endian::Big)?;
352            out.bytes(&required(h.reserved, "reserved")?)?;
353            if v >= 22 {
354                out.u32(narrow(size, "metadata_size")?)?;
355                out.i64(narrow(total, "file_size")?)?;
356                out.i64(narrow(offset, "data_offset")?)?;
357                out.i64(h.unknown)?;
358            }
359            out.bytes(meta.slice())?;
360            out.align(16)?;
361            out.bytes(data.slice())?;
362        } else {
363            out.bytes(data.slice())?;
364            out.boolean(h.endian == Endian::Big)?;
365            out.bytes(meta.slice())?;
366        }
367        if layout == SaveLayout::Semantic {
368            reloads_as_serialized(out.slice())?;
369        }
370        out.finish()
371    }
372
373    pub(crate) fn original_data(&self, row: &super::ObjectInfo) -> Result<Bytes, crate::Error> {
374        let start = self.reader.seek(row.byte_start)?;
375        let (range, _) = self
376            .reader
377            .read(self.data.len(), start, i64::from(row.byte_size))?;
378        Ok(self.data.slice(range))
379    }
380}
381
382/// The semantic layout's reload guard, a pure prefix-signature check: it
383/// runs detection's steps as a bundle or WebFile entry gets them
384/// (`check_entry_type`, `helpers/ImportHelper.py:44-124`) on `bytes`, the
385/// whole output, in place, up to the gzip probe, and neither allocates nor
386/// decodes. The output must detect as an `AssetsFile`, or, under 128 bytes,
387/// as the `ResourceFile` every such small file is. Below format 22 the
388/// header's sizes and the metadata or object bytes that follow can spell a
389/// signature, gzip magic or the brotli marker. Gzip magic is refused without
390/// inflating, conservatively: detection would inflate the stream, which in
391/// a rare output could fall back to the header and detect as this file, but
392/// that needs a metadata size of at least 0x1f8b0800 (about 529 MB).
393fn reloads_as_serialized(bytes: &[u8]) -> Result<(), SaveError> {
394    use crate::detect::{FileType, Signed, signature_only};
395    let reason = match signature_only(bytes) {
396        Ok(Signed::Type(FileType::AssetsFile)) => return Ok(()),
397        Ok(Signed::Type(FileType::ResourceFile)) if bytes.len() < 128 => return Ok(()),
398        Ok(Signed::Type(FileType::BundleFile)) => "SerializedFile bundle signature collision",
399        Ok(Signed::Type(FileType::WebFile)) => "SerializedFile WebFile marker collision",
400        Ok(Signed::Type(FileType::Zip)) => "SerializedFile zip signature collision",
401        Ok(Signed::Type(FileType::ResourceFile)) => "SerializedFile header detected as a resource",
402        Ok(Signed::Gzip) => "SerializedFile gzip magic collision",
403        // A 20-byte output with no NUL, which detection raises for.
404        Err(_) => "SerializedFile unterminated signature collision",
405    };
406    Err(SaveError::Range(reason))
407}
408
409impl SerializedType {
410    fn write(
411        &self,
412        source: (&SerializedFile, &SerializedHeader),
413        out: &mut Writer,
414        trees: bool,
415        is_ref: bool,
416        index: usize,
417        options: SaveOptions,
418    ) -> Result<(), SaveError> {
419        let (file, header) = source;
420        let v = header.version;
421        out.i32(self.class_id)?;
422        if v >= 16 {
423            out.boolean(required(self.is_stripped_type, "is_stripped_type")?)?;
424        }
425        if v >= 17 {
426            out.i16(self.script_type_index)?;
427        }
428        if v >= 13 {
429            if (is_ref && self.script_type_index >= 0)
430                || (v < 16 && self.class_id < 0)
431                || (v >= 16 && self.class_id == 114)
432            {
433                out.fixed16(required(self.script_id.as_ref(), "script_id")?, "script_id")?;
434            }
435            out.fixed16(
436                required(self.old_type_hash.as_ref(), "old_type_hash")?,
437                "old_type_hash",
438            )?;
439        }
440        if trees {
441            if v >= 23 {
442                required(
443                    file.head_handlers.as_slice().get(index),
444                    "HEAD type handler",
445                )?
446                .write((file, header), out, options)?;
447            } else {
448                let nodes = required(self.nodes.as_ref(), "node")?;
449                if crate::typetree::parse::is_blob_format(v) {
450                    nodes.write_blob(
451                        out,
452                        v,
453                        header.endian,
454                        options.layout,
455                        file.ctx.providers.common_strings(),
456                    )?;
457                } else {
458                    nodes.write_old(out, v)?;
459                }
460            }
461            if v >= 21 {
462                if is_ref {
463                    for s in [&self.class_name, &self.namespace, &self.assembly] {
464                        out.cstr(required(s.as_ref(), "ref type name")?.as_bytes())?;
465                    }
466                } else {
467                    let deps = required(self.type_dependencies.as_ref(), "type_dependencies")?;
468                    out.count(deps.len())?;
469                    for &d in deps {
470                        out.i32(d)?;
471                    }
472                }
473            }
474        }
475        Ok(())
476    }
477}
478
479#[cfg(test)]
480mod guard_tests {
481    use super::reloads_as_serialized;
482    use crate::files::save::{SaveError, SaveLayout, SaveOptions};
483    use std::sync::Arc;
484
485    /// A format-17 header (big-endian sizes, then the endian byte and three
486    /// reserved bytes), zero-padded to `len`.
487    fn header(metadata: u32, file: u32, len: usize) -> Vec<u8> {
488        let mut out = Vec::new();
489        for field in [metadata, file, 17, 0x40] {
490            out.extend_from_slice(&field.to_be_bytes());
491        }
492        out.resize(len, 0);
493        out
494    }
495
496    fn collision(reason: &'static str) -> Result<(), SaveError> {
497        Err(SaveError::Range(reason))
498    }
499
500    #[test]
501    fn only_outputs_detected_as_serialized_files_pass() {
502        let guard = reloads_as_serialized;
503        assert_eq!(guard(&header(0x10, 128, 128)), Ok(()));
504        // Under 128 bytes detection says resource for any unsigned file.
505        assert_eq!(guard(&header(0x10, 64, 64)), Ok(()));
506        // Metadata sizes from 0x1f8b0000 open with gzip magic: refused
507        // without inflating, a bad stream (method 0) and a plausible deflate
508        // header (method 8) alike.
509        for metadata in [0x1f8b_0000, 0x1f8b_0804] {
510            assert_eq!(
511                guard(&header(metadata, 128, 128)),
512                collision("SerializedFile gzip magic collision")
513            );
514        }
515        // Sizes 0x556e6974 and 0x79465300 spell `UnityFS\0`, and
516        // 0x504b0304 then a zero byte `PK\x03\x04\0`.
517        assert_eq!(
518            guard(&header(0x556e_6974, 0x7946_5300, 128)),
519            collision("SerializedFile bundle signature collision")
520        );
521        assert_eq!(
522            guard(&header(0x504b_0304, 128, 128)),
523            collision("SerializedFile zip signature collision")
524        );
525        let mut marked = header(0x10, 128, 128);
526        marked[0x20..0x26].copy_from_slice(b"brotli");
527        assert_eq!(
528            guard(&marked),
529            collision("SerializedFile WebFile marker collision")
530        );
531        // Sizes past the file fail the header check: a resource.
532        assert_eq!(
533            guard(&header(0x10, 4096, 128)),
534            collision("SerializedFile header detected as a resource")
535        );
536    }
537
538    /// The save path refuses with the guard's verdict on its own output. Only
539    /// the brotli marker is reachable end to end: the gzip, bundle and zip
540    /// sizes need metadata of hundreds of megabytes or more.
541    #[test]
542    fn semantic_save_refuses_with_the_guards_verdict_on_its_output() {
543        use unityrs_testkit::blob::NodeSpec;
544        use unityrs_testkit::serialized::{ObjectSpec, build, one_object};
545        // Path 2's data, which opens with `brotli`, moves from 0x10 to 0x20
546        // when the save writes path 1's 16 bytes first (the bundle test).
547        let mut marked = b"brotli".to_vec();
548        marked.resize(32, 1);
549        let mut spec = one_object(49, vec![NodeSpec::new(0, "aa", "aa")], marked);
550        spec.format = 8;
551        spec.objects[0].type_id = 49;
552        spec.objects[0].path_id = 2;
553        spec.objects.push(ObjectSpec {
554            path_id: 1,
555            type_id: 49,
556            class_id: 49,
557            data: vec![0; 16],
558            ..ObjectSpec::default()
559        });
560        let file = super::SerializedFile::parse(
561            crate::RawStr::from_static(b"CAB-marker"),
562            bytes::Bytes::from(build(&spec)),
563            None,
564            &crate::limits::Meter::unlimited(),
565            &Arc::new(crate::options::FileContext::unitypy()),
566        )
567        .unwrap();
568        let written = file
569            .save(SaveOptions {
570                layout: SaveLayout::UnityPy,
571            })
572            .unwrap();
573        let verdict = reloads_as_serialized(&written);
574        assert_eq!(
575            verdict,
576            collision("SerializedFile WebFile marker collision")
577        );
578        assert_eq!(file.save(SaveOptions::default()).map(|_| ()), verdict);
579    }
580}