App triggers

Drive the host app — Voxta Talk UI, VAM scenes, Voxy avatar, custom apps — from a scenario script.

App triggers are how a scenario reaches outward and tells the host app to do something: change the chat view, swap avatar images, play music, fire a sound effect, change a VAM scene state.

You call them from a script:

import { chat } from "@voxta";

export function trigger(e) {
  chat.appTrigger("TriggerName", ...params);
}

The available triggers depend on which app is running the chat. The trigger names below are for Voxta Talk (the default web UI). For VAM, see VAM app triggers.

Asset helpers

Most modern triggers take an Asset object instead of a path string. Get an asset from a character's or scenario's asset collection:

Function	What it does
`assets.get(name)`	Get a specific asset by filename. Throws if it doesn't exist.
`assets.oneOf(prefix)`	Random pick from assets whose filename starts with the prefix. Throws if none match.
`assets.oneOrNoneOf(prefix)`	Same as `oneOf` but returns null/undefined instead of throwing.

// Specific
const happy = e.character.assets.get("happy_face.webm");

// Random from a set
const emote = e.character.assets.oneOf("emote_");

// Optional random
const effect = chat.scenario.assets.oneOrNoneOf("special_effect_");

Path-based access still works for legacy triggers — just pass a string path relative to the character or scenario Assets folder.

Voxta Talk triggers

Emote

Pop an emoji bubble above the character.

chat.appTrigger("Emote", "💡", "yellow");
chat.appTrigger("Emote", "❤️");

Param	Type	Notes
`emoji`	`string`	A single emoji.
`color`	`string?`	Color name (`"red"`) or hex (`"#FF0000"`).

SelectView

Switch the chat interface mode.

chat.appTrigger("SelectView", "portrait");

ChatView values:

talk — voice-centric, minimal UI.
portrait — avatar-focused.
chat — full view with chat history.

SetAvatar (asset-based)

Recommended. Set the avatar using an Asset object.

chat.appTrigger(
  "SetAvatar",
  e.character.assets.get("mood.png"),
  e.character.id,
  "untilEndOfSpeech"
);

Param	Type	Notes
`asset`	`Asset`	The image/video to display.
`targetCharacterId`	`string?`	Whose avatar to change. Defaults to the asset's owner.
`until`	`AvatarExpiration?`	How long the override sticks.

SetAvatar (path-based)

Legacy. Set the avatar with a string path.

chat.appTrigger("SetAvatar", "talk.webm", e.character.id, e.character.id, "untilNextMessage");

SetAvatarFromScenario

Avatar from the scenario's asset folder instead of a character's.

chat.appTrigger("SetAvatarFromScenario", "intro.png", e.character.id);

PlayMusic

Background music track. Starting a new one stops the previous one.

chat.appTrigger("PlayMusic", chat.scenario.assets.get("background_music.mp3"));

PlayAmbient

Ambient sound. Multiple ambient tracks can play simultaneously with different track names.

chat.appTrigger(
  "PlayAmbient",
  chat.scenario.assets.get("rain_loop.ogg"),
  "weather_sounds",
  0.6  // volume 0.0–1.0
);

StopMusic / StopAmbient

chat.appTrigger("StopMusic");
chat.appTrigger("StopAmbient", "weather_sounds");

PlaySound

One-shot SFX. Overlaps with other sounds.

chat.appTrigger("PlaySound", e.character.assets.get("door_creak.wav"), 0.9);

PlayVoice

Queue a pre-recorded voice line as if it were TTS output.

chat.appTrigger("PlayVoice", e.character.assets.get("greeting_line_01.mp3"));

SetBackground

Swap the background image/video.

chat.appTrigger("SetBackground", chat.scenario.assets.get("main_room_bg.jpg"));

Avatar expiration values

Used in SetAvatar / SetAvatarFromScenario:

Value	Behavior
`untilNextMessage`	Reverts after the next chat message is processed.
`untilEndOfSpeech`	Reverts when the current TTS line finishes.
undefined (omit)	Persists for the session until explicitly changed.

By default chat.appTrigger(...) fires immediately. If you want the trigger to fire after the character finishes speaking (e.g. play a sound effect once the dialogue line completes), use chat.queueAppTrigger(...) instead:

chat.queueAppTrigger("PlaySound", chat.scenario.assets.get("door_close.wav"));

The queued trigger waits in the message queue and fires when the character's speech completes.

VAM triggers

When the chat is hosted by the VAM plugin, app triggers can drive any VAM atom storable — Timeline animations, light intensities, material params, etc. The trigger signature is different (atom + storable + param + value):

chat.appTrigger('Action', 'Person', 'plugin#2_VamTimeline.AtomPlugin', 'Play wave_hello');

See VAM → App triggers for the full VAM-specific reference.