Voxta Actions
Inference-driven AI choices — the smile, the sit, the gesture the character makes alongside speech.
Actions are AI-chosen behaviors that fire before, during, or after a character's message. They're how a scenario adds visual reactions to text: smile when happy, sit when asked, pick up an object, swap an avatar image.
Each action has a prompt that explains to the action-inference layer when to choose it. The inference layer evaluates all candidate actions and picks one (or none) per turn.
Actions and events share most of their structure. Actions are AI-chosen based on conversation context. Events are rule-triggered by time, message count, or flags.
Action name
The name is what the LLM emits when it picks this action. Naming matters:
- ✅ Good:
smile,sit_down,pick_up_phone - ❌ Bad:
jrs_045,act1,nope
Use only lowercase letters, numbers, and underscores. The name should be a hint to the inference model about what the action represents.
Layers
Layers group mutually-exclusive actions. Only one action per layer/timing pair can fire per turn.
Typical layering:
- Emotions —
smile,frown,surprised, ... - Movement —
sit_down,stand_up,lie_down, ...
Each layer is a separate inference pass, so avoid unnecessary layers — they cost a full LLM call each.
Timing
When the action fires relative to the conversation flow:
| Timing | When it runs |
|---|---|
| After User | After the user sends a message, before any character replies. |
| Before Char. | Just before a character replies (to user, another char, or event). |
| After Char. | After the character replies. Can fire before or while speaking. |
| Manually | Only fires when explicitly triggered with /trigger event_name. |
Prompt
Two fields:
- Prompt — what the action inference model sees. Should clearly state when to pick this action.
- Example for
sit_down:When {{ char }} wants to sit down or when {{ user }} instructs it.
- Example for
- Short desc. (optional) — exposed to the character itself so they know this action exists. Useful for big actions like room changes.
- Example:
sit downormove to another room
- Example:
Conditions
Filters that disqualify an action even if inference picks it.
Target
Which role can perform the action. Useful when multiple characters are in the scene.
Match
A regex applied to the triggering message. The action is only considered if the regex matches.
Use this for request-specific actions (only consider bring_water if the message mentions "water") and to skip whole inference layers when nothing relevant was said — saves credits.
Once
When checked: the action sets an invisible _event_name flag the first time it fires, and adds a !_event_name condition so it can never fire again in the same chat.
Flags
Standard flag conditions. See Flags.
Effects
What happens when the action fires.
Set Flags
Set or unset flags. Same syntax as Flags (flag_name, !flag_name, flag.enum_value).
Note / Instructions / Secret / Event / Story
Inject a message into the chat. See Messages for what each type does.
For Story specifically you can cap max tokens and max sentences — useful for keeping generated story beats short.
Script
Run a JavaScript handler. The script gets the full e event object (message, character, arguments, flags). See Scripting.
Interface
- Reorder — actions can be drag-reordered. Order can matter for tie-breaking.
- Toggle — temporarily disable an action without deleting it (great for testing).
- Search — quick filter when a scenario has many actions.