GUI

The folder

Your GUI files belong to a folder, which can be defined as follows:

gui: gui/

When you run stage compile, everything in that folder is carried into your game's .stg file. There are three files with fixed names, and then whatever images, fonts and sounds you want to use:

Your page runs in a sandbox. It can run its own scripts, but it can't reach the rest of the app, the player's files or anything else on their machine. Everything goes through one door, Engine.gui, which is the rest of this section.

If you'd rather build your GUI with a tool like Vite or React, that's fine: build into a folder and point gui: at the result.

Engine API

The engine's graphics API is available at window.Engine.gui and below are the available functions.

What's in a turn

A turn is one plain object, and every part of it is there on every turn, so there's nothing to check for before you read it. Pull out the parts you need and draw them:

engine.on('turnChanged', (turn) => {
  const { response, scene, media, achievements, metadata } = turn;

  // draw it
});

Sound

If your game declares sounds, every turn tells you what's heard in media.sounds. Each sound has an id, a src you can hand straight to an Audio, and loop. A looping sound is listed on every turn until your game stops it, so keep yours in step with the list rather than keeping count yourself. That's what makes a loaded save sound right without any extra work. A sound that plays once is only listed on the turn that played it, so play it as the turn arrives.

const loops = new Map();

let playing = [];

const heard = () => engine.preferences.audio !== false;

// Start what should be going and stop what shouldn't.
const listen = () => {
  const wanted = heard() ? playing : [];

  for (const [id, sound] of loops) {
    if (!wanted.some((one) => one.id === id)) {
      sound.pause();

      loops.delete(id);
    }
  }

  for (const { id, src } of wanted) {
    if (!loops.has(id)) {
      const sound = new Audio(src);

      sound.loop = true;

      sound.play().catch(() => {});

      loops.set(id, sound);
    }
  }
};

engine.on('turnChanged', ({ media }) => {
  playing = media.sounds.filter((sound) => sound.loop);

  for (const sound of media.sounds) {
    if (!sound.loop && heard()) {
      new Audio(sound.src).play().catch(() => {});
    }
  }

  listen();
});

engine.on('preferencesChanged', listen);

Where and how a sound plays is up to you: fade it in, duck the music while something else plays, or ignore a sound altogether. Stage only says what's playing.

Images

If your game declares images, every turn tells you what's showing in media.images, in the order they were shown, so the last one is the latest. Each has a src to draw and an alt saying what it shows, which is empty for a image that's only decoration. A image stays in the list on every turn until your game hides it.

Where they go is entirely up to you. Here's the simplest layout, the one Stage's own GUI uses: keep the latest image at the top, in an <img id="image">, and let the story scroll beneath it.

const image = document.getElementById('image');

engine.on('turnChanged', ({ media }) => {
  const latest = media.images.at(-1);

  image.hidden = !latest;

  if (latest) {
    image.src = latest.src;
    image.alt = latest.alt;
  }
});

To set images among the words instead, look at each image's before. For a image this turn showed, it's the number of the line in response it goes before, so 0 is before the first line and response.length is after the last. For a image that's still up from an earlier turn, it's null, because you've already drawn it.

Starting, restarting and loading

Nothing starts until you say so, which is what lets you keep a title screen up for as long as you like. Each of these gives you back a promise that settles once the first turn is in, or fails with the reason. So you can show it, rather than guessing.

A title screen that copes with all of it is only a few lines:

await engine.ready;

play.textContent = engine.isResumable ? 'Continue' : 'Play';
play.onclick = () => engine.begin();
again.hidden = !engine.isResumable;
again.onclick = () => engine.restart();

engine.saves().then((saves) => {
  for (const save of saves) {
    const row = document.createElement('button');

    row.textContent = save.name;
    row.onclick = () => engine.load(save.id).catch((error) => alert(error.message));

    list.append(row);
  }
});

Remembering things

Your GUI can keep a few things of its own for next time: whether the player likes the glowing monitor, which tab they had open, a bookmark. It's kept separately for each player and each game.

const crt = await engine.storage.get('crt', true);   // true if nothing's kept yet

await engine.storage.set('crt', false);
await engine.storage.delete('crt');

get gives you the fallback you pass (or null) when nothing's stored under that name. Because of that, you can't store null or undefined, since they couldn't be told apart from nothing: use delete to take something away. Deleting something that isn't there is fine.

How much room there is is up to whatever's drawing the game. The Stage app keeps twenty names per game and 64 KB per value, in a plain file on the player's machine, so it's no place for secrets. A game opened in a browser keeps nothing, and every call fails saying so. Either way, every call fails with a reason rather than quietly doing nothing, so it's worth a .catch.

Typing

The simplest way to take input is to call engine.submit('open door') from a click, which plays that line exactly as if the player had typed it. You never need a text box at all.

If you'd like a prompt the player types into, it's yours: draw it however you like, an <input> included, catch the keys yourself, and hand the line to engine.submit(text) when they press Enter. Stage doesn't hold what's being typed for you, because you already know.

Two calls tell Stage where the keyboard is, so its own shortcuts leave your keys alone:

The types file

If you write your GUI in TypeScript, or you just like your editor to know what's what, engine.d.ts describes everything on this page and the exact shape of a turn. It has no imports, so copying it in is all it takes:

import type { EngineGui } from './engine';

const engine: EngineGui = window.Engine.gui;

Keep it out of the folder you named with gui:. Everything in that folder is carried into your game, and a .d.ts isn't one of the things a GUI is allowed to carry, so the build would stop. If you build your GUI from a source folder, as Abandoned Empire does, that source folder is the place. For plain JavaScript, a comment above your script does the same job: /** @type {import('../engine').EngineGui} */.