Skip to main content

Type Definitions

All types exported from the vrm module of @hmcs/sdk.

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

Core​

Bones​

type Bones =
| "hips" | "spine" | "chest" | "neck" | "head"
| "leftShoulder" | "leftArm" | "leftForeArm" | "leftHand"
| "rightShoulder" | "rightArm" | "rightForeArm" | "rightHand"
| "leftUpLeg" | "leftLeg" | "leftFoot"
| "rightUpLeg" | "rightLeg" | "rightFoot";

PositionResponse​

interface PositionResponse {
/** Global screen coordinates (multi-monitor origin at leftmost screen). Null if not visible. */
globalViewport: [number, number] | null;
/** Bevy world coordinates. */
world: Vec3;
}

SpawnVrmOptions​

interface SpawnVrmOptions {
transform?: TransformArgs;
persona?: Persona;
}

VrmSnapshot​

interface VrmSnapshot {
entity: number;
name: string;
state: string;
transform: Transform;
globalViewport: [number, number] | null;
expressions: ExpressionsResponse;
animations: VrmaInfo[];
lookAt: LookAtState | null;
linkedWebviews: number[];
persona: Persona;
}

VrmMetadata​

interface VrmMetadata {
name: string;
entity: number;
}

MoveToArgs​

/** Arguments for moving a VRM to a viewport position. */
interface MoveToArgs {
globalViewport: GlobalViewport;
}

LookAtState​

type LookAtState =
| { type: "cursor" }
| { type: "target"; entity: number };

Persona​

Persona​

interface Persona {
/** Character profile/background description. */
profile: string;
/** Personality description in natural language. */
personality?: string | null;
/** Extension metadata for MODs. */
metadata: Record<string, unknown>;
}

Expressions​

ExpressionsResponse​

interface ExpressionsResponse {
expressions: ExpressionInfo[];
}

ExpressionInfo​

interface ExpressionInfo {
name: string;
weight: number;
isBinary: boolean;
overrideBlink: OverrideType;
overrideLookAt: OverrideType;
overrideMouth: OverrideType;
}

OverrideType​

type OverrideType = "none" | "blend" | "block";

Animation​

VrmaInfo​

interface VrmaInfo {
entity: number;
name: string;
playing: boolean;
}

VrmaPlayRequest​

interface VrmaPlayRequest {
asset: string;
transitionSecs?: number;
repeat?: VrmaRepeat;
waitForCompletion?: boolean;
resetSpringBones?: boolean;
}

VrmaRepeat​

interface VrmaRepeat {
type: "forever" | "never" | "count";
count?: number;
}

VrmaState​

interface VrmaState {
playing: boolean;
repeat: string;
speed: number;
elapsedSecs: number;
}

VrmaSpeedBody​

interface VrmaSpeedBody {
asset: string;
speed: number;
}

Spring Bone​

SpringBoneChainsResponse​

interface SpringBoneChainsResponse {
chains: SpringBoneChain[];
}

SpringBoneChain​

interface SpringBoneChain {
entity: number;
joints: string[];
props: SpringBoneProps;
}

SpringBoneProps​

interface SpringBoneProps {
stiffness: number;
dragForce: number;
gravityPower: number;
gravityDir: [number, number, number];
hitRadius: number;
}

Speech​

TimelineKeyframe​

interface TimelineKeyframe {
/** Duration of this keyframe in seconds. */
duration: number;
/** Expression weights to set. Keys are expression names, values are 0.0-1.0. */
targets?: Record<string, number>;
}

SpeakTimelineOptions​

interface SpeakTimelineOptions {
/** If true, waits for speech to complete. Defaults to true. */
waitForCompletion?: boolean;
/** Seconds for smoothstep blending between adjacent keyframes. Defaults to 0.05. */
transitionDuration?: number;
}

Events​

VrmEventSource​

class VrmEventSource implements Disposable {
on<K extends keyof EventMap>(
event: K,
callback: (event: EventMap[K]) => void | Promise<void>,
): void;
close(): void;
[Symbol.dispose](): void;
}

EventMap​

type EventMap = {
"drag-start": VrmPointerEvent;
"drag": VrmDragEvent;
"drag-end": VrmPointerEvent;
"pointer-press": VrmMouseEvent;
"pointer-click": VrmMouseEvent;
"pointer-release": VrmMouseEvent;
"pointer-over": VrmPointerEvent;
"pointer-out": VrmPointerEvent;
"pointer-cancel": VrmPointerEvent;
"pointer-move": VrmPointerEvent;
"state-change": VrmStateChangeEvent;
"expression-change": VrmStateChangeEvent;
"vrma-play": VrmStateChangeEvent;
"vrma-finish": VrmStateChangeEvent;
"persona-change": PersonaChangeEvent;
};

VrmPointerEvent​

interface VrmPointerEvent {
globalViewport: [number, number];
}

VrmDragEvent​

interface VrmDragEvent extends VrmPointerEvent {
delta: [number, number];
}

Button​

type Button = "Primary" | "Secondary" | "Middle";

VrmMouseEvent​

interface VrmMouseEvent extends VrmPointerEvent {
button: Button;
}

VrmStateChangeEvent​

interface VrmStateChangeEvent {
state: string;
}

PersonaChangeEvent​

interface PersonaChangeEvent {
persona: Persona;
}