Scenarios

A scenario defines the situation a character finds themselves in: where they are, who else is around, what events should fire, what actions are available, what extra context the AI should know. Scenarios are how you go from "a character that can chat" to a structured experience with story beats, multiple participants, and app-side effects.

You don't need a scenario for casual chats — pick a character and start talking. Scenarios are the upgrade for stories, multi-character setups, and app-integrated scenes (VAM, Voxy, custom apps).

The General tab

The top-level settings of the scenario.

• Chat Flow — Chat is normal back-and-forth where you and the character(s) take turns. Story excludes the user from the conversation entirely (the AI narrates, the user just watches/triggers).
• Attached Memory Book — extra world info pulled in just for this scenario. See Memory books.
• Narrator — the voice used to read events out loud.
• App — which host app this scenario targets (e.g. Voxta.VirtAMate). Apps filter which scenarios show up in their scenario dropdown. Leave it blank for generic scenarios.

Roles

Roles are named slots that characters get assigned to. The Voxta UI and the templating layer reference characters by their role, not by their literal name.

The role's Name is what you'll use in templates:

• {{ char }} always refers to the first role's character.
• {{ scenario_chars.your_role_name }} refers to whichever character is assigned to a specific role.

You can mark roles as disabled by default — useful when a character should be introduced later, e.g. when an event fires. Enable/disable them from a script with chat.setRoleEnabled('role_name', true).

Scenario template

A Scriban template that overrides the character's scenario field. If you leave it blank, the first character's own scenario is used. Override it when the scenario should describe the world differently for one chat than the character does at rest.

See Templates for the full template syntax and available variables.

Bootstrap messages

How the chat starts. A Scriban block that produces a sequence of messages. Each line generates one message:

{{ char }}: The first character speaks
{{ user }}: The user
{{ scenario_chars.your_role_name }}: A specific role's character speaks
{{ event }}: A narrated event everyone can see
{{ note }}: A silent note (visible in transcript, not read aloud)
{{ secret }}: Visible only to the character
{{ instructions }}: Visible only to the user

The messages fire in order. If you end with {{ user }}: ... the chat waits for the user to type/speak first instead of having the character open.

See Messages for the full message taxonomy.

Scripts

A scenario can ship one or more JavaScript files. The special index script runs when the chat starts and is the right place to initialize chat variables and set up event listeners.

Other scripts in the scenario can be imported by name from events, actions, and triggers:

import { yourExports } from "./file_name";
// Parent scenario scripts use ../base/
import { somethingElse } from "../base/file_name";

See Scripting for the full API.

Events, Actions, Contexts

Three separate scenario-scoped tabs:

• Events — automatic story moments. "After 5 messages, a phone rings."
• Actions — inference-driven choices. "When the user asks to sit down, play the sit animation."
• Contexts — sentences injected into the prompt. "The character is wearing a blindfold."

These all live as tabs within a scenario and can be combined freely.

Impersonation

By default the user plays themselves (their profile name/description). A scenario can override this with Impersonation — useful when the user is supposed to be playing a specific role in the story (the detective, the new student, etc.).

When impersonation is on, {{ user }} in templates renders the impersonated identity, not the user's profile.

What's next