メインコンテンツまでスキップ

@hmcs/persona

The Persona MOD (@hmcs/persona) manages character identities and provides default behavior for all personas. It replaces the previous @hmcs/character-settings MOD.

Overview​

This MOD provides two things:

  1. Persona Management — UI for creating, editing, and deleting personas with persistent identity data
  2. Default Behavior Service — A background process that auto-spawns personas and manages their animation state machine (idle, drag, sitting)

Persona Management UI​

Access from the system tray → "Persona".

The management dashboard lets you:

  • List all personas with thumbnails and names
  • Create new personas with custom identity fields
  • Edit existing persona settings
  • Delete personas you no longer need

Per-Persona Settings​

Access by right-clicking a character → "Persona".

The settings panel opens as a floating WebView next to the character. It has two tabs:

Persona Tab​

SettingDescription
NameDisplay name
AgeCharacter age
GenderGender identity (male, female, other, unknown)
First-Person PronounHow the character refers to itself (e.g., "I", "watashi", "boku")
ProfileBackground and profile description (free text)
PersonalityPersonality traits in natural language (free text) — used by AI Agent for prompt context
ThumbnailPersona thumbnail image displayed in management UI and menus

Appearance Tab​

SettingDescription
Bone ScaleAdjust VRM model bone scales to customize character proportions

Changes take effect after clicking Save. All settings are persisted to ~/.homunculus/preferences.db.

Default Behavior Service​

The service runs automatically when Desktop Homunculus starts. It handles two responsibilities:

Auto-Spawn​

Personas with metadata['auto-spawn'] set to true are automatically spawned at startup. You can enable Auto-Spawn when creating or editing a persona in the Persona Management dashboard.

Animation State Machine​

The service listens for state-change events on all spawned personas and plays the appropriate animation:

StateAnimationAdditional Behavior
idlevrma:idle-maid (looping)Cursor tracking enabled
dragvrma:grabbed (looping)Cursor tracking disabled, spring bones reset
sittingvrma:idle-sitting (looping)Cursor tracking enabled
ヒント

If you're building a custom MOD that creates personas, you don't need to reimplement idle/drag/sitting logic — the @hmcs/persona service handles it automatically for all spawned personas.

SDK Reference​

For programmatic persona management, see the SDK guide and the Persona class in the VRM module reference.

Notes​

  • This MOD adds a "Persona" entry to both the right-click menu and the system tray menu.
  • The settings panel UI uses the shared @hmcs/ui component library.
  • Personality text is used by the @hmcs/openclaw-plugin bridge to generate SOUL.md / IDENTITY.md for external OpenClaw agents. See AI Integration for details.