vrm-runtime
A renderer-agnostic VRM 1.0 loader, validator, animation system, and runtime for Rust.
vrm-runtime keeps immutable avatar data in AvatarAsset and stores expressions,
LookAt, animation, constraints, and SpringBone simulation in independent
AvatarRuntime instances. It does not require a particular graphics API or game
engine.
Highlights
- Strict VRM 1.0 loading with structured errors and optional permissive diagnostics
- Renderer-independent GPU and CPU deformation paths
- Expressions, LookAt, first-person visibility, node constraints, and SpringBone
- MToon, glTF PBR, unlit materials, emissive strength, and texture transforms
- Standalone
.vrmaloading, typed animation tracks, and humanoid retargeting - Arbitrary consecutive
TEXCOORD_nandJOINTS_n/WEIGHTS_nsets - Validated PNG/JPEG images from GLB buffer views, data URIs, and relative file URIs
- Type-safe IDs and builders for programmatically assembled avatars
API map
| Task | Start here |
|---|---|
| Load and inspect a VRM | AvatarAsset, LoadOptions |
| Evaluate an avatar each frame | AvatarRuntime |
| Feed a GPU renderer | GpuFrameView, GpuDraw |
| Render deformed CPU meshes | FrameView::bake_cpu |
| Load and play VRMA | VrmAnimation, PlaybackOptions |
| Inspect materials | Material, EvaluatedMaterial |
| Construct an asset in code | AvatarAssetBuilder, RenderPrimitiveBuilder |
The same API is also grouped by responsibility in the crate's animation,
avatar, material, render, runtime, and spring_bone modules.
Installation
[]
= "0.1"
Quick start
use ;
Controls persist between frames. Use clear_expression, clear_bone_rotation,
clear_look_at_target, or reset to remove them. Multiple runtimes can share one
Arc<AvatarAsset> without sharing animation or simulation state.
Loading and diagnostics
Strict validation is the default. Invalid references, unsupported required extensions, malformed accessors, and unsafe numeric values are returned as errors.
use ;
AvatarAsset::load and AvatarAsset::from_file resolve percent-encoded relative
buffer and image URIs against the avatar file. AvatarAsset::from_bytes has no base
directory, so external references are rejected; GLB buffer views and data URIs remain
available. HTTP(S) retrieval is intentionally left to the application.
Rendering model
Each AvatarRuntime::update returns a coherent frame with both rendering paths:
FrameView::gpu()exposes static primitives, world matrices, morph weights, joint matrices, typed IDs, and renderer-ready dynamic material values.FrameView::bake_cpu()returns meshes with morphing, skinning, and world transforms already applied.FrameView::evaluated_materials()provides expression colors and UV transforms, effective HDR emissive values, and MToon UV animation state.FrameView::to_owned()creates aFrameSnapshotsuitable for queues or another thread.CameraModeand first-person index selection apply VRM first-person visibility rules, including automatic head-mesh separation.
For a GPU path, process each GpuDraw in this order:
- Add the weighted morph-target deltas from
morph_weightsto the base vertex. - When
skin_idis present, blendjoint_matriceswith everyJOINTS_n/WEIGHTS_nset. These matrices already produce world-space output; do not applyworld_matrixagain. - When
skin_idis absent, transform the vertex byworld_matrix. - Draw
indices(camera_mode)with the primitive topology andevaluated_material.
Zero-total skin weights intentionally leave a vertex in its rest position. The CPU path implements the same rules and is a useful reference when integrating a shader.
The crate does not create GPU resources or render pipelines, so applications remain free to choose their graphics API and resource layout.
VRM animation
VrmAnimation supports programmatic clips and standalone
VRMC_vrm_animation (.vrma) files.
use ;
Loaded VRMA clips preserve STEP, LINEAR, and CUBICSPLINE interpolation; humanoid
rotation; Hips translation; expression weights; and LookAt channels. Playback
retargets rotations through the source and target T-poses. Hips translation is
scaled by avatar height by default and can be disabled with
PlaybackOptions::scale_hips_translation.
PlaybackOptions::default() plays at normal speed and loops. Use
PlaybackMode::Once for one-shot playback. pause, resume, seek,
set_playback_speed, playback_time, and stop control the active clip.
The complete vrma example
evaluates a clip through one-shot playback at 60 Hz.
Programmatic clips use typed Track<T>, Keyframe<T>, and BoneTrack values:
The following example also requires glam = "0.29" in your dependencies.
use Quat;
use ;
Programmatic assets
Use AvatarAssetBuilder to assemble a complete immutable asset. Renderer data can
be constructed with RenderPrimitiveBuilder, Material, AvatarTexture, and
AvatarImage. Primitive-local buffers are validated by
RenderPrimitiveBuilder::build; cross-object references and VRM invariants are
validated by AvatarAssetBuilder::build.
use ;
let primitive = new
.build?;
assert_eq!;
# Ok::
A complete AvatarAssetBuilder additionally requires consistent metadata,
humanoid nodes, object identifiers, and cross-object references. Its final
build call validates those relationships before returning an immutable asset.
Supported specifications
| Specification or feature | Status |
|---|---|
VRMC_vrm 1.0 metadata, humanoid, expressions, LookAt, first person |
Supported |
| glTF 2.0 PBR materials, textures, skins, morph targets, and animation accessors | Supported |
Arbitrary consecutive TEXCOORD_n and JOINTS_n/WEIGHTS_n |
Supported |
KHR_texture_transform |
Supported |
KHR_materials_unlit |
Supported |
KHR_materials_emissive_strength |
Supported |
VRMC_materials_mtoon 1.0 |
Supported |
Archived VRMC_materials_hdr_emissiveMultiplier |
Supported with diagnostics |
VRMC_node_constraint 1.0 |
Supported |
VRMC_springBone 1.0 |
Supported |
VRMC_springBone_extended_collider |
Supported |
VRMC_vrm_animation 1.0 |
Supported |
| VRM 0.x | Not supported; loading returns an explicit error |
Runtime support can be queried through Capabilities::current() or
AvatarAsset::capabilities().
Examples and validation
From the repository root:
cargo run --example basic -- <path/to/avatar.vrm>
cargo run --example vrma -- <avatar.vrm> <motion.vrma>
cargo test
cargo clippy --all-targets -- -D warnings
Tests that use a locally licensed avatar can be enabled without redistributing the file:
VRM_RUNTIME_TEST_SAMPLE=/absolute/path/to/avatar.vrm cargo test
The referenced file is read from outside the crate and is never included in the published package.
The conformance suite includes synthetic malformed documents and official VRM 1.0
samples. Set VRM_SPECIFICATION_DIR to a local checkout of the VRM specification
repository to run the official sample tests. They are not intended to run from the
published crate archive.
Project status
The crate is currently in its 0.1 development series. Public APIs may still change
before 1.0; semantic-versioning rules will be followed for published releases.
License
Licensed under either of the following, at your option:
Unless explicitly stated otherwise, contributions intentionally submitted for inclusion in this project are licensed under the same terms.