Voxta Scenarios
The setting and rules a chat runs under — roles, interactions, scripts, apps.
A scenario defines the situation a character is in: where they are, who else is around, what fires when, what the AI should know, and what the host app should do. It is how you go from "a character that can chat" to a structured experience.
You don't need one for casual chats. Scenarios are the upgrade for stories, multi-character setups, and app-integrated scenes.
Tabs
| Tab | What's in it |
|---|---|
| Overview | Name, description, creator, tags, folder, explicit content level. |
| Scenario | Chat flow, chat style, scenario template, bootstrap messages, system prompt override, memory books, narrator, initial flags. |
| Roles | Named character slots. |
| Apps | Per-app configuration — background, default view, and whatever the host app declares. |
| Scripts | The init script and shared script files. |
| Interactions | Events, buttons, HUD widgets, actions and tools, contexts. |
| Impersonation | Who the user plays. |
| Assets | Images, audio, video and animations the scenario ships. |
| Package | The content package this belongs to. |
Scenario tab
- Chat flow —
Chatis normal turn-taking.Storyexcludes the user from the conversation; the AI narrates and the user watches or triggers. - Chat style — narrows which actions and tools are offered. A roleplay scenario and an assistant scenario want different sets.
- Scenario template — a Scriban template that overrides the character's own scenario field. Leave it blank to use the character's. See Templates.
- System prompt — optionally replace or extend the default system prompt.
- Memory book — extra world info pulled in for this scenario. See Memory books.
- Narrator — the voice that reads events out loud.
- Initial flags — flags applied when a new chat starts, before the init and start script events.
Roles
Roles are named slots that characters get assigned to. Templates and scripts reference characters by role, not by name.
{{ char }}is the first role's character.{{ scenario_chars.your_role }}is a specific role's character.
A role can be disabled on start — useful when a character is introduced later. Toggle it from a script with chat.setRoleEnabled('role', true), or keep them present but silent with chat.setCharacterCanSpeak(false, 'role').
Bootstrap messages
How the chat opens. A Scriban block where each line produces one message:
{{ char }}: The first character speaks
{{ user }}: The user
{{ scenario_chars.your_role }}: A specific role's character speaks
{{ event }}: A narrated event everyone can see
{{ note }}: A silent note both sides see
{{ secret }}: Visible to the character only
{{ instructions }}: Visible to the user onlyThey fire in order. Ending with {{ user }}: ... makes the chat wait for the user instead of having the character open. See Messages.
Scripts
The index script runs when the chat starts — the right place to initialize variables and register event listeners. Other scripts are imported by name from events, buttons, actions and tools:
import { yourExports } from "./file_name";See Scripting.
Parent scenarios
A scenario can inherit from a parent. The parent's scripts are reachable under ../base/:
import { hud } from "../base/hud";Use it to share a library, a HUD, or a set of interactions across a family of scenarios. The Voxta UI parent ships helpers for the stage HUD.
Impersonation
By default the user plays themselves. Impersonation overrides that with a name and description — for when the user is meant to be the detective, the new student, and so on. {{ user }} then renders the impersonated identity.