Vrm.state()

Returns the current state of the VRM character. Character states control behavior patterns and can be used to coordinate animations, interactions, and other character-specific logic.

Returns

Promise<string> - The current state of the VRM character

The state() method retrieves the current behavioral state of a VRM character. States are string identifiers that represent the character's current condition or activity. The system has built-in states for common behaviors, and you can also define custom states for mod-specific functionality.

Built-in States

Default States

idle - Default resting state (assigned automatically on spawn)
sitting - Character is in a sitting position
drag - Character is being dragged by the user (automatically set/unset)

Custom States

Any string can be used as a custom state for mod-specific behaviors:

greeting, talking, thinking, celebrating, sleeping, etc.

Examples

Basic State Checking

import {Vrm} from '@homunculus/sdk';

const character = await Vrm.spawn('characters::assistant.vrm');

// Check current state
const currentState = await character.state();
console.log(`Character is currently: ${currentState}`); // "idle"

// State-based logic
if (currentState === 'idle') {
    console.log('Character is available for interaction');
} else if (currentState === 'drag') {
    console.log('Character is being moved');
} else {
    console.log(`Character is in custom state: ${currentState}`);
}

// Set a custom state
await character.setState('greeting');