Events

Events are scenario-scoped story beats that trigger automatically — by elapsed time, message count, flag state, or random probability — rather than being chosen by the AI.

Think of them as the "scripted plot points" sitting alongside the AI's free-form responses. The chat is going along normally, and partway through, an event fires that injects a new development.

When events fire

An event fires when all of its conditions are met. The available conditions:

Target, Match, Once, Flags

Shared with actions — see Actions → Conditions.

Probability

The chance of the event firing once its other conditions are met. Stacked with the rest of the conditions: a 50% probability event with a 5-to-10-message window ramps from 10% probability at message 5 up to 50% at message 10 (until it fires).

Messages count

Fire after a specific number of messages have been sent.

By default the count is measured from the start of the chat. You can switch it to "since flag" — counting from the last time a given flag was set. This enables looping events: have the event set its own flag and fire "5 messages since flag X" → the event happens every 5 messages indefinitely.

Chat time

Same idea as messages count but measured in real seconds, not message count. Be aware: chat time resets if you exit and come back — the calculation is based on time since the last message in the active session, not absolute wall-clock.

Interface

Events listed in the scenario UI:

• Reorderable — drag to change the evaluation order.
• Editable and deletable.
• Toggle-able — temporarily disable an event for testing without losing its config.

Patterns

Sequential chained events

Use flags to chain events together:

1. Event A sets flag event1.
2. Event B's condition is since flag event1 with a 5-message gap.
3. Event B sets !event1 and event2.
4. Event C reacts to since flag event2.

You can build long pre-scripted sequences this way, with easy adjustments to spacing.

Branching narrative

Use a script to set one flag or another based on user choice. Both flag paths can set a shared direction_chosen flag so the rest of the scenario knows the branch happened:

import { chat } from "@voxta";

export function trigger(e) {
  if (e.message.text.toLowerCase().includes("left")) {
    chat.setFlag('went_left');
  } else {
    chat.setFlag('went_right');
  }
  chat.setFlag('direction_chosen');
}

Looping events

Self-resetting flag pattern:

Event: "5 messages since flag heartbeat"
Effect: set flag "heartbeat" (replaces itself)

The event fires every 5 messages indefinitely.

What's next