Script API

import { chat } from "@voxta";

chat.instructions('Only you see this');
chat.note('Both sides see this, no reply');
chat.secret('Only the character sees this');
chat.event('A door slams');            // narrated, triggers a reply
chat.story('Describe the storm');      // story writer expands it
chat.userMessage('Where are we going?');
chat.characterMessage('To the garden');
chat.roleMessage('detective', 'Right behind you');

chat.secret('Standing by the window.', { expiresAfterTurns: 2 });

export async function trigger(e) {
  await chat.story('The lights go out.');
  chat.appTrigger('PlaySound', chat.scenario.assets.get('breaker.wav'));
}

// Or pass a callback instead
chat.story('The lights go out.', () => chat.setFlag('blackout'));

chat.customMessage({
  role: 'Secret',            // Assistant, User, Event, Note, Secret, Instructions
  text: 'Then something incredible happens',
  useStoryWriter: true,
  maxNewTokens: 200,
  maxSentences: 2,
  allowMultipleLines: false,
  includeChatHistory: false,
  triggerReply: false,
  narrate: false,
  expiresAfterTurns: 5,
});

chat.variables.score = 0;
chat.set('score', 0);              // same thing
const s = chat.get('score', 0);    // with a default
chat.variables.score += 5;

chat.setFlag('wears_hat');
chat.setFlag('!wears_hat');            // unset
chat.unsetFlag('wears_hat');
chat.setFlag('pose.sitting');          // enum — clears other pose.*
chat.setFlags('a', 'b.enum', '!c');
chat.hasFlag('wears_hat');

chat.setFlag('cooldown', { messages: 10 });   // expires after 10 messages
chat.setFlag('rush_hour', { seconds: 120 });  // expires after 2 min chat time

chat.setContext('crown', '{{ char }} is wearing a crown.', 'my_flag');  // third arg is an optional flag filter
chat.setContext('crown');                                              // clear

chat.character          // main character
chat.roles.guard        // by scenario role
chat.characters         // every character in the scene
chat.user
chat.narrator

chat.setRoleEnabled('guard', false);        // remove from the chat
chat.setCharacterCanSpeak(false);           // present, but silent
chat.setCharacterCanSpeak(false, 'guard');

chat.scenario.assets.get('sounds/door.wav');   // exact path, throws if missing
e.character.assets.oneOf('emote_');            // random match (regex), throws if none
e.character.assets.oneOrNoneOf('rare_');       // random match, undefined if none
chat.scenario.assets.matchFiles('^bg/.*png$'); // all matching paths

chat.appTrigger('Emote', '🌳', '#00ff00');
chat.setBackground(chat.scenario.assets.get('room.jpg'), 1);

// Queued: runs after the current speech finishes
chat.queue.appTrigger('PlaySound', chat.scenario.assets.get('ping.mp3'));
chat.queue.roleMessage('guard', 'Halt.');
chat.queue.roleEnabled('guard', true);
chat.queue.setFlags('a', '!b');

chat.setTimeout(() => chat.setFlag('late'), 4);
const h = chat.setInterval(() => chat.setFlag('tick'), 30);
chat.clearInterval(h);

chat.time;  // seconds elapsed since the chat started

chat.generateImage('A candlelit tavern at night');
chat.generateImage('A neon street', { analyze: true });        // character sees the result
chat.generateImage('A portrait', e.character);                 // target a character

chat.imagine();                                                // LLM writes the prompt from context
chat.imagine('the room she just walked into');
chat.imagine({ prompt: 'her childhood home', analyze: true });
chat.imagine({ params: { avatar: true } });                    // use as the avatar
chat.imagine({ params: { background: true, layer: 1 } });      // use as a background

chat.generateAnimation({ prompt: 'A slow curtsy', duration: 4, seed: 12345 });
chat.perform('Throw both arms up and jump once');              // the character acts it out

chat.interrupt();                                              // stop speech / cancel the reply

export async function trigger(e) {
  const line = await chat.infer('Write a short, cryptic fortune.', { maxSentences: 1 });
  chat.event(line);
}

const verdict = await chat.infer('Did the user agree to the deal?', {
  schema: { agreed: 'boolean', tone: ['friendly', 'hostile', 'neutral'] },
});
if (verdict.agreed) chat.setFlag('deal_struck');

chat.addEventListener('userMessageReceived', (e) => {
  e.rewriteUserMessage(e.message.text.replace(/John/g, 'Jane'));
});

chat.addEventListener('start', () => {
  chat.variables.score = 0;
});

// Narrow the candidate actions before the inference pass runs
chat.addEventListener('beforeSelectActionInference', (e) => {
  if (e.layer === 'movement' && chat.hasFlag('tied_up')) e.setActions([]);
});

chat.addEventListener('action:roll_dice', (e) => {
  return `You rolled a ${1 + Math.floor(Math.random() * 20)}.`;
});

chat.setActions('desk', [
  {
    name: 'adjust_desk_height',
    description: 'Adjust the desk between sitting (0) and standing (5)',
    layer: 'desk_control',
    timing: 'AfterAssistantMessage',
    invocation: 'ActionInference',   // or 'ToolCalling'
    arguments: [
      { name: 'height', type: 'integer', description: 'Desk height 0-5', required: true },
    ],
  },
]);

chat.addEventListener('action:adjust_desk_height', (e) => {
  chat.set('desk_height', e.arguments.height);
});

chat.setButtons('doors', [
  { name: 'Left door', description: 'Open the left door', effect: { setFlags: ['chose_left'] } },
  { name: 'Right door', description: 'Open the right door', effect: { setFlags: ['chose_right'] } },
]);

chat.setControls('settings', {
  title: 'Settings',
  controls: [
    { type: 'toggle', variable: 'lights_on', label: 'Lights' },
    { type: 'slider', variable: 'volume', label: 'Volume', min: 0, max: 100, step: 5, live: true },
  ],
});