Skip to main content

Crate unityrs_meshdecode

Crate unityrs_meshdecode 

Source
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’s m_StreamData through Resources, the index size and buffer, and each channel’s data, through the three VertexFormat tables (get_channel_dtype) and UnityPyBoost’s strided gather (unpack_vertexdata), into a Processed. A Mesh’s CompressedMesh is unpacked (PackedBitVector’s unpack_ints and unpack_floats, then decompress_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§

ComponentBytes
UnityPyBoost’s output: the gathered components, each of 2 or 4 bytes swapped when asked.
FileResources
The core’s resource read from an object’s file: Environment::resource, its port of get_resource_data.
Gather
The arguments of UnityPyBoost.unpack_vertexdata after Python’s conversion to C (UnityPyBoost/Mesh.cpp:26-43): each a uint32_t, the component size an int that the arithmetic converts to one.
IndexBuffer
The unpacked index buffer (m_IndexBuffer after process).
MeshHandler
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.
ProcessedOwned
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.
SubMeshTriangles
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: one SubMeshTriangles per submesh.
Version
The version a handler reads (module docs).
VertexArray
One attribute: len() tuples of dimension() components, as struct.iter_unpack (or the copy of a Mesh’s skin) gives them, the values flat in tuple order. A compressed mesh’s arrays are PackedBitVector.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).
FormatTable
The three tables, as get_channel_dtype picks one by version.
GfxPrimitiveType
GfxPrimitiveType (enums/GfxPrimitiveType.py:4-10), the same values under the engine’s names; nothing in UnityPy reads it.
IndexKind
An IndexError, by its message.
MeshError
A failure of the mesh handler (module docs).
MeshTopology
MeshTopology (enums/MeshTopology.py:4-10), a SubMesh’s topology, which get_triangles compares 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.
StructCode
A struct code get_channel_dtype gives: how one component is read.
StructError
A struct.error Python 3.11 raises, by its message.
Unsupported
A part of MeshHandler this crate leaves to a later phase (docs/plans/extract.md E16, PARITY.md section 15.3).
Values
An attribute’s values: Python floats, as f64, or ints, flat in tuple order.
VertexChannelFormat
VertexChannelFormat, the formats below Unity 2017 (enums/VertexFormat.py:4-9).
VertexFormat
VertexFormat, the formats from Unity 2019 (enums/VertexFormat.py:28-40).
VertexFormat2017
VertexFormat2017, the formats of Unity 2017 and 2018 (enums/VertexFormat.py:12-25).

Traits§

Resources
Where a Mesh’s m_StreamData bytes come from: UnityPy’s get_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 in format.
get_channel_dtype
MeshHandler.get_channel_dtype (helpers/MeshHelper.py:451-462): the struct code of a channel’s format under version’s table, or UnityPy’s ValueError for 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 to meter before it is allocated and counted as decode work.