Gameable Engine

Cutscenes ​

An option, never a default. A cutscene is a short clip drawn over the stage at a moment that matters (a boss falls, a level ends, a reveal). A game gets one only when the person asks for it; no template plays one on its own, and the kit's rule is: cutscenes are available on request, never by default.

The end goal (Isaac, 30 Sep 2026) is a cutscene design panel in the studio's canvas: a tool creators use right there to make their cutscenes and to manage when each one is called. Until that exists, this page says what to call when a cutscene is asked for.

What exists today ​

  • The maker (the studio's companion, POST /cutscenes/make): a drawing of the moment in the game's style from the game's own references, then a clip from that drawing, through the build's own drawing and clip steps. It returns the clip, its first frame as a poster, and the cost and the time per step. The clip is made at build time and shipped with the game as a file; a game never calls the maker at play time.
  • The player (createCutscenePlayer in @aosengine/core): the clip over the canvas with a fade in and out, the poster until the first frame, a tap or a key (Escape, Enter, Space) to skip when allowed, hooks for the host to pause the stage and duck the game's sound, and the phone rules (playsinline; muted when the browser refuses sound before a touch; the next tap starts it when it refuses even that).
  • The bridge (createCutsceneBridge in @aosengine/wasm-host): the player wired to a running engine (the time scale to 0 under the clip and back after; the mixer's master bus ducked to 15 % and back) and to the game (the commands in, the end out as an event).
  • The facade (cutscene in @aosengine/sdk): what game code calls.

What to call ​

The clip is a video entry of the manifest, with an optional poster. Game code names it by id, never by URL (the engine's rule for every asset):

json
{
  "id": "kael-falls",
  "type": "video",
  "src": "cutscenes/kael-falls.mp4",
  "poster": "cutscenes/kael-falls.jpg"
}

In the game, preload it when the moment becomes possible and play it at the event; the end comes back as a cutscene-event:

ts
import { cutscene } from '@aosengine/sdk';

cutscene.preload('kael-falls'); // when the fight starts: the clip is fetched, so play starts at once
cutscene.play('kael-falls', { fadeIn: 300, fadeOut: 400, skippable: true, pause: true }); // when the boss falls

// each tick, in ctx.events:
for (const e of ctx.events) {
  if (e.tag === 'cutscene-event') {
    // e.val.kind: 'ended' | 'skipped' | 'failed'; e.val.asset; e.val.seconds
  }
}

pause: true (the default) freezes the stage under the clip (the time scale to 0: no ticks, no animation) and ducks the game's sound; pause: false lets the game run on under it, sound included. cutscene.skip() ends the one playing.

On the page, the bridge is wired once and handed to the adapter; without it a cutscene command warns once and does nothing:

ts
import { createCutsceneBridge } from '@aosengine/wasm-host';

const cutscenes = createCutsceneBridge({
  engine,
  events: adapter.events,
  mixer: engine.get('audio'),
});
// createEngineAdapter({ ..., cutscene: cutscenes.handle })

A page that plays a clip of its own, outside the game's logic, uses cutscenes.player (preload(url, { poster }), play(url, options), skip()).

The maker: what it takes and what it gives back ​

POST /cutscenes/make (multipart) on the studio's companion:

FieldWhat
promptthe moment, in plain words (what happens)
stylethe game's style words
seconds3 to 8 (default 5)
frame16:9 or 9:16
resolutionthe clip service's setting; the build's own 4K by default
pronounthe hero's, for the drawing's wording (her, his, their)
characterfiles: the hero's own pictures
monsterfiles: the monster's
gamefiles: a frame of the game at the moment (its place, light and colours)
moodfiles: the game's mood pictures (style, palette, brushwork)

It answers the state at once and runs in the background; GET /cutscenes/{id} gives the state (drawing, clip, finishing, done or failed with what failed in plain words), the cost and the time per step, and the files: drawing.png, poster.jpg, clip.mp4 (the web copy, under 5 MB), light.mp4 (the phone copy, under 2 MB), source.mp4 (as the service returned it). POST /cutscenes/{id}/retry runs only what is missing: a finished drawing is never drawn (or paid) again.

Measured on 30 Sep 2026, four cutscenes of 5 s at 16:9: the drawing 42 to 50 s and $0.15 with six references; the clip 110 to 127 s and $0.80; the poster and the copies about 3 s; 165 to 181 s and $0.95 a cutscene. Both steps run through the outside service; neither has an own-GPU road in the code.

The references rule, and the known faults ​

The references are the game's own pictures of its characters and of the moment: the hero's and the monster's pictures, a frame of the game at the moment, the game's mood pictures. Three candidates of one moment differ in the prompt, never in the references. The faults seen on the first four (Hollow Reign's boss fall, judged by Isaac): likeness drifts (the monster came back as a different creature in two of four; the hero's outfit gained a fur collar in one), and invented objects (a bell hanging into the frame that the game does not have). A cutscene is never "the" cutscene until the person picks it, and these faults are why the design panel in the canvas is the end goal: the person sees the drawing before the clip is paid for, and fixes it there.

See also ​