Core mechanics
The engine has four key building blocks, and they make up most of what a Stage game does. Learn just these and you'll already be most of the way there.
Triggers
Triggers are things that happen, such as rendering a response to the player, adjusting a measure, adding an object to the inventory and more. See below for a full list of the types and their parameters:
| Type | Data | Effect |
|---|---|---|
| change-scene | { scene } | moves the player |
| add-to-inventory | { object, announce? } | gives the player an object |
| remove-from-inventory | { object } | takes it from their hands, leaving it in the room |
| move-object | { object, to, announce? } | puts an object in a scene, `inventory`, `offstage`, `bin`, `held:` somebody, or `here` |
| remove-object | { object } | throws an object away, into the `bin` |
| move-tagged | { tag, from, to, announce? } | moves everything carrying a tag from one place to another in one firing |
| set-flag | { flag, value? } | sets a flag, defaulting to `true` |
| response | { text } | says something to the player |
| end-game | { journal? } | ends the game, and says what it's remembered as |
| save-game | { name? } | keeps the playthrough, once the turn is over |
| adjust-measure | { subject, measure, by? | to? } | moves a measure, or sets it outright |
| achievement | { id } | unlocks a credit that outlives the playthrough |
| journal | (none) | writes down that the player tried, even where whatever gated it turned them back |
Conditions
A condition is a way to gate against a trigger happening, either game state or chance. The `requires` field is a list of them, and every one must match before the subsequent Triggers will fire. The first to fail is the one whose `failure` path is activated. Below is a list of all condition types available:
| Type | Data | Matches when |
|---|---|---|
| has-item | { object } | the object is in the inventory |
| object-here | { object } | the object is carried or in the current scene |
| character-here | { character } | the character is in the current scene and can be seen there |
| object-in | { object, location } | the object is in `location`: a scene id, `inventory`, `offstage`, `bin`, `held:` somebody, or `in:` something |
| handled | { object } | the player has had the object in their hands at some point, carried now or not |
| flag | { flag, value? } | the flag equals `value`, or is truthy when `value` is omitted |
| visited | { scene?, times? } | the scene has been entered at least `times` (default 1) |
| scene | { id? } or { tag? } | the player is standing in that room, or in any room declaring that word |
| performed | { object?, action?, preposition?, indirect?, scene?, times? } | a matching action has fired at least `times` (default 1) |
| measure | { subject, measure, min?, max? } | the measure stands within the bounds given, each inclusive |
| carrying | { of?, min?, max? } | what the player is holding stands within the bounds given |
| tagged | { tag, location } | something carrying the tag is at `location` - the same places `object-in` reads |
| chance | { name, of, index, no-repeat? } | is luck with you? each pass uses `name`, `of` and `index`, which can be either a number, an array of numbers or a spread ([1..5], one through five). If you want the condition to only fire once if there's a match, use `no-repeat: true`. |
| any-of | { conditions } | at least one of the conditions matches |
| all-of | { conditions } | every one of the conditions matches |
Measures
A measure is a number that belongs to the player or to a thing and can move during play - health, how full a lamp's oil is, whatever your game needs to keep count of. It's bounded rather than open-ended: give it a `min` and a `max`, and a `start` to begin a playthrough at, and Stage keeps it inside those bounds for you.
| Field | Type | Does |
|---|---|---|
| id | string, required | what the measure is called |
| min | number | the lowest it can fall to |
| max | number | the highest it can rise to |
| start | number | what it begins a playthrough at |
| thresholds | Threshold[ ] | triggers that fire the moment it crosses into a new range |
Actions
An action is a thing the player can do to an object, a character, a room, or the game itself - gates and then a list. `requires` and `once` are the gates, each saying why it refused; `triggers` is what happens when every gate has let the player through, prose included.
| Field | Type | Does |
|---|---|---|
| id | string, required | the id of the verb this answers to |
| preposition | string | the significant preposition this answers to, such as the `under` in "look under"; omit for the plain form |
| indirect | string | the id of the second object or topic required; omit to accept any |
| requires | Condition[ ] | what must be true first - see Conditions |
| once | block | present to fire only the first time; its `failure` is what later attempts get |
| triggers | Trigger[ ] | everything that happens when it works - see Triggers |