Character actions

Find the Actions Editor, executor reference, dispatcher configuration, scripting API, and usage guides for Convai character actions in Unity.

Character actions let a Convai character respond to what a player says with an in-scene behavior — walking to a target, making eye contact, playing a gesture, or running your own gameplay code. Convai identifies which action to run and what to target; the Actions Editor is where you add and configure the 21 built-in executors that carry it out, or wire in your own. This section covers everything from your first action to the full scripting API.

Several built-in executors run through the Gaze and Body Animation embodiment modules, so a character needs the matching module installed before those actions work — see Embodiment.

How character actions work Understand the pipeline, key concepts, required components, and built-in executors.

Character actions quick start Add a ready-made action to your NPC from the Actions Editor's starter catalog — no scripting required.

Actions Editor Reference for the Actions Editor window: the Add Action catalog, and one-click executor provisioning.

Configure character actions Full reference for ConvaiActionConfigSource — action definitions, targets, and connect-time overrides.

Update character actions at runtime Apply ConvaiActionConfigPatch updates to actions, objects, characters, and attention while a session is active, confirmed by Convai's acknowledgment.

Action executors Reference for all 21 executor components with Inspector field tables.

Dispatcher and batch policies Configure how ConvaiActionDispatcher handles concurrent batches and step failures.

Write a custom action executor Implement IConvaiActionExecutor to create project-specific behaviors for any action.

How action target resolution works How a command's target words are matched to real objects in your scene, and how attention narrows the match.

Character actions scripting reference Complete public API for all action system types, events, enums, and components.

Character actions examples Six progressive scenarios from no-code Inspector setup to scripted batch injection, speech-synced timing, and observation actions.

Troubleshoot character actions Diagnose action pipeline issues with the Action Troubleshooter and a symptom/cause/fix reference.