Skip to main content

unityrs_export/extractor/
mod.rs

1// Ported from UnityPy 1.25.2 (MIT): tools/extractor.py. See THIRD_PARTY_LICENSES.
2//! L9 extractor: tools/extractor.py:25-157, tools/extractor.py:165-319.
3//! Container entries are never deduplicated. Stable priority is implemented
4//! by sorting (priority, original ordinal), without allocating sort scratch.
5//! Tier C failures are retained in the report; failure to allocate the
6//! report itself ends the run. The caller supplies a confined filesystem
7//! sink; all names handed to it have passed [`paths::validate`].
8mod crawl;
9mod images;
10pub mod paths;
11mod resource;
12use crate::{audio, shader, simple};
13use std::sync::Arc;
14use unityrs_core::{
15    ObjectRef, Parsed, RawStr, Value,
16    env::Environment,
17    limits::{ChargeError, Meter, MeteredVec},
18};
19use unityrs_mesh::obj::{self, MeteredWrite};
20
21/// Export dispatch order, including UnityPy's observable insertion order.
22pub const EXPORT_TYPES: [i32; 9] = [1, 213, 83, 128, 43, 114, 48, 49, 28];
23/// Called first with metadata, then with the parsed object, as UnityPy does.
24/// A missing MonoBehaviour tree is passed as None on the second call too.
25pub trait AssetFilter: Send + Sync {
26    /// Upper bound on lookup work, reserved before each call to `accepts`.
27    /// Existing callbacks retain their own work-accounting policy.
28    fn lookup_work(&self) -> u64 {
29        0
30    }
31    fn accepts(&self, object: &ObjectRef, parsed: Option<&Parsed>) -> bool;
32}
33/// Options of `extract_assets`; loading is the caller's Environment policy.
34#[derive(Clone, Copy)]
35pub struct Options<'a> {
36    pub use_container: bool,
37    pub ignore_first_container_dirs: i64,
38    pub append_path_id: bool,
39    pub export_unknown_as_typetree: bool,
40    pub asset_filter: Option<&'a dyn AssetFilter>,
41    /// The caller's runtime setup-header table. `None` keeps Vorbis samples
42    /// a typed failure. Batch never sets this option or calls the extractor.
43    pub vorbis: Option<&'a unityrs_audio::VorbisHeaders>,
44}
45impl Default for Options<'_> {
46    fn default() -> Self {
47        Self {
48            use_container: true,
49            ignore_first_container_dirs: 0,
50            append_path_id: false,
51            export_unknown_as_typetree: false,
52            asset_filter: None,
53            vorbis: None,
54        }
55    }
56}
57/// A sink must confine paths beneath its root and charge buffered output
58/// before fallible allocation. A successful call has finished writing.
59pub trait Sink {
60    fn directory(&mut self, relative: &[u8]) -> Result<(), Error>;
61    fn file(&mut self, relative: &[u8], bytes: &[u8]) -> Result<(), Error>;
62}
63#[derive(Debug, thiserror::Error)]
64pub enum Error {
65    #[error("unsafe extractor output path")]
66    UnsafePath,
67    #[error("invalid extractor field {0}")]
68    Field(&'static str),
69    #[error(transparent)]
70    Core(#[from] unityrs_core::Error),
71    #[error(transparent)]
72    Deref(#[from] unityrs_core::env::DerefError),
73    #[error(transparent)]
74    Charge(#[from] ChargeError),
75    #[error(transparent)]
76    Simple(#[from] simple::Error),
77    #[error(transparent)]
78    Audio(#[from] audio::Error),
79    #[error(transparent)]
80    Shader(#[from] shader::Error),
81    #[error(transparent)]
82    Mesh(#[from] unityrs_mesh::MeshError),
83    #[error(transparent)]
84    MeshDecode(#[from] unityrs_meshdecode::MeshError),
85    #[error(transparent)]
86    Decode(#[from] unityrs_texture::DecodeError),
87    #[error(transparent)]
88    Sprite(#[from] unityrs_texture::sprite::SpriteError),
89    #[error(transparent)]
90    Fetch(#[from] unityrs_texture::fetch::Error),
91    #[error("image writer: {0:?}")]
92    Image(unityrs_imageio::writers::SaveError<ChargeError>),
93    #[error(transparent)]
94    Io(#[from] std::io::Error),
95}
96impl Error {
97    /// Whether this terminal failure refused memory, allocation or bounded
98    /// work, including a lazy input read nested inside an exporter error.
99    #[must_use]
100    pub fn resource_refusal(&self) -> bool {
101        resource::refused(self)
102    }
103}
104/// A completed write, including writes subsequently overwritten. Paths are relative.
105#[derive(Debug)]
106pub struct Written {
107    pub object: ObjectRef,
108    pub path: RawStr,
109    pub size: u64,
110}
111/// An export failure with its original typed cause and requested relative path.
112#[derive(Debug)]
113pub struct Failure {
114    pub object: ObjectRef,
115    pub path: RawStr,
116    pub error: Error,
117}
118/// Exported identities preserve UnityPy's duplicates (a Sprite returns its texture).
119#[derive(Clone, Debug)]
120pub struct Identity {
121    pub file: Arc<unityrs_core::files::SerializedFile>,
122    pub path_id: i64,
123}
124impl From<&ObjectRef> for Identity {
125    fn from(object: &ObjectRef) -> Self {
126        Self {
127            file: object.file().clone(),
128            path_id: object.path_id(),
129        }
130    }
131}
132#[derive(Debug)]
133pub struct Report {
134    pub written: MeteredVec<Written>,
135    pub failures: MeteredVec<Failure>,
136    pub exported: MeteredVec<Identity>,
137}
138impl Report {
139    #[must_use]
140    pub fn new(meter: &Arc<Meter>) -> Self {
141        Self {
142            written: MeteredVec::new(meter),
143            failures: MeteredVec::new(meter),
144            exported: MeteredVec::new(meter),
145        }
146    }
147}
148fn same(a: &ObjectRef, b: &ObjectRef) -> bool {
149    Arc::ptr_eq(a.file(), b.file()) && a.path_id() == b.path_id()
150}
151fn contains(objects: &[ObjectRef], obj: &ObjectRef, meter: &Meter) -> Result<bool, Error> {
152    meter.count_decode(objects.len() as u64)?;
153    Ok(objects.iter().any(|a| same(a, obj)))
154}
155fn was_exported(objects: &[Identity], obj: &ObjectRef, meter: &Meter) -> Result<bool, Error> {
156    meter.count_decode(objects.len() as u64)?;
157    Ok(objects
158        .iter()
159        .any(|a| Arc::ptr_eq(&a.file, obj.file()) && a.path_id == obj.path_id()))
160}
161fn priority(id: i32) -> usize {
162    EXPORT_TYPES.iter().position(|i| *i == id).unwrap_or(999)
163}
164struct Entry {
165    object: ObjectRef,
166    path: RawStr,
167    ordinal: usize,
168}
169/// Extract a loaded Environment. Empty container mode stays empty: there is
170/// no implicit fallback to all objects. Later entries overwrite earlier ones.
171pub fn extract_assets(
172    env: &Environment,
173    options: &Options<'_>,
174    sink: &mut dyn Sink,
175    meter: &Arc<Meter>,
176) -> Result<Report, Error> {
177    let mut report = Report::new(meter);
178    sink.directory(b"")?;
179    let mut entries = MeteredVec::new(meter);
180    if options.use_container {
181        for item in env.container()? {
182            let item = item?;
183            let Some(ptr) = item.row.asset() else {
184                continue;
185            };
186            let object = env.deref(&item.file, ptr)?;
187            let path = item.row.path.unwrap_or_default();
188            entries.push(Entry {
189                object,
190                path,
191                ordinal: entries.len(),
192            })?;
193        }
194    } else {
195        for item in env.objects() {
196            entries.push(Entry {
197                object: item?,
198                path: RawStr::default(),
199                ordinal: entries.len(),
200            })?;
201        }
202    }
203    meter.count_decode(
204        (entries.len() as u64).saturating_mul(1 + u64::from(entries.len().bit_width())),
205    )?;
206    entries
207        .as_mut_slice()
208        .sort_unstable_by_key(|e| (priority(e.object.class_id()), e.ordinal));
209    for entry in entries.as_slice() {
210        let obj = &entry.object;
211        if let Some(filter) = options.asset_filter {
212            meter.count_decode(filter.lookup_work())?;
213            if !filter.accepts(obj, None) {
214                continue;
215            }
216        }
217        if !options.use_container && was_exported(report.exported.as_slice(), obj, meter)? {
218            continue;
219        }
220        let path = if options.use_container {
221            paths::container(
222                entry.path.as_bytes(),
223                options.ignore_first_container_dirs,
224                meter,
225            )
226        } else {
227            Ok(RawStr::default())
228        };
229        match path {
230            Ok(path) => export_obj(
231                env,
232                obj,
233                path.as_bytes(),
234                !options.use_container,
235                options,
236                sink,
237                meter,
238                &mut report,
239            )?,
240            Err(error) => report.failures.push(Failure {
241                object: obj.clone(),
242                path: entry.path.clone(),
243                error,
244            })?,
245        }
246    }
247    Ok(report)
248}
249/// Export one object, appending its name when requested. Recoverable failures
250/// are appended to `report`; report allocation failures return Err.
251#[allow(clippy::too_many_arguments)]
252pub fn export_obj(
253    env: &Environment,
254    obj: &ObjectRef,
255    path: &[u8],
256    append_name: bool,
257    options: &Options<'_>,
258    sink: &mut dyn Sink,
259    meter: &Arc<Meter>,
260    report: &mut Report,
261) -> Result<(), Error> {
262    if let Err(error) = one(
263        env,
264        obj,
265        path,
266        append_name,
267        options,
268        sink,
269        meter,
270        report,
271        false,
272    ) {
273        report.failures.push(Failure {
274            object: obj.clone(),
275            path: RawStr::charged(path, meter)?,
276            error,
277        })?;
278    }
279    Ok(())
280}
281fn name<'a>(obj: &ObjectRef, parsed: Option<&'a Parsed>) -> Result<&'a [u8], Error> {
282    match parsed.and_then(|p| p.value().as_dict().and_then(|m| p.attr(m, b"m_Name"))) {
283        Some(Value::Str(s)) => Ok(s.as_bytes()),
284        Some(_) => Err(Error::Field("m_Name")),
285        None => Ok(unityrs_core::classid::class_name(obj.class_id())
286            .unwrap_or("UnknownType")
287            .as_bytes()),
288    }
289}
290#[allow(clippy::too_many_arguments, clippy::too_many_lines)]
291fn one(
292    env: &Environment,
293    obj: &ObjectRef,
294    path: &[u8],
295    append_name: bool,
296    options: &Options<'_>,
297    sink: &mut dyn Sink,
298    meter: &Arc<Meter>,
299    report: &mut Report,
300    crawl_id: bool,
301) -> Result<(), Error> {
302    if !EXPORT_TYPES.contains(&obj.class_id()) && !options.export_unknown_as_typetree {
303        return Ok(());
304    }
305    paths::validate(path)?;
306    let parsed = match simple::read(obj, env) {
307        Ok(p) => Some(p),
308        Err(e)
309            if (obj.class_id() == 114 || options.export_unknown_as_typetree)
310                && simple::read_failed(&e) =>
311        {
312            None
313        }
314        Err(e) => return Err(e.into()),
315    };
316    if let Some(filter) = options.asset_filter {
317        meter.count_decode(filter.lookup_work())?;
318        if !filter.accepts(obj, parsed.as_ref()) {
319            return Ok(());
320        }
321    }
322    let path = if append_name {
323        paths::join(path, name(obj, parsed.as_ref())?, meter)?
324    } else {
325        RawStr::charged(path, meter)?
326    };
327    let (stem, extension) = paths::split(path.as_bytes());
328    let mut numbered = obj::ChargedBytes::new(meter);
329    let stem = if options.append_path_id {
330        numbered.write_bytes(stem)?;
331        if crawl_id {
332            numbered.write_args(format_args!("_{}", obj.path_id()))?;
333        } else {
334            numbered.write_bytes(b"_None")?;
335        }
336        numbered.as_bytes()
337    } else {
338        stem
339    };
340    match obj.class_id() {
341        1 => {
342            crawl::export(env, obj, stem, options, sink, meter, report)?;
343            return Ok(());
344        }
345        28 | 213 => {
346            let (image, texture) = images::image(
347                env,
348                obj,
349                parsed.as_ref().ok_or(Error::Field("image tree"))?,
350                meter,
351            )?;
352            images::save(
353                obj,
354                parsed.as_ref().ok_or(Error::Field("image tree"))?,
355                &image,
356                stem,
357                extension,
358                sink,
359                meter,
360                report,
361            )?;
362            report.exported.push(obj.into())?;
363            if let Some(texture) = texture {
364                report.exported.push(texture)?;
365            }
366            return Ok(());
367        }
368        83 => {
369            let samples = audio::export_with_vorbis(obj, env, true, options.vorbis, meter)?;
370            if samples.len() == 1 {
371                if let Some(sample) = samples.as_slice().first() {
372                    write(
373                        obj,
374                        stem,
375                        b".wav",
376                        sample.bytes.as_slice(),
377                        sink,
378                        meter,
379                        report,
380                    )?;
381                }
382            } else if !samples.is_empty() {
383                sink.directory(stem)?;
384                for sample in samples.as_slice() {
385                    let name = paths::join(stem, sample.name.as_slice(), meter)?;
386                    write(
387                        obj,
388                        name.as_bytes(),
389                        b".wav",
390                        sample.bytes.as_slice(),
391                        sink,
392                        meter,
393                        report,
394                    )?;
395                }
396            }
397        }
398        43 => {
399            let mesh = unityrs_mesh::read_mesh_for_obj(obj, env, meter)?;
400            if let Some(bytes) = obj::export_mesh_obj_owned(&mesh, None, meter)? {
401                write(
402                    obj,
403                    stem,
404                    default_ext(extension, b".obj"),
405                    bytes.as_bytes(),
406                    sink,
407                    meter,
408                    report,
409                )?;
410            }
411        }
412        48 => {
413            let bytes = shader::export(obj, env, meter)?;
414            write(
415                obj,
416                stem,
417                default_ext(extension, b".txt"),
418                bytes.as_slice(),
419                sink,
420                meter,
421                report,
422            )?;
423        }
424        49 | 128 | 114 => {
425            if let Some(payload) = simple::export(obj, env, "", meter)? {
426                let suffix = if obj.class_id() == 49 {
427                    default_ext(extension, b".txt")
428                } else {
429                    payload.extension.as_bytes()
430                };
431                write(
432                    obj,
433                    stem,
434                    suffix,
435                    payload.bytes.as_slice(),
436                    sink,
437                    meter,
438                    report,
439                )?;
440            }
441        }
442        _ => {
443            if let Some(parsed) = parsed.as_ref() {
444                match simple::json(parsed, meter) {
445                    Ok(bytes) => write(obj, stem, b".json", bytes.as_slice(), sink, meter, report)?,
446                    Err(simple::Error::Json(crate::pyjson::WriteError::Unwritable(_))) => {
447                        let bytes = obj.raw_data()?;
448                        write(obj, stem, b".bin", &bytes, sink, meter, report)?;
449                    }
450                    Err(e) => return Err(e.into()),
451                }
452            } else {
453                let bytes = obj.raw_data()?;
454                write(obj, stem, b".bin", &bytes, sink, meter, report)?;
455            }
456        }
457    }
458    report.exported.push(obj.into())?;
459    Ok(())
460}
461fn default_ext<'a>(extension: &'a [u8], default: &'a [u8]) -> &'a [u8] {
462    if extension.is_empty() {
463        default
464    } else {
465        extension
466    }
467}
468#[allow(clippy::too_many_arguments)]
469fn write(
470    obj: &ObjectRef,
471    stem: &[u8],
472    ext: &[u8],
473    bytes: &[u8],
474    sink: &mut dyn Sink,
475    meter: &Arc<Meter>,
476    report: &mut Report,
477) -> Result<(), Error> {
478    let path = paths::suffix(stem, ext, meter)?;
479    // Reserve the report before publishing, so every completed write is reportable.
480    report.written.reserve(1)?;
481    meter.count_decode(bytes.len() as u64)?;
482    sink.file(path.as_bytes(), bytes)?;
483    report.written.push(Written {
484        object: obj.clone(),
485        path,
486        size: bytes.len() as u64,
487    })?;
488    Ok(())
489}