pub struct VrmAnimation { /* private fields */ }Expand description
A playable VRM humanoid animation.
Programmatic clips store target-local rotation deltas. Clips loaded from
.vrma additionally retain the source rest pose needed for retargeting.
Implementations§
Source§impl VrmAnimation
impl VrmAnimation
Sourcepub fn new(duration: f32) -> Self
pub fn new(duration: f32) -> Self
Creates an empty programmatic clip with the given duration in seconds.
Tracks may be inserted before validation. AvatarRuntime::play
validates the complete clip before it becomes active.
Sourcepub const fn duration(&self) -> f32
pub const fn duration(&self) -> f32
Returns the clip duration in seconds.
Examples found in repository?
8fn main() -> Result<(), Box<dyn std::error::Error>> {
9 let mut arguments = std::env::args().skip(1);
10 let avatar_path = arguments
11 .next()
12 .expect("usage: vrma <avatar.vrm> <motion.vrma>");
13 let animation_path = arguments
14 .next()
15 .expect("usage: vrma <avatar.vrm> <motion.vrma>");
16
17 let avatar = AvatarAsset::load(avatar_path)?;
18 let animation = VrmAnimation::load(animation_path)?;
19 let duration = animation.duration();
20 let mut runtime = AvatarRuntime::new(avatar);
21
22 runtime.play(
23 animation,
24 PlaybackOptions {
25 mode: PlaybackMode::Once,
26 ..PlaybackOptions::default()
27 },
28 )?;
29
30 let delta_seconds = 1.0 / 60.0;
31 let frame_count = ((duration / delta_seconds).ceil() as usize).max(1) + 1;
32 for frame_index in 0..frame_count {
33 let (draw_count, bone_update_count) = {
34 let frame = runtime.update(delta_seconds)?;
35 (frame.gpu().draws().len(), frame.bone_updates().len())
36 };
37
38 if frame_index % 60 == 0 || !runtime.is_playing() {
39 println!(
40 "time={:.3}s draws={} bone_updates={}",
41 runtime.playback_time().unwrap_or(0.0),
42 draw_count,
43 bone_update_count,
44 );
45 }
46 if !runtime.is_playing() {
47 break;
48 }
49 }
50
51 Ok(())
52}Sourcepub fn with_bone_track(self, bone: HumanBone, track: BoneTrack) -> Self
pub fn with_bone_track(self, bone: HumanBone, track: BoneTrack) -> Self
Adds or replaces a humanoid bone track.
Sourcepub fn insert_bone_track(
&mut self,
bone: HumanBone,
track: BoneTrack,
) -> Option<BoneTrack>
pub fn insert_bone_track( &mut self, bone: HumanBone, track: BoneTrack, ) -> Option<BoneTrack>
Inserts a humanoid bone track and returns the previous value, if any.
Sourcepub fn with_expression_track(
self,
name: impl Into<String>,
track: Track<f32>,
) -> Self
pub fn with_expression_track( self, name: impl Into<String>, track: Track<f32>, ) -> Self
Adds or replaces an expression weight track.
Sourcepub fn insert_expression_track(
&mut self,
name: impl Into<String>,
track: Track<f32>,
) -> Option<Track<f32>>
pub fn insert_expression_track( &mut self, name: impl Into<String>, track: Track<f32>, ) -> Option<Track<f32>>
Inserts an expression weight track and returns the previous value, if any.
Sourcepub fn with_look_at_rotation_track(self, track: Track<Quat>) -> Self
pub fn with_look_at_rotation_track(self, track: Track<Quat>) -> Self
Adds or replaces the LookAt rotation track.
Sourcepub fn set_look_at_rotation_track(
&mut self,
track: Track<Quat>,
) -> Option<Track<Quat>>
pub fn set_look_at_rotation_track( &mut self, track: Track<Quat>, ) -> Option<Track<Quat>>
Replaces the LookAt rotation track and returns the previous value, if any.
Sourcepub fn load<P: AsRef<Path>>(path: P) -> Result<Self, AnimationLoadError>
pub fn load<P: AsRef<Path>>(path: P) -> Result<Self, AnimationLoadError>
Loads the first animation from a VRMA file using strict validation.
Relative external buffers are resolved against the file’s parent
directory. Use Self::load_with_options to collect diagnostics from
permissive validation.
§Errors
Returns AnimationLoadError when the file cannot be read, its glTF or
VRMC_vrm_animation data is invalid, or it requires an unsupported
extension.
§Examples
use vrm_runtime::VrmAnimation;
let animation = VrmAnimation::load("motion.vrma")?;
println!("duration: {} seconds", animation.duration());Examples found in repository?
8fn main() -> Result<(), Box<dyn std::error::Error>> {
9 let mut arguments = std::env::args().skip(1);
10 let avatar_path = arguments
11 .next()
12 .expect("usage: vrma <avatar.vrm> <motion.vrma>");
13 let animation_path = arguments
14 .next()
15 .expect("usage: vrma <avatar.vrm> <motion.vrma>");
16
17 let avatar = AvatarAsset::load(avatar_path)?;
18 let animation = VrmAnimation::load(animation_path)?;
19 let duration = animation.duration();
20 let mut runtime = AvatarRuntime::new(avatar);
21
22 runtime.play(
23 animation,
24 PlaybackOptions {
25 mode: PlaybackMode::Once,
26 ..PlaybackOptions::default()
27 },
28 )?;
29
30 let delta_seconds = 1.0 / 60.0;
31 let frame_count = ((duration / delta_seconds).ceil() as usize).max(1) + 1;
32 for frame_index in 0..frame_count {
33 let (draw_count, bone_update_count) = {
34 let frame = runtime.update(delta_seconds)?;
35 (frame.gpu().draws().len(), frame.bone_updates().len())
36 };
37
38 if frame_index % 60 == 0 || !runtime.is_playing() {
39 println!(
40 "time={:.3}s draws={} bone_updates={}",
41 runtime.playback_time().unwrap_or(0.0),
42 draw_count,
43 bone_update_count,
44 );
45 }
46 if !runtime.is_playing() {
47 break;
48 }
49 }
50
51 Ok(())
52}Sourcepub fn from_file<P: AsRef<Path>>(path: P) -> Result<Self, AnimationLoadError>
pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Self, AnimationLoadError>
Loads a VRMA file using strict validation.
Sourcepub fn from_bytes(bytes: &[u8]) -> Result<Self, AnimationLoadError>
pub fn from_bytes(bytes: &[u8]) -> Result<Self, AnimationLoadError>
Parses a GLB/VRMA byte slice using strict validation.
Sourcepub fn load_with_options<P: AsRef<Path>>(
path: P,
options: LoadOptions,
) -> Result<AnimationLoadOutcome, AnimationLoadError>
pub fn load_with_options<P: AsRef<Path>>( path: P, options: LoadOptions, ) -> Result<AnimationLoadOutcome, AnimationLoadError>
Loads a VRMA file and returns recoverable diagnostics.
Sourcepub fn from_file_with_options<P: AsRef<Path>>(
path: P,
options: LoadOptions,
) -> Result<AnimationLoadOutcome, AnimationLoadError>
pub fn from_file_with_options<P: AsRef<Path>>( path: P, options: LoadOptions, ) -> Result<AnimationLoadOutcome, AnimationLoadError>
Loads a VRMA file and returns recoverable diagnostics.
Sourcepub fn from_bytes_with_options(
bytes: &[u8],
options: LoadOptions,
) -> Result<AnimationLoadOutcome, AnimationLoadError>
pub fn from_bytes_with_options( bytes: &[u8], options: LoadOptions, ) -> Result<AnimationLoadOutcome, AnimationLoadError>
Parses a GLB/VRMA byte slice and returns recoverable diagnostics.
Sourcepub fn bone_track(&self, bone: HumanBone) -> Option<&BoneTrack>
pub fn bone_track(&self, bone: HumanBone) -> Option<&BoneTrack>
Returns the channels assigned to a humanoid bone.
Sourcepub fn bone_tracks(&self) -> impl Iterator<Item = (HumanBone, &BoneTrack)>
pub fn bone_tracks(&self) -> impl Iterator<Item = (HumanBone, &BoneTrack)>
Iterates over bones that have at least one animation channel.
Sourcepub fn expression_track(&self, name: &str) -> Option<&Track<f32>>
pub fn expression_track(&self, name: &str) -> Option<&Track<f32>>
Returns an expression weight track.
Sourcepub fn expression_tracks(&self) -> impl Iterator<Item = (&str, &Track<f32>)>
pub fn expression_tracks(&self) -> impl Iterator<Item = (&str, &Track<f32>)>
Iterates over all expression weight tracks.
Sourcepub fn look_at_rotation_track(&self) -> Option<&Track<Quat>>
pub fn look_at_rotation_track(&self) -> Option<&Track<Quat>>
Returns the LookAt rotation track, if present.
Sourcepub fn look_at_offset_from_head_bone(&self) -> Option<Vec3>
pub fn look_at_offset_from_head_bone(&self) -> Option<Vec3>
Returns the source animation’s LookAt origin offset.
Sourcepub fn source_bone_rest_pose(
&self,
bone: HumanBone,
) -> Option<SourceBoneRestPose>
pub fn source_bone_rest_pose( &self, bone: HumanBone, ) -> Option<SourceBoneRestPose>
Returns source T-pose information required for humanoid retargeting.
Sourcepub fn source_hips_height(&self) -> Option<f32>
pub fn source_hips_height(&self) -> Option<f32>
Returns the source Hips height used to scale locomotion across avatars.
Sourcepub fn validate(&self) -> Result<(), String>
pub fn validate(&self) -> Result<(), String>
Validates keyframe ordering and all numeric values before playback.
Sourcepub fn sample_look_at_rotation(&self, time: f32) -> Option<Quat>
pub fn sample_look_at_rotation(&self, time: f32) -> Option<Quat>
Samples the LookAt rotation while preserving its glTF interpolation.
Sourcepub fn sample_programmatic_bone_rotation_delta(
&self,
bone: HumanBone,
time: f32,
) -> Option<Quat>
pub fn sample_programmatic_bone_rotation_delta( &self, bone: HumanBone, time: f32, ) -> Option<Quat>
Samples a target-local rotation delta from a programmatic clip.
This returns None for loaded VRMA tracks because their rotations are
source-local poses that must be retargeted.
Sourcepub fn sample_source_bone_rotation(
&self,
bone: HumanBone,
time: f32,
) -> Option<Quat>
pub fn sample_source_bone_rotation( &self, bone: HumanBone, time: f32, ) -> Option<Quat>
Samples the raw local-space rotation stored by a loaded VRMA source.
This returns None for programmatic clips, whose rotations already
represent target-local deltas.
Sourcepub fn sample_normalized_source_bone_rotation(
&self,
bone: HumanBone,
time: f32,
) -> Option<Quat>
pub fn sample_normalized_source_bone_rotation( &self, bone: HumanBone, time: f32, ) -> Option<Quat>
Samples a loaded VRMA source rotation in normalized humanoid space.
Sourcepub fn sample_retargeted_source_bone_rotation(
&self,
bone: HumanBone,
time: f32,
target_world_rest_rotation: Quat,
) -> Option<Quat>
pub fn sample_retargeted_source_bone_rotation( &self, bone: HumanBone, time: f32, target_world_rest_rotation: Quat, ) -> Option<Quat>
Converts a normalized source pose into the delta expected by a target avatar whose world rest rotation is supplied by the caller.
Sourcepub fn sample_bone_translation_delta(
&self,
bone: HumanBone,
time: f32,
) -> Option<Vec3>
pub fn sample_bone_translation_delta( &self, bone: HumanBone, time: f32, ) -> Option<Vec3>
Samples the Hips translation delta while preserving its interpolation.
Sourcepub fn sample_expression_weight(&self, name: &str, time: f32) -> f32
pub fn sample_expression_weight(&self, name: &str, time: f32) -> f32
Samples an expression weight and clamps it to the VRM range.