Expand description
§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
[dependencies]
vrm-runtime = "0.1"§Quick start
use vrm_runtime::{AvatarAsset, AvatarRuntime};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let asset = AvatarAsset::load("avatar.vrm")?;
let mut runtime = AvatarRuntime::new(asset);
runtime.set_expression("happy", 0.8)?;
let frame = runtime.update(1.0 / 60.0)?;
// GPU path: upload immutable vertices plus frame-local deformation data.
for draw in frame.gpu().draws() {
let _primitive = draw.primitive;
let _morph_weights = draw.morph_weights;
let _joint_matrices = draw.joint_matrices;
if let Some(material) = draw.evaluated_material {
let _renderer_ready_material = material;
}
}
// CPU path: morphing, skinning, and world transforms are already applied.
let meshes = frame.bake_cpu();
println!("baked {} meshes", meshes.len());
Ok(())
}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 vrm_runtime::{AvatarAsset, LoadOptions, ValidationMode};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let outcome = AvatarAsset::load_with_options(
"avatar.vrm",
LoadOptions {
validation: ValidationMode::Permissive,
},
)?;
for diagnostic in outcome.diagnostics {
eprintln!(
"{} at {}: {}",
diagnostic.code, diagnostic.path, diagnostic.message
);
}
Ok(())
}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 vrm_runtime::{AvatarAsset, AvatarRuntime, PlaybackOptions, VrmAnimation};
fn main() -> Result<(), Box<dyn std::error::Error>> {
let avatar = AvatarAsset::load("avatar.vrm")?;
let animation = VrmAnimation::load("motion.vrma")?;
let mut runtime = AvatarRuntime::new(avatar);
runtime.play(animation, PlaybackOptions::default())?;
// Call update once per application frame with elapsed seconds.
let frame = runtime.update(1.0 / 60.0)?;
println!("{} draws", frame.gpu().draws().len());
Ok(())
}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 glam::Quat;
use vrm_runtime::{
BoneTrack, HumanBone, Interpolation, Keyframe, Track, VrmAnimation,
};
fn main() -> Result<(), String> {
let rotation = Track::new(
Interpolation::Linear,
vec![
Keyframe::new(0.0, Quat::IDENTITY),
Keyframe::new(1.0, Quat::from_rotation_y(0.5)),
],
);
let animation = VrmAnimation::new(1.0).with_bone_track(
HumanBone::Head,
BoneTrack::new().with_rotation(rotation),
);
animation.validate()?;
Ok(())
}§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 vrm_runtime::{NodeId, RenderPrimitiveBuilder};
let primitive = RenderPrimitiveBuilder::new(
NodeId::from_index(0),
vec![[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0]],
vec![0, 1, 2],
)
.build()?;
assert_eq!(primitive.positions().len(), 3);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 warningsTests that use a locally licensed avatar can be enabled without redistributing the file:
VRM_RUNTIME_TEST_SAMPLE=/absolute/path/to/avatar.vrm cargo testThe 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.
Re-exports§
pub use animation::AnimationLoadError;pub use animation::AnimationLoadOutcome;pub use animation::BoneTrack;pub use animation::Interpolation;pub use animation::Keyframe;pub use animation::SourceBoneRestPose;pub use animation::Track;pub use animation::TrackValue;pub use animation::VrmAnimation;pub use avatar::AvatarAsset;pub use avatar::LoadOutcome;pub use builder::AvatarAssetBuilder;pub use constraint::AimAxis;pub use constraint::AimConstraint;pub use constraint::NodeConstraint;pub use constraint::NodeConstraintKind;pub use constraint::RollAxis;pub use constraint::RollConstraint;pub use constraint::RotationConstraint;pub use constraint::solve_constraints;pub use diagnostic::Capabilities;pub use diagnostic::Diagnostic;pub use diagnostic::DiagnosticSeverity;pub use diagnostic::LoadOptions;pub use diagnostic::ValidationMode;pub use error::BuildError;pub use error::LoadError;pub use evaluated_material::EvaluatedMaterial;pub use evaluated_material::UvAnimationState;pub use expressions::Expression;pub use expressions::ExpressionEvaluation;pub use expressions::ExpressionOverrideType;pub use expressions::Expressions;pub use expressions::MaterialColorBind;pub use expressions::MaterialColorType;pub use expressions::MaterialColorUpdate;pub use expressions::MorphTargetBind;pub use expressions::MorphTargetUpdate;pub use expressions::TextureTransformBind;pub use expressions::TextureTransformUpdate;pub use first_person::AutoSplit;pub use first_person::CameraMode;pub use first_person::FirstPerson;pub use first_person::FirstPersonFlag;pub use first_person::MeshAnnotation;pub use humanoid::HumanBone;pub use humanoid::HumanBoneNode;pub use humanoid::Humanoid;pub use id::ImageId;pub use id::MaterialId;pub use id::NodeId;pub use id::PrimitiveId;pub use id::SkinId;pub use id::TextureId;pub use image::AvatarImage;pub use instance::AvatarEvaluation;pub use instance::AvatarInstance;pub use instance::BoneUpdate;pub use look_at::LookAt;pub use look_at::LookAtRangeMap;pub use look_at::LookAtType;pub use look_at::calc_yaw_pitch;pub use material::AlphaMode;pub use material::AvatarTexture;pub use material::EmissiveStrengthSource;pub use material::MToonMaterial;pub use material::MagFilter;pub use material::Material;pub use material::MaterialShadingModel;pub use material::MinFilter;pub use material::NormalTextureInfo;pub use material::OcclusionTextureInfo;pub use material::OutlineWidthMode;pub use material::TextureInfo;pub use material::TextureSampler;pub use material::TextureTransform;pub use material::WrapMode;pub use meta::AvatarMeta;pub use meta::AvatarPermission;pub use meta::AvatarPermissions;pub use meta::CommercialUsage;pub use meta::CreditNotation;pub use meta::ModificationPermission;pub use morph_target::MorphTarget;pub use node::AvatarNode;pub use node::compute_joint_matrices;pub use node::compute_world_matrices;pub use primitive::MorphedVertices;pub use primitive::PrimitiveTopology;pub use primitive::RenderPrimitive;pub use primitive::RenderPrimitiveBuilder;pub use primitive::SkinningSet;pub use render::CpuMesh;pub use runtime::AvatarRuntime;pub use runtime::ControlError;pub use runtime::FrameSnapshot;pub use runtime::FrameView;pub use runtime::GpuDraw;pub use runtime::GpuFrameView;pub use runtime::PlaybackMode;pub use runtime::PlaybackOptions;pub use runtime::RuntimeError;pub use runtime::RuntimeOptions;pub use runtime::SkinningPalette;pub use skin::Skin;pub use spring_bone::ColliderShape;pub use spring_bone::SpringBone;pub use spring_bone::SpringBoneSimulator;pub use spring_bone::SpringChain;pub use spring_bone::SpringCollider;pub use spring_bone::SpringColliderGroup;pub use spring_bone::SpringJoint;pub use transform::Transform;
Modules§
- animation
- VRMA loading, typed animation tracks, sampling, and retargeting metadata.
- avatar
- Immutable VRM assets and strict or permissive file loading.
- builder
- Validated construction of complete programmatic avatar assets.
- constraint
- VRM node-constraint data and low-level constraint evaluation.
- diagnostic
- Loader capabilities, validation modes, and recoverable diagnostics.
- error
- Errors produced while loading or constructing assets.
- evaluated_
material - Renderer-ready material values after expressions and UV animation.
- expressions
- VRM expressions, binds, overrides, and evaluated updates.
- first_
person - First-person visibility annotations and automatic mesh separation.
- humanoid
- Humanoid bone definitions and validated node mappings.
- id
- Type-safe identifiers for objects stored in an avatar asset.
- image
- Encoded PNG and JPEG image data retained by the loader.
- instance
- Low-level mutable avatar controls and frame evaluation results.
- look_at
- LookAt configuration and gaze-angle conversion.
- material
- glTF, unlit, and MToon material and texture data.
- meta
- VRM authorship, licensing, and usage-permission metadata.
- morph_
target - Morph-target vertex deltas.
- node
- Avatar node transforms and low-level world or joint matrix calculation.
- primitive
- Canonical renderer geometry and validated primitive construction.
- render
- CPU-side deformation output.
- runtime
- High-level animation, expression, constraint, and SpringBone evaluation.
- skin
- Skin joints and inverse-bind matrices.
- spring_
bone - SpringBone colliders, chains, validation, and simulation.
- transform
- Renderer-independent translation, rotation, and scale values.