Voxta Build your first scenario
One example end to end — a role, a context, an event, a button, and a script.
Every other page here explains one piece. This one builds a small thing that works, so the pieces have somewhere to sit.
We'll make a night watch: a guard at a gate, who notices after a while that it's getting cold, and whom you can offer a drink.
You need a character already. Any will do — Characters if you don't have one yet.
1. Create the scenario
Studio → Scenarios → Create. Name it Night Watch.
On the Scenario tab, set the scenario template — this is what the AI is told about the situation:
{{ char }} is on night watch at the north gate. It is late, quiet, and getting cold.
{{ user }} has come up the road.2. Give it a role
Roles → Add. Name it guard and assign your character.
The first role is what {{ char }} refers to, and roles are how scripts address characters later — chat.roles.guard rather than a name that might change.
3. Open the chat
Bootstrap messages decide how it starts. On the Scenario tab:
{{ char }}: Far enough. State your business.At this point you have a working scenario. Start a chat and check the character opens with that line.
Get this far before adding anything else. A scenario that misbehaves later is much easier to diagnose when you know the plain version worked.
4. Add state the AI can see
Now the cold. We want the character to know it's cold, but only once it is.
Go to Interactions.
A context
Contexts → Add:
- Text:
{{ char }} is cold, and has been out here too long. - Conditions:
is_cold
Nothing sets that flag yet, so nothing changes. A context is a sentence added to the prompt whenever its condition holds — see Contexts.
An event to set it
Events → Add:
- Name:
gets_cold - Timing:
AfterAssistantMessage - Trigger: anchored to chat start, min messages
6, max fires1 - Effect → Set flags:
is_cold - Effect → Note:
The wind has picked up.
Six messages in, the flag flips on, the note appears, and the context starts riding along in every prompt from then on. See Events.
Start a fresh chat and talk for six messages. The character should start acting cold without you mentioning it.
5. Give the player something to do
Buttons → Add:
- Name:
Offer your flask - Conditions:
is_cold && !drank - Effect → Set flags:
drank - Effect → Event:
{{ user }} offers {{ char }} a flask.
The button only appears once the character is cold, and disappears once used. That's the whole pattern behind stage-view navigation too — one flag, and everything gated on it. See Buttons & controls.
6. Make it do something a field can't
Say you want the guard to warm up over the next few minutes, on their own.
Add a script to the button instead of the flag effect:
import { chat } from "@voxta";
export function trigger(e) {
chat.setFlags('drank', '!is_cold');
chat.event('{{ char }} takes a long pull from the flask.');
// Cold again in three minutes of chat time
chat.setTimeout(() => {
chat.setFlag('is_cold');
chat.note('The warmth wears off.');
}, 180);
}That's the point at which scripting earns its place: a delay, a computation, or a decision no checkbox expresses. See Scripting.
7. Watch it work
Open the chat inspector while you test. The Flags section shows what is set right now, and Contexts shows what actually reached the prompt.
If the character isn't acknowledging the cold, that pair answers it in one look: either the flag never got set, or it did and the context's condition doesn't match.
Where to go next
| You want to | Read |
|---|---|
| More than one character in the scene | Scenarios → Roles |
| The AI to choose to do something | Actions & tools |
| Backgrounds, music, avatars | App triggers and Audio |
| A visual-novel scene with clickable art | Stage Editor |
| Health bars, inventories, popups | HUD & stage effects |
| To share it | Packages |