EN Create DSL Reference

DSL reference

Français · Type: reference · Audience: author · Context: engine repository, created project · Status: ready · Applies from: 4.4.0

The content format and its tools · contract: stable · verified by CI (support matrix of 4.4.0, 2026-10-23): Node 22 and 24 on Ubuntu; Windows (windows-latest): the unit suite but six POSIX files · automated checks: jobs check, coverage, second-game, upgrade; CI plan node24, windows, secondGame, freshInstall, upgrade, reference; 4 test files · people's passes: heroes-two-languages not run (#237) · known limits: generated-dsl

A game is data: conditions and commands inside rooms, rules, topics, listeners and scripts, typed by quest-n-click/content (create.rooms.md shows how to write them). This page is the reference of that vocabulary. Its Reference part is generated from the schemas the tools themselves read, so what you read there is what the validator, the solver and the Studio accept.

Where it comes from

The reference below is generated from three sources of the engine:

• the Studio's forms, src/studio/schema.ts (COND_KINDS, CMD_SPECS), with the sentence of each condition and command in tools/dsl-meta.ts;
• the IR's schema, src/engine/core/ir-schema.ts (the objectives' fields);
• the table that says what each field of a game and of a room counts as, src/engine/core/ir-fields.ts.

To regenerate it, in a clone of the engine repository, from its root folder:

# in the engine repository
npm run wiki -- generate create.dsl

npm run wiki -- check fails when this page is behind the schemas. npx tsx tools/dsl-doc.ts writes it again (run in the engine repository; --check exits 1 when the page is behind), as npm run wiki -- generate create.dsl does, and tests/dsl-doc.test.ts fails when it is behind. A created project reads the same vocabulary from its installed engine: there is nothing to generate there.

Stability

Since 4.1.12 the names and meanings listed below are stable (decision D22): a change to one is a break that ships with its migration of the bundled games and saves. What could still grow until 4.1.15, and what is frozen after it for 4.2, is written in docs/dev/DSL-STABILITY.md, with the primitives proposed for that release and why each was admitted or refused. A new primitive enters with a short decision record and reaches the runtime, the validator, the solver, the replay, the Studio, MCP and this page (tests/propagation.test.ts checks it). What the product as a whole promises is in start.stability.md.

The game as the tools see it

npm run ir (in the engine repository; GAME=<id> picks the game, --json prints the whole IR) prints the game's intermediate representation: its logic as plain data, each id with the file and line that writes it. The Studio's Language tab shows the same (studio.language-objectives.md), and the MCP tool get_ir returns it (studio.mcp-tools.md#get-ir). The game's fingerprint hashes it (logic), with the trusted extensions, the presentation and the engine apart; the pause menu shows its short form. See docs/dev/adr/0013-game-ir-and-fingerprint.md and, for the files themselves, engine.file-formats.md.

Reference

Limit · generated-dsl The tables below are generated: edit the schemas or tools/dsl-meta.ts, never this part of the page. They list the custom and minigame commands, not what a game's own commands or minigames do: those belong to the game.

Conditions

A condition is data: a string for a flag, an object for the rest, nested with not, all, any.

Written	Means
'flag'	The flag is set (true, a number other than 0, a word).
'!flag'	The flag is false or was never set.
{ has: 'item' }	The player holds the item.
{ flag: 'x', eq?: value, gte?: n, lt?: n }	The flag's value equals, reaches or stays under a number.
{ not: cond }	The condition does not hold.
{ all: [cond, …] }	Every condition holds.
{ any: [cond, …] }	At least one condition holds.
{ visited: 'room' }	The room has been entered at least once.
{ room: 'room' }	The player is in this room.
{ prop: ['room.prop', 'state'] }	The prop is in that state.
{ unlocked: 'place' }	The place is unlocked on the map.
{ seen: 'key' }	The topic, choice or listener was already seen.
{ actorIn: ['who', 'room'] }	The character is in that room.
{ player: 'who' }	This character is the one the player controls.

Commands

A command is one key of CMD_KEYS; its fields are the Studio form’s. A plain string is the hero’s line.

Command	Shape	Does
say	{ say: [who, line], id?: id, shout?: true, voice?: id }	A character says a line (a plain string is the hero).
walk	{ walk: target | [x, y], who?: who }	A character walks to a thing or a point.
face	{ face: target, who?: who }	A character turns left, right or towards a thing.
pose	{ pose: [who, pose] }	A character takes a pose until told otherwise.
anim	{ anim: [who, pose], ms?: number, at?: … }	A character plays a pose once, with commands at chosen frames.
place	{ place: [who, at], face?: 'left' | 'right' }	A character appears at a point, without walking.
wait	{ wait: number }	Waits that many milliseconds.
parallel	{ parallel: [[cmd, …], …] }	Runs several lists at the same time, until all end.
camera	{ camera: … }	Moves the camera of a wide room: follow, pan, or centre on a thing.
play	{ play: [prop, animation] }	Plays a prop's animation.
stopAnim	{ stopAnim: prop }	Stops a prop's looping animation.
launch	{ launch: { target: who, to: target | [x, y], from?: target | [x, y], height?: number, ms?: number, rotate?: number } }	Throws a thing along a ballistic arc (presentation only).
spring	{ spring: { target: who, axis?: 'x' | 'y' | 'rot', amplitude?: number, frequency?: number, damping?: number, ms?: number } }	Makes a thing swing and settle (presentation only).
path	{ path: { target: who, points: [[x, y], …], ms?: number, orient?: true } }	Moves a thing along a smooth path (presentation only).
follow	{ follow: { target: who, leader: who, offset?: [x, y], ms: number } }	Keeps a thing next to another for a while (presentation only).
prop	{ prop: [prop, state] }	Puts a prop in a state.
show	{ show: target, fade?: number }	Shows a hidden thing, with an optional fade.
hide	{ hide: target, fade?: number }	Hides a thing, with an optional fade.
gain	{ gain: item }	The player gains an item.
lose	{ lose: item }	The player loses an item.
used	{ used: item }	Marks items used: kept, greyed, offered only to a rule that names them.
set	{ set: flag }	Sets a flag (true, or the value given).
unset	{ unset: flag }	Removes a flag.
inc	{ inc: flag, by?: number }	Adds to a flag counted as a number.
unlock	{ unlock: place }	Unlocks a place on the map.
goto	{ goto: room, at?: id | [x, y] }	Takes the player to a room, at an entry or a point.
map	{ map: true }	Opens the travel map.
moveActor	{ moveActor: [who, room], at?: id | [x, y] }	Moves a character to another room.
emit	{ emit: event }	Fires an event: the room's listeners, then the game's.
waitUntil	{ waitUntil: cond }	In a script: pauses until the condition holds.
waitEvent	{ waitEvent: event }	In a script: pauses until the event is fired.
switchPlayer	{ switchPlayer: char }	The player takes another playable character.
transfer	{ transfer: [item, to] }	Hands an item to another playable character.
custom	{ custom: command, args?: … }	Runs a custom command: its declared effects, then its browser code.
startScript	{ startScript: script }	Starts a script from its first command.
stopScript	{ stopScript: script }	Stops a script until it is started again.
sfx	{ sfx: sfx, caption?: text }	Plays a sound effect, with an optional caption.
music	{ music: … }	Changes the music: a track, push, pop, stop, once or a stinger.
toast	{ toast: text, id?: id }	Shows a short message at the top of the screen.
shake	{ shake: number }	Shakes the screen that many milliseconds.
if	{ if: cond, then: [cmd, …], else?: [cmd, …] }	Runs then when the condition holds, else else.
once	{ once: [cmd, …], id?: id }	Runs its list the first time only.
nth	{ nth: [[cmd, …], …], id?: id }	Runs the next list each time, the last one again after.
cycle	{ cycle: [[cmd, …], …], id?: id }	Runs its lists in turn, looping.
random	{ random: [[cmd, …], …], id?: id }	Runs one of its lists at random (recorded for replays).
cutscene	{ cutscene: [cmd, …] }	Runs a list the player can skip.
choice	{ choice: [{ id?: id, text: text, img?: image, if?: cond, once?: true, do: [cmd, …] }, …] }	Offers the player options, each with its commands; an option with an img shows as a card (the image, its text under it), the cards first.
minigame	{ minigame: minigame, params?: …, then?: [cmd, …] }	Starts a minigame, then runs then.
phone	{ phone: char, do: [cmd, …] }	An incoming call from one or several characters.
guide	{ guide: { verb: verb, target: target, say: text }, id?: id }	A tutorial step: waits for that verb on that target.
talk	{ talk: char }	Opens a conversation with a character.
hint	{ hint: true }	Gives the next hint of the room.
ending	{ ending: true, after?: [cmd, …] }	The sealed ending: decrypted, scratched, celebrated, then its card.
reveal	{ reveal: true, after?: [cmd, …] }	The old name of ending (removed in 5.0).
end	{ end: true }	Ends the game.

Objectives (GameDef.objectives[id])

Field	Type	Means
title	string	What the quest journal shows (translated under objectives/<id>.title).
done	cond	Done the first time this condition holds after an action; best a condition that stays true.
optional	boolean (optional)	A side objective: not part of 100% (npm run solve -- --goal=100%).
parent	string (optional)	The objective this one is a step of: shown under it.

Placeholders in texts

Written inside any text; anything else between braces stays as written. A switch compares String(value) of the flag exactly; no value matching (or the flag unset) takes *=, else the first text. No nesting, no escaping: an alternative holds no {, } or |. The validator reports a malformed switch, a flag no command sets, a value listed that no set writes, and a value written that the switch neither lists nor covers with *=.

Placeholder	Filled
{hero}	when shown: the active hero’s name (its variant’s); lines, choices, looks, hints, toasts, captions, item and object names, objective titles
{<flag>?<value>=<text>|…|*=<text>}	when shown, after the translation: the text listed for the flag’s current value ({form?m=him|f=her}, content{form?f=e|*=})
{item} {target} {name}	in a fallback, kind or give line: the thing acted on, what it is used on, the target
{code:<id>} {hint:<id>}	at boot, by Remix: a coupled dimension’s code and its clue

How each field counts (IR and fingerprint)

From core/ir-fields.ts: logic is in the IR and the fingerprint’s logic; presentation in its presentation; both splits; meta is for the tools only.

The game (GameDef):

• logic: schemaVersion, id, saveVersion, hero, players, hintItem, hintVoice, rules, scripts, events, globalTalk, start, reality, checkpoints, invariants, migrations, objectives, remix, variant
• both: verbs, characters, items, rooms, map
• presentation: title, renderer, audio, skin, ending, saves, settings, input, actorGap, ui, titleScreen, creditsScreen, credits
• meta: lang, offline, lint, i18n, assetBudgets, speedrun

A room (RoomDef):

• logic: id, name, hotspots, look, on, talk, hints, onEnter, scripts, events, hero, anchors
• both: props, actors, exits, stage
• presentation: decor, music, renderer
• meta: description, furniture

---

Edit the source of this page · Report an error