Expand description
A Mesh’s or a sprite’s vertex arrays, index buffer and triangles, as
UnityPy 1.25.2’s MeshHandler gives them (docs/plans/extract.md E16;
PARITY.md section 15.3’s rows marked P1b): the same values, the same
types (float as f64, int), and the same exceptions where it
raises.
Source: what the handler reads, a Mesh object’s value or a Sprite’s render data, from the core’s typetree read, viewed as UnityPy’s object mode builds it (unityrs_core::objmode).MeshHandler::process: the channels and streams by version, a Mesh’sm_StreamDatathroughResources, the index size and buffer, and each channel’s data, through the threeVertexFormattables (get_channel_dtype) and UnityPyBoost’s strided gather (unpack_vertexdata), into aProcessed. A Mesh’sCompressedMeshis unpacked (PackedBitVector’sunpack_intsandunpack_floats, thendecompress_compressed_mesh) with UnityPy’s two Tier C errors there corrected (compressed’s module docs).Processed::get_triangles: each submesh’s triangles, for triangle lists, strips and quads, with UnityPy’s errors for the rest.
What is not here (docs/plans/extract.md E16). A Mesh’s own vertex
arrays and a sprite’s own vertices, which no version’s typetree holds
beside m_VertexData, are P4’s (docs/plans/static3d.md, decision 2); below Unity 4, get_channels’
fixed layout is P4. Each is MeshError::Unsupported, returned where
UnityPy would begin it, so every failure before it is UnityPy’s.
Divergences (PARITY.md sections 15.3, 19.1 and 19.3): a compressed
mesh’s third and later UV channels read from where the ones before end,
a skin’s fourth weight in 31sts, and a Mesh’s UNorm, SNorm and byte
colour channels normalised to floats (its blend indices, and a
Sprite’s channels, kept as UnityPy’s integers), where UnityPy errs
(Tier C); a
packed item wider than 32 bits is MeshError::Malformed; an array or a
loop past the caller’s meter is MeshError::Charge; a gather whose
32-bit offsets wrap past UnityPyBoost’s check, where UnityPy reads or
writes out of bounds, is MeshError::WrappedAccess; a field of a type
or range no version’s typetree gives it, or a class node of another
type, is MeshError::Malformed; and the core’s resource read reports
its own errors (MeshError::Resource). The handler changes nothing it
reads: UnityPy’s process sets a streamed Mesh’s m_DataSize and leaves
its results on the handler for a second call to read, and its
get_triangles rewrites a strip’s indexCount, which
SubMeshTriangles::index_count returns instead; so each call here
gives the first’s answer.
No panics, bounded work (docs/plans/core.md section 3.15): indexing,
unwrap and the like are denied outside tests; offsets are computed as
UnityPyBoost computes them, in wrapping u32s, and checked. Every array
sized by the input (the values, the index buffer, the triangles, the
derived streams) is charged to the caller’s meter, at its element count,
before it is allocated, and a message echoes at most 64 bytes of a type
name. Every loop’s work is counted on the meter before the loop runs, and
after the charge that loop’s output needs, so a refused charge counts no
work: a unit per byte or element of output, per channel (those skipped
included), per submesh, and for every name a scan of a class’s fields may
compare, counted before it, so the work is in proportion to the input or
the output.
tests/oracle.rs replays what the oracle recorded
(tools/fixtures/meshdecode.py); tests/limits.rs runs each recorded
case under smaller meters and work bounds, and with its bytes changed;
tests/charges.rs counts the allocations each case makes against its
charges; and tests/work.rs measures the work against the channels,
submeshes and fields read.
Structs§
- Component
Bytes - UnityPyBoost’s output: the gathered components, each of 2 or 4 bytes swapped when asked.
- File
Resources - The core’s resource read from an object’s file:
Environment::resource, its port ofget_resource_data. - Gather
- The arguments of
UnityPyBoost.unpack_vertexdataafter Python’s conversion to C (UnityPyBoost/Mesh.cpp:26-43): each auint32_t, the component size anintthat the arithmetic converts to one. - Index
Buffer - The unpacked index buffer (
m_IndexBufferafterprocess). - Mesh
Handler MeshHandler(src, version)(helpers/MeshHelper.py:71-108).- Processed
- What
process()leaves on the handler: the vertex count, the index size and buffer, and the attributes the channels and the skin filled. - Processed
Owned - A processed mesh independent of its parsed source. Each buffer retains its charge.
- Source
- What the handler is given: a Mesh, or a Sprite’s render data, read when the handler runs.
- SubMesh
Triangles - One submesh’s list of index tuples (module docs): the whole triangles, then at most one tuple a triangle list’s buffer cut short, then empty tuples.
- Triangles
get_triangles()’s list: oneSubMeshTrianglesper submesh.- Version
- The version a handler reads (module docs).
- Vertex
Array - One attribute:
len()tuples ofdimension()components, asstruct.iter_unpack(or the copy of aMesh’s skin) gives them, the values flat in tuple order. A compressed mesh’s arrays arePackedBitVector.reshape’s lists, whose last tuple may be cut short: it is a tuple here too, of the components it holds.
Enums§
- Component
- One component of a
VertexArray’s tuple (VertexArray::component). - Format
Table - The three tables, as
get_channel_dtypepicks one by version. - GfxPrimitive
Type GfxPrimitiveType(enums/GfxPrimitiveType.py:4-10), the same values under the engine’s names; nothing in UnityPy reads it.- Index
Kind - An
IndexError, by its message. - Mesh
Error - A failure of the mesh handler (module docs).
- Mesh
Topology MeshTopology(enums/MeshTopology.py:4-10), aSubMesh’stopology, whichget_trianglescompares with (helpers/MeshHelper.py:646,:651,:668).- Norm
- A normalised format’s rule (module docs, Tier C): how unityrs reads a
Mesh’s integer of that format as a
float. - Struct
Code - A
structcodeget_channel_dtypegives: how one component is read. - Struct
Error - A
struct.errorPython 3.11 raises, by its message. - Unsupported
- A part of
MeshHandlerthis crate leaves to a later phase (docs/plans/extract.mdE16,PARITY.mdsection 15.3). - Values
- An attribute’s values: Python
floats, asf64, orints, flat in tuple order. - Vertex
Channel Format VertexChannelFormat, the formats below Unity 2017 (enums/VertexFormat.py:4-9).- Vertex
Format VertexFormat, the formats from Unity 2019 (enums/VertexFormat.py:28-40).- Vertex
Format2017 VertexFormat2017, the formats of Unity 2017 and 2018 (enums/VertexFormat.py:12-25).
Traits§
- Resources
- Where a Mesh’s
m_StreamDatabytes come from: UnityPy’sget_resource_data(path, assets_file, offset, size)(helpers/ResourceReader.py:10-38) from the Mesh’s own file.
Functions§
- get_
channel_ component_ size MeshHandler.get_channel_component_size(helpers/MeshHelper.py:464-466): the bytes of one component of a channel informat.- get_
channel_ dtype MeshHandler.get_channel_dtype(helpers/MeshHelper.py:451-462): the struct code of a channel’sformatunderversion’s table, or UnityPy’sValueErrorfor a format the table’s enum lacks.- unpack_
vertexdata UnityPyBoost.unpack_vertexdata(data, ...)(UnityPyBoost/Mesh.cpp:23-210): the gather, its check and its swap (module docs), the output charged tometerbefore it is allocated and counted as decode work.