unityrs-meshdecode 1.1.0

UnityPy 1.25.2's MeshHandler vertex-data unpack, index formats and get_triangles, for meshes and sprites.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
// Ported from UnityPy 1.25.2 (MIT): UnityPy/helpers/MeshHelper.py's MeshHandler.get_streams, read_vertex_data and assign_channel_vertex_data. See THIRD_PARTY_LICENSES.
//! The channels' and streams' layout, and each channel's data unpacked
//! into its attribute.
//!
//! **Streams** (`get_streams`, `helpers/MeshHelper.py:256-281`). From 5,
//! the handler derives the streams from the channels: as many as the
//! highest stream a channel names, plus one; each stream's stride is the
//! sum, over its channels of a non-zero dimension, of the dimension's low
//! four bits times the format's component size, and the streams follow
//! one another, each offset rounded up to 16. UnityPy visits every stream
//! and, within it, every channel, reading each channel's `dimension` and,
//! when it is not 0, its format, so a channel's missing field or a format
//! the version's enum lacks raises at the first stream, then channel, that
//! has one. [`get_streams`] reads each channel once and keeps the first
//! failure in that order, so it runs in the channels' count, not times the
//! streams'. At 4, the streams are the file's own (`StreamInfo`s).
//!
//! **Each channel** (`read_vertex_data`, `:323-393`). Nothing is read when
//! the vertex count is 0 or the data empty. A channel of dimension 0 is
//! skipped; any other is read when its bit is set in its stream's mask,
//! which UnityPy tests on the string `bin(channelMask)[::-1]`, so a channel
//! past the mask's highest bit reads `b` and then `0`, and one further on
//! raises `IndexError` ([`mask_bit`]); a derived stream's mask has the bit
//! of every channel of a non-zero dimension it holds. Below 2018 the colour
//! channel (2) of format 2 is read as 4 components whatever its
//! dimension (`:348-357`). The data is then gathered ([`crate::unpack`]),
//! and assigned by channel index ([`assign`]). A Mesh's channel in a
//! `UNorm`, `SNorm` or byte colour format is normalised to `float`s, where
//! UnityPy keeps the integers (`PARITY.md` section 19.1, Tier C;
//! `crate::format`'s module docs); the blend indices, bone indices whatever
//! their format, and a Sprite's render data keep them.
//!
//! **Work.** [`get_streams`] counts one unit a channel before its two
//! passes, and charges the streams it derives before it allocates them;
//! [`read_vertex_data`] counts one unit a channel, those of dimension 0 it
//! skips included, before its loop; and every field read counts its scans
//! ([`unityrs_core::objmode`]).

use std::sync::Arc;

use unityrs_core::limits::{Charge, Meter, MeteredVec};

use crate::Version;
use crate::error::{IndexKind, MeshError};
use crate::format::{FormatTable, get_channel_dtype};
use crate::unpack::{Gather, VertexArray, unpack_channel};
use unityrs_core::objmode::{List, Obj};

/// The most streams a mesh can have: a channel's `stream` is a `UInt8`, so
/// a derived layout has at most 256, a fixed bound.
const MAX_STREAMS: usize = 256;

/// A stream derived by [`get_streams`]: its offset and stride, Python
/// `int`s (unbounded there, so a `u128` and a `u64` here), and implicitly
/// the mask of its channels.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub(crate) struct DerivedStream {
    pub(crate) offset: u128,
    pub(crate) stride: u64,
}

/// Where each channel's stream comes from.
#[derive(Debug)]
pub(crate) enum Streams<'a> {
    /// Derived from the channels (5 and up), at most [`MAX_STREAMS`], with
    /// the charge for their memory.
    Derived {
        streams: Vec<DerivedStream>,
        // Declared last: the charge is returned after the streams are freed.
        _charge: Charge,
    },
    /// The file's own `m_Streams` (4.x).
    File(List<'a>),
}

/// The attributes the channels fill, as the handler's fields are named.
#[derive(Debug, Default)]
pub(crate) struct Attributes {
    pub(crate) vertices: Option<VertexArray>,
    pub(crate) normals: Option<VertexArray>,
    pub(crate) tangents: Option<VertexArray>,
    pub(crate) colors: Option<VertexArray>,
    pub(crate) uv: [Option<VertexArray>; 8],
    pub(crate) bone_weights: Option<VertexArray>,
    pub(crate) bone_indices: Option<VertexArray>,
    /// `m_BindPose`, which only `decompress_compressed_mesh` sets.
    pub(crate) bind_pose: Option<VertexArray>,
}

/// A required integer field: absent only on an `UnknownObject`, which
/// [`Obj::get`] has refused, so `None` is a value missing from the dict.
pub(crate) fn field(obj: &Obj<'_>, name: &'static str, max: u64) -> Result<u64, MeshError> {
    obj.uint(name, max)?.ok_or(MeshError::NoAttribute(name))
}

/// `get_streams(m_Channels, m_VertexCount)` (`helpers/MeshHelper.py:256-281`,
/// module docs).
pub(crate) fn get_streams(
    version: Version,
    channels: &List<'_>,
    vertex_count: u64,
    meter: &Arc<Meter>,
) -> Result<Streams<'static>, MeshError> {
    // Each channel is read once in each of the two loops below, in a fixed
    // amount of work.
    meter.count_decode(u64::try_from(channels.len()).unwrap_or(u64::MAX))?;
    // UnityPy MeshHelper.py:257: `max` reads every channel's `stream`.
    let mut highest: Option<u64> = None;
    for ch in channels.iter() {
        let s = field(&ch?, "stream", 255)?;
        highest = Some(highest.map_or(s, |h| h.max(s)));
    }
    let count = usize::try_from(highest.ok_or(MeshError::NoChannels)?).unwrap_or(0) + 1;
    // UnityPy MeshHelper.py:261-268: stream `s` visits each of its
    // channels in order; the first failure by (stream, channel) is the one
    // UnityPy raises.
    let mut strides = [0u64; MAX_STREAMS];
    let mut first: Option<(u64, MeshError)> = None;
    for ch in channels.iter() {
        let ch = ch?;
        let s = field(&ch, "stream", 255)?;
        let stride = (|| {
            let dim = field(&ch, "dimension", 255)?;
            if dim == 0 {
                return Ok(0);
            }
            let format = u8::try_from(field(&ch, "format", 255)?).unwrap_or(u8::MAX);
            let size = get_channel_dtype(version, format)?.size();
            Ok((dim & 0xF) * u64::from(size))
        })();
        match stride {
            Ok(add) => {
                if let Some(slot) = usize::try_from(s).ok().and_then(|i| strides.get_mut(i)) {
                    *slot = slot.saturating_add(add);
                }
            }
            // The channels are visited in order, so the first failure of a
            // stream is the earliest of its channels.
            Err(e) => {
                if first.as_ref().is_none_or(|(at, _)| s < *at) {
                    first = Some((s, e));
                }
            }
        }
    }
    if let Some((_, e)) = first {
        return Err(e);
    }
    // UnityPy MeshHelper.py:270-280: each stream after the last, at the
    // next multiple of 16.
    let mut streams = MeteredVec::<DerivedStream>::with_capacity(meter, count)?;
    let mut offset: u128 = 0;
    for &stride in strides.get(..count).unwrap_or(&[]) {
        streams.push(DerivedStream { offset, stride })?;
        offset = offset.saturating_add(u128::from(vertex_count) * u128::from(stride));
        offset = offset.saturating_add(15) & !15;
    }
    let (streams, charge) = streams.into_parts();
    Ok(Streams::Derived {
        streams,
        _charge: charge,
    })
}

/// `bin(channelMask)[::-1][chn] == "1"` (`helpers/MeshHelper.py:346-347`):
/// the bit for a channel below the mask's length in bits (1 for a mask of
/// 0), `b` then `0` for the next two, `IndexError` past them.
pub(crate) fn mask_bit(mask: u64, chn: usize) -> Result<bool, MeshError> {
    let bits = usize::try_from(mask.bit_width()).unwrap_or(0).max(1);
    if chn >= bits + 2 {
        return Err(MeshError::Index(IndexKind::Str));
    }
    Ok(chn < bits && (mask >> chn) & 1 == 1)
}

/// The vertex data a handler reads: its `m_VertexData`, and the bytes
/// `m_StreamData` put in place of its `m_DataSize`.
#[derive(Clone, Copy, Debug)]
pub(crate) struct VertexData<'a> {
    pub(crate) obj: Obj<'a>,
    pub(crate) streamed: Option<&'a [u8]>,
}

/// `read_vertex_data(m_Channels, m_Streams)` (`helpers/MeshHelper.py:323-393`,
/// module docs): the vertex count it sets, if it reads at all. `normalise`
/// (a Mesh's, not a Sprite's) reads each normalised format's integers as
/// `float`s (Tier C).
#[allow(clippy::too_many_arguments)] // The handler's state, each its own.
pub(crate) fn read_vertex_data(
    version: Version,
    little: bool,
    normalise: bool,
    vertex_data: VertexData<'_>,
    channels: &List<'_>,
    streams: &Streams<'_>,
    attrs: &mut Attributes,
    meter: &Arc<Meter>,
) -> Result<Option<u64>, MeshError> {
    let vd = vertex_data.obj;
    // UnityPy MeshHelper.py:331-332: no count, or no data, reads nothing.
    let count = field(&vd, "m_VertexCount", u64::from(u32::MAX))?;
    if count == 0 {
        return Ok(None);
    }
    let data = match vertex_data.streamed {
        Some(b) => b,
        None => vd
            .bytes("m_DataSize")?
            .ok_or(MeshError::NoAttribute("m_DataSize"))?,
    };
    if data.is_empty() {
        return Ok(None);
    }
    let vertex_count = u32::try_from(count).unwrap_or(u32::MAX);
    // One unit a channel, the ones skipped included.
    meter.count_decode(u64::try_from(channels.len()).unwrap_or(u64::MAX))?;
    for (chn, ch) in channels.iter().enumerate() {
        let ch = ch?;
        // UnityPy MeshHelper.py:338-339
        if field(&ch, "dimension", 255)? == 0 {
            continue;
        }
        let stream = field(&ch, "stream", 255)?;
        let stream = usize::try_from(stream).unwrap_or(usize::MAX);
        // UnityPy MeshHelper.py:338-347: the stream, and its mask's bit.
        let file_stream = match streams {
            Streams::Derived { .. } => None,
            Streams::File(list) => {
                let s = list
                    .get(stream)
                    .ok_or(MeshError::Index(IndexKind::List))??;
                let mask = field(&s, "channelMask", u64::from(u32::MAX))?;
                if !mask_bit(mask, chn)? {
                    continue;
                }
                Some(s)
            }
        };
        // UnityPy MeshHelper.py:348-357: below 2018 the colour channel of
        // format 2 is a new `ChannelInfo` of dimension 4, which reads the
        // channel's offset (and its stream, read above).
        let colour = version.major()? < 2018 && chn == 2 && field(&ch, "format", 255)? == 2;
        let (dimension, format) = if colour {
            field(&ch, "offset", 255)?;
            (4, 2)
        } else {
            (field(&ch, "dimension", 255)?, field(&ch, "format", 255)?)
        };
        // UnityPy MeshHelper.py:359-364
        let format = u8::try_from(format).unwrap_or(u8::MAX);
        let code = get_channel_dtype(version, format)?;
        // PARITY.md section 19.1 (Tier C): UnityPy keeps the integers. The
        // blend indices are bone indices, integers whatever their format.
        let major = version.major()?;
        let norm = if normalise && !is_blend_indices(major, chn) {
            FormatTable::for_major(major).norm(format)
        } else {
            None
        };
        let size = code.size();
        let swap = little && size > 1;
        let channel_dimension = u32::try_from(dimension & 0xF).unwrap_or(0);
        // UnityPy MeshHelper.py:366-376: the stream's offset and stride,
        // then the channel's offset, each masked to 32 bits by `I`.
        let (stream_offset, stream_stride) = match (file_stream, streams) {
            (Some(s), _) => (
                field(&s, "offset", u64::from(u32::MAX))?,
                field(&s, "stride", u64::from(u32::MAX))?,
            ),
            (None, Streams::Derived { streams: v, .. }) => {
                let s = v.get(stream).copied().unwrap_or_default();
                (low32(s.offset), low32(u128::from(s.stride)))
            }
            (None, Streams::File(_)) => (0, 0),
        };
        let channel_offset = field(&ch, "offset", 255)?;
        let args = Gather {
            component_byte_size: size,
            vertex_count,
            stream_offset: u32::try_from(stream_offset).unwrap_or(0),
            stream_stride: u32::try_from(stream_stride).unwrap_or(0),
            channel_offset: u32::try_from(channel_offset).unwrap_or(0),
            channel_dimension,
            swap,
        };
        let array = unpack_channel(data, &args, code, norm, meter)?;
        assign(version, chn, array, attrs)?;
    }
    Ok(Some(count))
}

/// Whether channel `chn` holds the blend indices: channel 13 from 2018
/// ([`assign`]'s `m_BoneIndices`); below, the vertex data holds none (the
/// skin's indices come from `m_Skin`).
fn is_blend_indices(major: u16, chn: usize) -> bool {
    major >= 2018 && chn == 13
}

/// An `int`'s low 32 bits, as Python's `I` format takes them.
fn low32(v: u128) -> u64 {
    u64::try_from(v & 0xFFFF_FFFF).unwrap_or(0)
}

/// `assign_channel_vertex_data(channel, data)` (`helpers/MeshHelper.py:395-449`):
/// from 2018, channels 0 to 13 are the position, normal, tangent, colour,
/// eight UVs, bone weights and bone indices; below, 0 to 7 are the
/// position, normal, colour, UV0, UV1, then UV2 from 5 (the tangent below
/// 5), UV3 and the tangent. Any other raises `ValueError`.
pub(crate) fn assign(
    version: Version,
    channel: usize,
    data: VertexArray,
    attrs: &mut Attributes,
) -> Result<(), MeshError> {
    let major = version.major()?;
    let slot = if major >= 2018 {
        match channel {
            0 => &mut attrs.vertices,
            1 => &mut attrs.normals,
            2 => &mut attrs.tangents,
            3 => &mut attrs.colors,
            4..=11 => uv(attrs, channel - 4),
            12 => &mut attrs.bone_weights,
            13 => &mut attrs.bone_indices,
            _ => return Err(unknown(channel)),
        }
    } else {
        match channel {
            0 => &mut attrs.vertices,
            1 => &mut attrs.normals,
            2 => &mut attrs.colors,
            3 => uv(attrs, 0),
            4 => uv(attrs, 1),
            5 if major >= 5 => uv(attrs, 2),
            5 | 7 => &mut attrs.tangents,
            6 => uv(attrs, 3),
            _ => return Err(unknown(channel)),
        }
    };
    *slot = Some(data);
    Ok(())
}

fn uv(attrs: &mut Attributes, i: usize) -> &mut Option<VertexArray> {
    let [u0, u1, u2, u3, u4, u5, u6, u7] = &mut attrs.uv;
    match i {
        0 => u0,
        1 => u1,
        2 => u2,
        3 => u3,
        4 => u4,
        5 => u5,
        6 => u6,
        _ => u7,
    }
}

fn unknown(channel: usize) -> MeshError {
    MeshError::UnknownChannel(u64::try_from(channel).unwrap_or(u64::MAX))
}

/// The checks `read_vertex_data` makes of each channel before it reads a
/// byte (`helpers/MeshHelper.py:338-364`): a 4.x channel's stream and its
/// mask's bit, the colour channel's offset below 2018, and each format,
/// offsets and stride, and each slot (`helpers/MeshHelper.py:395-449`). A
/// caller that reads a streamed Mesh's resource itself
/// ([`crate::Resources::reads_range`]) has them run before the read, so a
/// Mesh they refuse opens nothing; UnityPy reads the resource first.
pub(crate) fn check_channels(
    version: Version,
    vd: &Obj<'_>,
    channels: &List<'_>,
    streams: &Streams<'_>,
    meter: &Arc<Meter>,
) -> Result<(), MeshError> {
    if field(vd, "m_VertexCount", u64::from(u32::MAX))? == 0 {
        return Ok(());
    }
    meter.count_decode(u64::try_from(channels.len()).unwrap_or(u64::MAX))?;
    for (chn, ch) in channels.iter().enumerate() {
        let ch = ch?;
        if field(&ch, "dimension", 255)? == 0 {
            continue;
        }
        let stream = usize::try_from(field(&ch, "stream", 255)?).unwrap_or(usize::MAX);
        let mut file_stream = None;
        if let Streams::File(list) = streams {
            let s = list
                .get(stream)
                .ok_or(MeshError::Index(IndexKind::List))??;
            if !mask_bit(field(&s, "channelMask", u64::from(u32::MAX))?, chn)? {
                continue;
            }
            file_stream = Some(s);
        }
        let colour = version.major()? < 2018 && chn == 2 && field(&ch, "format", 255)? == 2;
        let format = if colour {
            field(&ch, "offset", 255)?;
            2
        } else {
            field(&ch, "dimension", 255)?;
            field(&ch, "format", 255)?
        };
        get_channel_dtype(version, u8::try_from(format).unwrap_or(u8::MAX))?;
        if let Some(s) = file_stream {
            field(&s, "offset", u64::from(u32::MAX))?;
            field(&s, "stride", u64::from(u32::MAX))?;
        }
        field(&ch, "offset", 255)?;
        // The slot [`assign`] fills: an unknown channel fails there.
        let known = if version.major()? >= 2018 { 14 } else { 8 };
        if chn >= known {
            return Err(unknown(chn));
        }
    }
    Ok(())
}

#[cfg(test)]
mod tests {
    use super::mask_bit;
    use crate::error::{IndexKind, MeshError};

    #[test]
    fn the_mask_is_read_as_its_reversed_binary_string() {
        // bin(0b101)[::-1] == "101b0"
        assert!(mask_bit(0b101, 0).unwrap());
        assert!(!mask_bit(0b101, 1).unwrap());
        assert!(mask_bit(0b101, 2).unwrap());
        assert!(!mask_bit(0b101, 3).unwrap());
        assert!(!mask_bit(0b101, 4).unwrap());
        assert!(matches!(
            mask_bit(0b101, 5),
            Err(MeshError::Index(IndexKind::Str))
        ));
        // bin(0)[::-1] == "0b0"
        assert!(!mask_bit(0, 0).unwrap());
        assert!(!mask_bit(0, 2).unwrap());
        assert!(mask_bit(0, 3).is_err());
        assert!(mask_bit(u64::from(u32::MAX), 31).unwrap());
        assert!(!mask_bit(u64::from(u32::MAX), 33).unwrap());
        assert!(mask_bit(u64::from(u32::MAX), 34).is_err());
    }
}