Skip to main content

playVrma

import { Vrm, repeat } from "@hmcs/sdk";

vrm.playVrma(options) starts a VRMA animation on the character.

const character = await Vrm.spawn("my-mod:character");

await character.playVrma({
asset: "vrma:idle-maid",
repeat: repeat.forever(),
transitionSecs: 0.5,
});

Options​

OptionTypeDefaultDescription
assetstring(required)Asset ID of the VRMA animation
repeatVrmaRepeat—Repeat mode: repeat.forever(), repeat.never(), or repeat.count(n)
transitionSecsnumber—Crossfade duration in seconds for blending from the current animation
waitForCompletionbooleanfalseIf true, the call blocks until the animation finishes
resetSpringBonesbooleanfalseIf true, resets spring bone velocities to prevent bouncing artifacts

Crossfade Transitions​

Use transitionSecs to smoothly blend from the current animation into the new one. Without it, animations switch instantly.

// Smooth 0.5-second crossfade into idle
await character.playVrma({
asset: "vrma:idle-maid",
repeat: repeat.forever(),
transitionSecs: 0.5,
});

Waiting for Completion​

Set waitForCompletion: true to block until a one-shot animation finishes. This is useful for sequencing animations.

// Play a wave animation and wait for it to finish
await character.playVrma({
asset: "my-mod:wave",
repeat: repeat.never(),
waitForCompletion: true,
});

// This line runs after the wave animation is done
await character.playVrma({
asset: "vrma:idle-maid",
repeat: repeat.forever(),
transitionSecs: 0.5,
});

Spring Bone Reset​

When switching between animations with very different poses (e.g., standing to grabbed), spring bone physics (hair, clothing) can cause unwanted bouncing. Use resetSpringBones: true to reset velocities.

await character.playVrma({
asset: "vrma:grabbed",
repeat: repeat.forever(),
resetSpringBones: true,
});

Built-in Animations​

The engine provides these built-in VRMA animations:

Asset IDDescription
vrma:idle-maidStanding idle animation (looping)
vrma:grabbedPicked-up/grabbed pose (looping)
vrma:idle-sittingSitting idle animation (looping)