Game commands
Français · Type: reference · Audience: author · Context: engine repository, created project · Status: ready · Applies from: 4.3.0
The commands a rule, a topic, a script or a listener runs, grouped by what they do. Every command is data: a plain string, or an object whose key names the command. The generated DSL reference gives each command's exact shape, field by field; this page says what each does and when to use it.
How commands run
A command list (do, then, onEnter…) runs in order, each command waiting for the previous one to finish. A single
command written as plain text makes the hero speak: 'There. A step up.'. The catalogue of commands is
src/engine/core/cmds.ts (CMD_KEYS): it says which commands change the game's
state (what the solver and the saves care about) and which only show something. A key it does not know is refused by
the validator.
Speech
| Command | Effect |
|---|---|
'text' | The hero says the line. |
{ say: ['grandma', 'text'] } | A character speaks. 'hero' always designates the hero, whatever its id. An offscreen character (narrator, radio) speaks in a frame at the top of the screen. |
{ say: ['grandma', 'LOOK OUT!'], shout: true } | A shout: bigger text, and it shakes. |
{ say: [...], id: 'house.l-careful' } | A line with a stable id: its translation and its voice clip follow the id (translations). |
{ say: [...], voice: 'grandma_01' } | Plays that clip of audio.voices; the line stays while it plays (voices). |
A line stays on screen for as long as it takes to read, or until a tap. validate warns about a line above 140
characters; under 90 reads comfortably on a phone (dialogues).
Movement and poses
| Command | Effect |
|---|---|
{ walk: 'shelf' } | The hero walks to the shelf's approach point (set in the layout). |
{ walk: [300, 350], who: 'grandpa' } | Grandpa walks to that point (any actor in the room; with no walk pose, they slide in their current pose). Where he stops is kept in the save. |
{ face: 'left' }, { face: 'grandma' }, { face: 'hero', who: 'grandma' } | Turn left, or turn to face someone or something (the hero included). In a cutscene nobody is acted on, so nobody turns by themselves: this is how two characters look at each other. |
{ pose: ['cat', 'sleep'] } | A lasting pose (until the next one). Character poses: see their sprites sheet. |
{ anim: ['hero', 'use'], ms: 600 } | Hold the pose for the given time, then return to normal. Works for any actor in the room, even one in pose: 'front': { anim: ['grandpa', 'surprise'], ms: 900 } plays the surprise pose from their sheet, then they go back to front. at: { 2: [{ sfx: 'thud' }] } runs commands when the pose reaches that frame. |
{ place: ['grandpa', [420, 360]], face: 'left' } | Teleport a character. |
{ launch: { target: 'vase', to: [420, 310], height: 60, rotate: 360, ms: 900 } } | Stage physics (3.4): a ballistic flight of a prop or a character from where it stands (or from) to to, a point or a thing. Computed, never simulated: the same flight on every device. A character stays where it lands; a prop until the room is entered again: follow it with what it means ({ hide: 'vase' }, { prop: ['vase', 'broken'] }). |
{ spring: { target: 'lamp', axis: 'rot', amplitude: 12, frequency: 3, damping: 0.25 } } | A damped swing or shake around its place (axis x, y or rot). |
{ path: { target: 'bat', points: [[80, 120], [300, 60], [560, 140]], orient: true } } | Along a smooth curve through the points, turned along it. |
{ follow: { target: 'parrot', leader: 'hero', offset: [10, -70], ms: 3000 } } | Keeps one at an offset from another for a while. |
{ wait: 500 } | Pause, in milliseconds. In a script, the player keeps playing meanwhile. |
{ parallel: [[…], […]] } | Play several lists at the same time (e.g. two characters walking). |
{ camera: … }, { play: [prop, anim] }, { stopAnim: prop } | The camera of a wide room and prop animations: geometry, staging. |
With reduced motion, every motion jumps to its end. The motions (launch, spring, path, follow) are presentation
only: the solver does not see them. Making a character walk on its own, a patrol: moving characters.
The world
| Command | Effect |
|---|---|
{ prop: ['lamp', 'on'] } | Change a prop's state. 'room.prop' targets another room. |
{ show: 'ghost', fade: 1200 }, { hide: 'ghost', fade: 1500 } | Make an actor or prop appear or disappear, with an optional fade. Kept in the save. |
{ gain: 'rope' }, { lose: 'rope' } | Add or remove an inventory item. gain on an item marked used reactivates it. |
{ used: 'rope' }, { used: ['rope', 'badge'] } | The item has served its purpose: it stays in the bag, greyed out (items). |
{ set: 'tied' }, { set: ['tries', 3] }, { unset: 'x' }, { inc: 'tries' }, { inc: 'tries', by: -1 } | Flags: checkboxes, counters and values, named however you like (flags, variables and events). |
{ unlock: 'market' } | Unlock a place on the map. A locked place does not appear (world map). |
{ goto: 'market', at: 'gate' } | Change rooms; at is an entry point of the layout, or a point. |
{ map: true } | Open the map. |
{ moveActor: ['grandpa', 'house'], at: 'door' } | Send a character to another room (moving characters). |
{ emit: 'bell_rang' } | Fire an event: its listeners run right here (scripts and events). |
{ startScript: 'id' }, { stopScript: 'id' } | Start a script from the top, or stop it (scripts). |
{ waitUntil: COND }, { waitEvent: 'gong' } | In a script: pause until a condition holds, or until an event. |
{ switchPlayer: 'laverne' }, { transfer: ['tentacle', 'hoagie'] } | Several playable characters: take control of another one, hand an item to another one (heroes). |
{ custom: 'sparkle', args: { ms: 1200 } } | A command the game defines in code (custom code). |
Audio and effects
| Command | Effect |
|---|---|
{ sfx: 'coin' } | Sound effect. caption: '[A door slams upstairs]' writes what it means for whoever cannot hear it (sound effects). |
{ music: 'market' } | Change the music (crossfade). |
{ music: { push: 'minigame' } } then { music: { pop: true } } | Temporary music, then back to the previous track. |
{ music: { once: 'jingle' } } | Play a track once on top, then the music resumes. |
{ music: { stinger: 'success' } } | A short cue (a track of audio.music or a sound of audio.sfx) on the next beat of the score that plays (3.5); at once with a single mix (music). |
{ music: { stop: true } } | Stop the music. |
{ toast: 'New place: Market' } | A small message at the top of the screen (id gives it a stable id for its translation). |
{ shake: 400 } | The screen shakes, for that many milliseconds. |
Logic
| Command | Effect |
|---|---|
{ if: COND, then: […], else: […] } | Branch on a condition. |
{ once: […], id } | Only once in the whole game. |
{ nth: [[…1st time], […2nd time], […after]], id } | By number of times; the last branch repeats. |
{ cycle: [[…], […]], id } | In a loop: 1, 2, 1, 2… (e.g. a record player alternating two tracks). |
{ random: [[…], […]], id } | At random, never the same one twice in a row. |
In schema 3 each of once, nth, cycle and random needs a stable id: its count is kept in the save under it
(key is the old, v2 name). Remembering something for later is a flag (set); signalling a moment is an event
(emit): which to use.
Sequences and screens
| Command | Effect |
|---|---|
{ cutscene: […] } | Cutscene: black bars, a "Skip" button. Skipping plays the rest instantly: effects (items, flags, states) still apply. |
{ choice: [{ id, text, do, if?, once?, img? }, …] } | The player picks a line; the hero says it, then do plays. img shows the option as a card with that image (dialogues). |
{ talk: 'grandma' } | Open an actor's conversation menu from a script. |
{ minigame: 'pipes', params: { tiles: …, cols: 4 }, then: […] } | Launch a minigame. A minigame is never failed: then always plays, even if you skip. All its images come from params (minigames). |
{ phone: 'grandma', do: […] } | Incoming call: ringtone (skin.sounds.phone), a Pick-up button, then the lines in do. During the call, the caller shows in a phone frame (bottom left), mouth animated while they talk; their lines appear at the top. |
{ phone: ['lou', 'seller'], do: […] } | A call with several people: all shown side by side in the same frame (the first one in front), each at its own size (height). Each { say: ['lou', …] } animates the right person's mouth. Pose shown: the first of skin.callPoses that exists (default phone, front, face, idle); mouths from mouths.phone (otherwise the phone_talk pose alternates, otherwise a small bounce). Ids are characters from characters (no actor needed in the room). |
{ guide: { verb: 'look', target: 'shelf', say: 'Pick Look, then tap the shelf.' } } | Tutorial: the hero gives the instruction, the verb blinks, the target glows. It waits until the player does exactly that action; any other action repeats the instruction. |
{ hint: true } | Give the current hint (same as talking to the hint item). |
{ ending: true, after?: […] } | The sealed ending (GameDef.ending): scratch ticket, confetti, then after, then the final card. { reveal: true } is the old name, still accepted (the sealed ending). |
{ end: true } | End of game. |
Limit ·
custom-for-the-restWhat none of these commands does needs a custom command, written in TypeScript with its declared effects (custom code). There is no command that runs arbitrary code from the content.
Related identifiers
- Every command's exact shape: the DSL reference. The types:
Cmdinsrc/engine/core/types/content.ts. - Reactions, conditions, scripts and events.