Interactions
Companions are metadata-driven. Each interaction declares a trigger, an action, and usually an animation clip.
Model
Declared in companion.json. The host resolves the first eligible interaction for a trigger (cooldowns and unlocks apply), then runs the action against the animation map. See Animations for clip roles.
{
"id": "theme-shift",
"description": "Glows when the site theme changes",
"trigger": "theme_change",
"action": "play_animation",
"animation": "glow",
"cooldown": 1800,
"duration": 2000
}Triggers
| Trigger | Typical use |
|---|---|
| click / double_click | Happy, jump, wake |
| idle_timeout | Idle pulse, sleep, blink |
| drag_start / drop | Pick up, fall → puff |
| cursor_nearby | Glow, follow cursor |
| page_navigation | Greet after docs navigation |
| theme_change | React to light/dark toggle (Nyx) |
| scroll / surface_action | Glance, perched surface click |
| manual | Reserved for host-only calls |
| Trigger | Typical use | | --- | --- | | click / double_click | Happy, jump, wake | | idle_timeout | Idle pulse, sleep, blink | | drag_start / drop | Pick up, fall | | cursor_nearby | Glow, follow | | page_navigation | Greet on route change | | theme_change | React to light/dark toggle | | scroll / surface_action | Glance, perched click | | manual | Host-only / reserved |
Actions
play_animation— play a named clip.jump— physics hop, often with celebrate/happy.sleep/change_state— doze or fall.move— drift (follow-cursor style).
Try them live on the Companions page — spawn Nyx and toggle the theme to see theme_change.