VRM Module

The Vrm class is the core module of @hmcs/sdk. It manages the full lifecycle of VRM 3D characters -- spawning, finding, animating, controlling expressions, handling pointer/drag events, lip-sync speech, and more.

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

Static Methods

Method	Description
Vrm.spawn	Spawn a new VRM from a MOD asset ID. Returns a Vrm instance.
Vrm.findByName	Find a VRM by its model name. Throws if not found.
Vrm.waitLoadByName	Wait for a VRM to finish loading, then return it.
Vrm.findAll	Get all loaded VRM instances as Vrm[].
Vrm.findAllEntities	Get all loaded VRM entity IDs as number[].
Vrm.findAllDetailed	Get detailed snapshots of all VRMs (state, transform, expressions, animations, persona).
Vrm.streamMetadata	Stream raw VrmMetadata for existing and future VRM instances.
Vrm.stream	Stream existing and future VRM instances as Vrm objects.

Instance Methods

Method	Description
despawn	Remove this VRM from the scene.
position	Get position in both screen (globalViewport) and world coordinates.
state	Get the current state string (e.g., "idle", "drag", "sitting").
setState	Set the character's state.
name	Get the VRM model name.
findBoneEntity	Find the entity ID of a named bone (e.g., "head", "leftHand").
playVrma	Play a VRMA animation with repeat, transition, and completion options.
stopVrma	Stop a specific VRMA animation by asset ID.
listVrma	List all VRMA animations attached to this VRM.
vrmaState	Get the playback state of a specific animation (playing, speed, elapsed).
setVrmaSpeed	Change the playback speed of an animation.
springBones	Get all spring bone chains (hair, clothing physics).
springBone	Get a specific spring bone chain by entity ID.
setSpringBone	Update spring bone physics properties (stiffness, drag, gravity).
expressions	Get all expressions and their current weights.
setExpressions	Set expression weights, replacing all previous overrides.
modifyExpressions	Partially update expression weights (other overrides remain).
clearExpressions	Clear all expression overrides, returning control to VRMA animation.
modifyMouth	Set mouth expressions for lip-sync (non-mouth overrides are preserved).
lookAtCursor	Make the character's eyes follow the mouse cursor.
lookAtTarget	Make the character look at a specific entity.
unlook	Disable the look-at behavior.
persona	Get the character's persona (profile, personality, OCEAN traits, metadata).
setPersona	Set the character's persona data.
speakWithTimeline	Play WAV audio with frame-synchronized expression keyframes for lip-sync.
events	Open a VrmEventSource for real-time event streaming.

repeat namespace

Function	Description
repeat.forever	Loop the animation indefinitely.
repeat.never	Play the animation exactly once.
repeat.count	Play the animation a fixed number of times.

VrmEventSource

Method	Description
VrmEventSource.on	Register an event listener.
VrmEventSource.close	Close the SSE connection.