Stage Editor

The Stage Editor is a full-screen canvas for laying out buttons and HUD widgets over a scenario's background. Drag them where they go, style them, and attach the script that runs on click.

It edits the same objects as the Interactions tab — it just gives you the scene to place them on.

Opening it

1. Set the scenario's default view to Stage, and a background, under Apps.
2. Go to Interactions, open a button or HUD widget.
3. Click the full-screen / position button on its row.

On screen

Tabs

General — name, description, conditions, once, set-flags, and the message the element injects.

Position — three modes:

• Flow (default) — the button sits in the normal layout.
• Custom position — drag it on the canvas. Stored as percentages, so it survives any resolution.
• Hotspot — trace an invisible shape over the scene to make a door, a sign or a window clickable. This is the right tool for anything that isn't a rectangle. (Older buttons may still use shape distortion, a four-corner perspective warp; hotspots supersede it.)

Style (buttons) — presets to start from, then fonts, fill (solid / gradient / stripes), shadow and text-shadow styles, borders, radius, opacity, hover effects, and an image background. Two presets matter for scene-painted elements: Invisible Hotspot and Hint Tint. Combine an image background with hidden text for a clickable door painted onto the scene. Styles can be copied and pasted between buttons.

Script (buttons) — the click handler. A regular script with the full chat API.

Widget (HUD widgets) — bar or text, the variable it watches, its range and look. See Buttons & controls.

Patterns

Navigating between locations

Use one enum flag as the current location, and gate every button and context on it. Setting the new location auto-clears the old one, so the whole scene swaps at once.

export function trigger(e) {
  chat.setFlag("places.backyard");
  chat.setBackground(chat.scenario.assets.get("backgrounds/backyard.png"));
}

Then a context gated on places.backyard tells the AI where the user is.

Sequencing a click

chat.queue.* waits for the current audio to finish, so a knock, a door opening, and the room behind it land in order:

import { chat } from "@voxta";

export function trigger(e) {
  chat.appTrigger('PlaySound', chat.scenario.assets.oneOf('SFX/Knock_'), 100);

  if (Math.random() < 0.33) {
    chat.queue.appTrigger('PlaySound', chat.scenario.assets.get('SFX/DoorOpening.mp3'), 100);
    chat.queue.appTrigger('SetBackground', chat.scenario.assets.get('backgrounds/room.png'));
    chat.queue.roleEnabled('tenant', true);
    chat.queue.roleMessage('tenant', '');
    chat.queue.setFlags('places.tenant_room');
  }
}

See Queued vs immediate.

At chat time

Stage view renders the current background, every button whose conditions pass, and the HUD. Change a flag and the visible buttons change with it — that is the whole navigation model.

For the scripted HUD, popups and screen effects that also live on the stage, see HUD & stage effects.

See also