Skip to main content

Character

Character tools manage VRM lifecycle, active selection, and persona metadata.

get_character_snapshot​

Get the current state of all desktop characters. Returns entity ID, name, position, active expressions, playing animations, persona, and lookAt state for each character.

This tool takes no parameters. The first character found is automatically set as the active character for subsequent tool calls.

Example response:

[
{
"entity": 42,
"name": "Elmer",
"state": "idle",
"position": [800, 600],
"activeExpressions": [{ "name": "happy", "weight": 1.0 }],
"playingAnimations": ["idle-maid"],
"persona": { "profile": "A cheerful assistant", "personality": null },
"lookAt": { "type": "cursor" }
}
]

position is [x, y] in global viewport coordinates, or null if unavailable. lookAt is an object (for example { "type": "cursor" } or { "type": "target", "entity": 123 }) or null.


spawn_character​

Spawn a new VRM character on the desktop. The spawned character becomes the active character. Use the homunculus://assets resource to discover available VRM asset IDs.

ParameterTypeDefaultDescription
assetstringrequiredVRM model asset ID (e.g. vrm:elmer)
namestring—Display name for the character
persona_profilestring—Character personality/background description
xnumber—Initial viewport X position (pixels)
ynumber—Initial viewport Y position (pixels)

Example:

{
"asset": "vrm:elmer",
"name": "Elmer",
"persona_profile": "A cheerful coding companion who loves Rust",
"x": 900,
"y": 700
}

remove_character​

Remove a VRM character from the desktop.

ParameterTypeDefaultDescription
namestring—Name of the character to remove. If omitted, removes the active character.

select_character​

Switch the active character by name. All subsequent tools that target "the active character" will target this character.

Use get_character_snapshot to list available names.

ParameterTypeDefaultDescription
namestringrequiredCharacter name to select

set_persona​

Set the active character's personality profile. This affects how the character is presented in AI conversations.

ParameterTypeDefaultDescription
profilestringrequiredCharacter background description
personalitystring—Personality traits in natural language

Example:

{
"profile": "A serious researcher who specializes in distributed systems",
"personality": "Precise, methodical, occasionally dry humor"
}