Crate unity_formats 

Readers for the data files of Unity players: the SerializedFiles a built game keeps its scenes and assets in, and the objects inside them (scenes, meshes, textures, materials, shader programs, terrains, Animator data).

A built Unity game keeps its scenes and assets in SerializedFiles (globalgamemanagers, *.assets, levelN), with the bulk data (textures, meshes, audio) in .resS stream files beside them. A player build strips the type trees that say how each class is laid out, so objects are decoded with a type tree package (a TPK file) that the caller supplies. The crate was written against Unity 2019.4 and Unity 6 players (SkateBIRD, Sledding Game, PEAK); what it refuses to read is named in each module.

use std::path::Path;
use unity_formats::{TypeTreePackage, listing::list, mesh::UnityMeshData, player::Player};

let package = TypeTreePackage::parse(&std::fs::read("typetrees.tpk")?)?;
let player = Player::open(Path::new("Game_Data"), package)?;
for scene in player.scenes()? {
    println!("{}: {}", scene.file, scene.name);
}
for entry in list(&player, Some(&["Mesh"]))?.entries.iter().take(3) {
    let mesh = UnityMeshData::read(&player, &entry.object)?;
    println!("{}: {} vertices", mesh.name, mesh.vertex_count);
}

The modules:

• bundle: UnityFS bundles (AssetBundles, Addressables content, a player’s data.unity3d): the block table and directory, nodes read by range.
• serialized: the SerializedFile container: header, types, the object table, script references, external files. Strict and version-gated: only container versions verified against real data are read.
• tpk: a type tree package (the TPK format), the class layouts per Unity version that a player build strips from its files. The caller supplies the package; none is bundled.
• typetree: decoding an object’s bytes by its class’s type tree into a Value tree.
• value: the decoded value tree.
• version: Unity version strings.
• resource: streamed resources (.resS), the bulk data that objects point at.
• player: a player’s data folder: its files, pointers resolved across them, its quality levels, its build’s scene list and render pipeline.
• scene: a scene’s hierarchy (GameObjects, Transforms composed to world matrices) and its renderers, lights, cameras, colliders and terrains, with the scene’s ambient and fog settings.
• mesh: meshes (vertex streams, compressed meshes, index buffers, submeshes, skins and blend shapes).
• texture: textures (formats, mip chains, sampler state).
• program: a shader’s compiled programs (variants, constant-buffer layouts, bind slots, code).
• animator: Avatars and AnimatorControllers (state machines, blend trees, transitions).
• clip: AnimationClips (curves decoded to keys with tangents).
• listing: a player’s objects by class and name, read from the object tables.
• material: materials as stored (shader, saved properties, keywords).
• shader: a Shader’s render state as stored (subshaders, passes, blend, depth and stencil state).
• terrain: terrains as stored (heightmap, holes, splat layers and alphamaps, trees).
• pipeline: the lighting and shadow settings of a Universal Render Pipeline asset.

Reads are bounds-checked, and a file the readers do not understand is refused with an Error that names what was found and where.

Re-exports

pub use serialized::ObjectInfo;

pub use serialized::SerializedFile;

pub use tpk::TypeTreePackage;

pub use typetree::TypeTree;

pub use value::Value;

pub use version::UnityVersion;

Modules

animator

Unity’s Animator side as typed data: an Avatar (the skeleton Mecanim animates, and for a humanoid the compiled muscle axes and the HumanDescription it was built from), an AnimatorController (layers, state machines, states with their blend trees and transitions, parameters). Nothing here is evaluated: it is what the files hold, in Unity’s frame (rotations as [x, y, z, w]), with the names Unity keeps only as CRC-32 hashes resolved through the object’s own name table (tos) where it has one.

bundle

UnityFS bundles: the archive AssetBundles, Addressables content and a player’s data.unity3d are.

clip

Unity AnimationClips: the curves of a Mecanim clip (m_MuscleClip) decoded to keys with tangents.

listing

A player’s objects listed by class and name from its object tables: the class of each object is in the table, its name is read from the object’s first bytes (Player::field: the fields before m_Name are walked, nothing after it), so listing every mesh, texture and material of a player decodes none of them whole.

material

Unity materials as stored: the shader’s name and render state (decoded into crate::shader’s types), and the saved properties (textures with their tiling and offset, floats, integers, colours), keywords, tags and render queue. What they mean depends on the shader.

mesh

Unity meshes: vertex channels in interleaved streams (decoded through checked vertex layouts), or a compressed mesh (bit-packed quantised floats); an index buffer of 16- or 32-bit indices; submeshes.

pipeline

A Universal Render Pipeline asset’s lighting and shadow settings, decoded from the bytes of its UniversalRenderPipelineAsset MonoBehaviour (a build has no type tree for a script’s fields).

player

A Unity player’s data folder: its SerializedFiles by name, pointers (PPtr) resolved across them, objects decoded by their classes’ type trees.

program

A Shader’s compiled programs, as a player stores them: per pass, each stage’s program (vertex, fragment, geometry, hull, domain: the stages the pass has) with its variants (each a keyword set, a GPU program type and an entry of the compressed blob) and their parameters (constant buffers with each field’s name and byte offset, texture and sampler bind slots), read from m_ParsedForm; and a variant’s code from the platform’s LZ4-compressed blob. What the bindings mean for a material is the caller’s.

resource

Streamed resources: bulk data (texture pixels, vertex data, audio) kept in a .resS or .resource file beside the serialized file, named by an object’s StreamingInfo (offset, size, path).

scene

A scene’s hierarchy: GameObjects, their Transforms (local TRS composed to world matrices in Unity’s frame), and its mesh renderers (skinned ones with their bones), LODGroups, colliders, lights and terrains, each whatever its state.

serialized

The SerializedFile container: what globalgamemanagers, *.assets and levelN are.

shader

A Shader’s render state as stored (m_ParsedForm): its subshaders, their passes and the passes’ render-state values, with the BlendMode values they use. crate::material::ShaderData decodes them from a Shader object; procedural says which shaders build their geometry from component data.

terrain

Unity terrains as stored: TerrainData (the heightmap, holes, splat layers and their alphamaps, tree prototypes and instances) and TerrainLayer.

texture

Unity textures (Texture2D): the pixel format, the mip chain from the object or its streamed resource, colour space, how the texture is used, and its sampler state.

tpk

Type tree packages (TPK, “TPK*” files): the layouts of Unity’s built-in classes for every Unity version, which a player build strips from its files. Format versions 1 and 2, type tree data, uncompressed or LZ4 (LZMA and Brotli packages are refused: re-pack them uncompressed).

typetree

Type trees: a class’s serialized layout, and decoding an object’s bytes by it.

value

A decoded object: the value tree its type tree describes. Arrays of a primitive type are kept as typed vectors (a mesh’s vertex data or a terrain’s heights are millions of elements).

version

Unity editor versions, as files write them (6000.3.12f1) and as type tree packages order them.

Enums

Error

Why a read was refused.

Type Aliases

Result

A read’s result.