A cutscene is a timeline: camera keyframes, timed lines of dialogue, sound cues, letterbox bars and an input lock, all against a clock. Scenes are stored in the map and started by a trigger action.
The editor is a scrubbable timeline. Frame the shot in the map viewport, open the Cutscene module, press Set keyframe from current view, and the scene interpolates between keyframes using the same camera machinery the trailer pipeline uses. The preview box under the timeline is drawn by the same player and the same letterbox/subtitle component the match uses, so what you scrub through is what plays. (The keyframe takes the viewport's centre and zoom; set yaw and pitch on the keyframe itself.)
What a scene contains
| Field | What it does |
|---|---|
id | The name a trigger uses to start it |
durationSec | How long the scene lasts, in seconds |
lockInput | Whether the player is stopped from acting during the scene. On by default |
letterbox | Whether the black bars come in. On by default |
camera | The 3D camera track: keyframes, each with a time in seconds, the point it looks at, yaw, pitch, distance and an easing |
lines | Timed dialogue: the text, an optional speaker, a start time t and how long it stays up, hold (3 seconds if you leave it out), both in seconds |
sounds | Sound cues: a time in seconds and a sound id (the ids playSound takes) |
camera2d | Legacy camera track for older maps. New maps should use the camera track above |
hud | Keep the HUD visible. Off by default: the HUD, minimap and trigger UI are hidden for the scene and come back when it ends |
dayNight | Light the scene at a fixed time of day (and optionally let the sun move). This only changes what the scene looks like — fog of war, night vision and anything else that depends on the match's real time of day are unaffected, and the match's lighting returns when the scene ends |
The rule that matters
A cutscene cannot change the game. No spawning, no orders, no resource changes. Those are all trigger actions and they belong in a trigger.
The reason is skipping. Camera position and letterbox bars are presentation: one player skipping the scene while another watches it is fine, because neither affects the simulation. Spawning a unit is not presentation. If a scene could spawn, then a player who skipped it would be running a different world from a player who watched it, and the match would fork the moment the skip happened.
So the simulation records only that scene X started on tick T, and when it
ends. Everything the player sees is built from that on each client, and
everything the scene needs to actually do is expressed as trigger actions
before the playCutscene action, or in a trigger on the Cutscene finished
event after it.
In practice this is a small change to how you write a scene. Instead of:
SCENE "ambush"
camera to "ridge_view"
spawn 6 goblin_brawler at "ambush_point" ← not allowed
line: "They were waiting for us."write:
TRIGGER hero enters region "ravine"
create 6 goblin_brawler at region "ambush_point" for player 5
play cutscene "ambush"
SCENE "ambush"
camera to "ridge_view"
line: "They were waiting for us."The units exist before the camera moves, every client agrees they exist, and the scene is purely what the player watches.
Timing and length
Keep scenes short. The input lock is the expensive part: a player who cannot act for forty seconds is a player who is not playing, and in a multiplayer match everyone else is still going.
For a mission opening, a scene of ten to twenty seconds with three or four camera moves is usually enough to establish a place and a problem. Longer than that and the useful pattern is several short scenes triggered by progress rather than one long one at the start.
Dialogue
Lines are timed against the scene clock: each has a start time and a hold time in seconds, and an optional speaker. There is no voice acting pipeline for custom maps: lines are text.
If a map is part of a series with a recurring cast, name your speakers consistently across scenes. The interface shows the speaker name as written.
Starting a scene
The playCutscene action takes a scene id. It is a normal trigger action, so a
scene can be started by anything a trigger can detect: the map starting, a hero
reaching a region, a building finishing, a timer, a wave count, a player being
eliminated.
A scene started while another is playing (for any of the same players)
replaces it. There is no queue, on the grounds that two cutscenes competing for
the camera is a bug rather than a feature. stopCutscene ends one early.
When a scene ends
The Cutscene finished event fires on the same tick on every machine, with the scene id as its text and how it ended as its value:
| Value | Meaning |
|---|---|
| 0 | Played to its full length |
| 1 | Skipped by every human player it was shown to |
| 2 | Replaced by another playCutscene |
| 3 | Stopped by stopCutscene |
Put what happens after a scene in that trigger rather than after a wait of
the scene's length: a skipped scene ends early, and the event is what knows.
You write every time in a scene in seconds: its durationSec, each line's t
and hold, and each keyframe's t. The game turns the scene's length into
whole game ticks (20 per second), so every machine ends it on the same tick.
The scene plays on the match clock, so pausing the match pauses the scene. When a scene ends the camera returns to where the player left it.
Skipping
Players press Esc (or the Skip button in the bottom bar). Their screen leaves the scene straight away. Whether the scene ends in the game is decided fairly: the skip is sent like any other command, and the scene only ends once every human player watching it has skipped. In single player that is one key press. In multiplayer one impatient player cannot cut the scene short for everyone else, and nothing about a skip can make two machines disagree. Players still watching see "Waiting for N players to skip…" once anyone has skipped; if someone never skips, the scene simply runs to its end.
Moving the camera without a cutscene
The Camera trigger actions work during normal play and are shown only to the players you name: pan to a point over a number of ticks (unlike a scene, these durations are in ticks: 20 is one second), set zoom (1 is the default view), lock to a unit or a point, set bounds to a region, shake, unlock and reset. They move each player's own view and never affect the game itself.
Next: Testing.