API

Games are written in YAML, and this is the shape of every file. The details about triggers, conditions, chance and actions are covered once, in Core mechanics.

Vocabulary - vocabulary.yml

The most important file in your source, what your game understands - Verbs, Articles, Prepositions, Conjunctions, Topics and Directions. This file sits in the root of your game source files.

Key	Type	Description
verbs	`- id: string synonyms: - string affordances: boolean navigational: boolean conversational: boolean recipient-first: boolean`	The verbs a player can type which are recognised by the engine for your game. A verb whose target is a direction rather than an object, such as `walk`, sets `navigational: true`. A verb that asks a character something, such as `ask`, sets `conversational: true`. A verb that may name who something is for before naming the thing, such as `give`, sets `recipient-first: true`.
directions	`- id: string synonyms: - string`	The ways the engine understands the player wants to move somewhere, corresponds directly to a definition inside a scene file.
articles	`- id: string synonyms: - string`	Articles are what stands before an object or character, such as `the`, `an` and `a`.
prepositions	object	There are two kinds of prepositions, `filler` and `significant` - the first is simply meaningless filler, the latter changes the meaning of a verb. For example, `walk to the fire` and `walk the fire` compile to the same command whereas significant prepositions help the engine understand the difference between `look under the bed` and `look at the bed`.
prepositions.filler	`- id: string synonyms: - string`	The prepositions considered to be filler, see above.
prepositions.significant	`- id: string synonyms: - string`	The prepositions considered to be significant, see above.
conjunctions	object	Conjunctions allow commands to be chained by the player.
conjunctions.coordinating	string[ ]	Coordinating conjunctions can be declared such as `and`, `but`, `then` etc.
conjunctions.subordinating	string[ ]	There is no requirement for subordinating conjunctions, yet.

Game - config.yml

The following file sits next to your vocabulary file and provides the engine with basic information about your game.

Key	Type	Description
id	string	The unique identifier of your game.
start	string	The first scene which loads in your game.
metadata	object	Additional configuration for your game.
metadata.title	string	The title of your game, a human readable name.
metadata.version	string	The current version of your game, semantic is recommended though other formats are fine.
metadata.description	string	What your game is about, in your own words. Shown on the page that shows your game before it's opened.
metadata.rating	string	What you were told to say about who your game is for, word for word - `PEGI 16`, `ESRB Teen`, `USK 12`.
metadata.genres	string[ ]	What kind of game it is, in your own words and your own order - shown, and searched by whatever holds a shelf of games.
metadata.release	object	When the game came out.
metadata.release.date	string	The day, as `YYYY-MM-DD`.
metadata.developer	`name: string website: string`	Whoever made the game.
metadata.publisher	`name: string website: string`	Whoever put the game out.
metadata.website	string	The game's own place on the web, as against the people behind it.
metadata.assets	object	The pictures your game shows for itself.
metadata.assets.icon	string	Path to the mark shown where your game sits beside others, such as a shelf.
metadata.assets.cover	string	Path to the banner shown where your game sits on its own.
gui	string	Path to a folder holding your game's own screen, if it has one - see Your own screen.
player	object	What the game says about the player, who is otherwise only a position and a pair of hands.
player.measures	`- id: string min: number max: number start: number thresholds: - from: number triggers: - type: response data: text: string`	The player's own measures, such as health or how much they're carrying - see Measures.
player.carries	string	Which of the player's measures says how much they may hold at once. Left out, nothing is ever refused for weight.

Scene - scenes/[name].scene.yml

Scene files are the building blocks of your game, they allow the player to move between your world. They sit inside a `scenes` directory, and can be nested in scene-specific directories - see the Ferryman demo game as an example.

Key	Type	Description
id	string	The unique identifier of the scene.
name	string	What the scene is called - shown to the player and used to name it in the journal. Falls back to the scene's id when left out.
presence	`- requires: - type: has-item data: object: string also: true triggers: - type: response data: text: string`	How the scene describes itself to the user upon entry.
actions	`- id: string requires: - type: string triggers: - type: string`	The verbs a player may type within the scene, and what happens when they do - see Actions.
objects	`- string - id: string name: string`	The objects that exist in the scene.
characters	`- string - id: string name: string`	The characters that exist in the scene.
navigation	`- id: string synonyms: - string affordances: boolean requires: - type: string once: failure: triggers: - type: string triggers: - type: change-scene data: scene: string`	The ways out of a scene and into another scene - the same gates and triggers as an action.
tags	string[ ]	A list of tags used to categorise the scene, which can be used in triggers later.
metadata	`# any properties - never read by Stage description: string`	Your own bookkeeping. Never read by Stage - any properties are accepted.

Objects - [name].object.yml

Objects can sit inline or within a file of their own and references by ID in the scene files.

Key	Type	Description
id	string	The unique identifier of the object.
synonyms	string[ ]	Alternative words that the player may type to reference the same object.
name	string	The text a player is shown about an object.
metadata	`# any properties - never read by Stage description: string`	Your own bookkeeping. Never read by Stage - any properties are accepted.
noun	"common" \| "proper" \| "plural" \| "as-written"	Can be one of `common` (the default), `proper` (for a name), `plural` or `as-written`.
portable	boolean	Whether the object can be held or added to an inventory.
contains	boolean	Whether other objects can exist within this object, such as a sack or backpack.
presence	`- requires: - type: has-item data: object: string also: true triggers: - type: response data: text: string`	What the scene says about an object that exists within it.
size	string	Which of this object's own measures says how heavy it is. Left out, it weighs one; only read where the game names a carrying limit at all - see Measures.
start	string	Objects can move between scenes and/or be carried by characters or the player - this decides where it starts. Can be either a scene ID, `offstage` or `in:` (another object).
requires	`- type: string data: object negate: boolean`	The conditions that must match for it to be present where it is defined - see Conditions.
actions	`- id: string requires: - type: string triggers: - type: string`	The verbs that the object will answer to - see Actions.
measures	`- id: string min: number max: number start: number thresholds: - from: number triggers: - type: response data: text: string`	The numbers that are attributed to an object, such as quantity, fragility, power, whatever your game needs to keep track of.
affordances	boolean	Provides a way to exclude the object from appearing in the affordances list.

Characters - [name].character.yml

Characters can sit inline or within a file of their own and references by ID in the scene files.

Key	Type	Description
id	string	The unique identifier of the character.
synonyms	string[ ]	Alternative names that the player may type to reference the same character.
name	string	The text a player is shown about an character.
metadata	`# any properties - never read by Stage description: string`	Your own bookkeeping. Never read by Stage - any properties are accepted.
noun	"common" \| "proper" \| "plural" \| "as-written"	Can be one of `common` (the default), `proper` (for a name), `plural` or `as-written`.
requires	`- type: string data: object negate: boolean`	The conditions that must match for the character to be present where it is defined - see Conditions.
actions	`- id: string requires: - type: string triggers: - type: string`	The verbs that the character will answer to - see Actions.
measures	`- id: string min: number max: number start: number thresholds: - from: number triggers: - type: response data: text: string`	The numbers that are attributed to a character, such as fragility, power, whatever your game needs to keep track of.
start	string	Characters can move between scenes and/or be carried by characters or the player - this decides where it starts. Can be either a scene ID or `offstage`.
holds	string[ ]	Characters can hold objects, this list defines what they are.
knows	`- topic: string verb: string requires: - type: has-item data: object: string triggers: - type: response data: text: string knows: - topic: string verb: string open: true triggers: - type: response data: text: string id: string`	What the character knows or understands - their knowledge of the world.
presence	`- requires: - type: has-item data: object: string also: true triggers: - type: response data: text: string`	What the scene says about a character that exists within it.
affordances	boolean	Provides a way to exclude the character from appearing in the affordances list.

Actions - actions.yml

An actions file provides a way for the engine to react to a verb defined nowhere else, such as `wait` or `pray`. If the same verb is defined in the current scene, that will be used first, else it will fallback to this. Individual scenes can also define their own `actions.yml` file to better organise their actions.

Key	Type	Description
actions	`- id: string requires: - type: string triggers: - type: string`	The verbs answered from anywhere - see Actions.

Every turn - every-turn.yml

The every turn file gives you the ability to write rules that happen on each turn with optional conditions - luck among them - and finally triggers. In the root of the source it runs on every scene's turns, added inside a scene's directory will influence only that scene.

Key	Type	Description
every-turn	`- requires: - type: has-item data: object: string - type: chance data: name: string of: number index: number \| number[ ] triggers: - type: response data: text: string`	The rules checked at the end of every turn.

Topics - topics.yml

What a character can be asked or told about, deliberately kept separate from the character itself so more than one of them can share the same knowledge. A copy at the root of your game applies everywhere; one inside a scene's own directory only applies there, and its topic IDs are qualified with the scene's own.

Key Type Description

topics

- id: string
  synonyms:
    - string
  affordances: boolean
  knows:
    - verb: string
      requires:
        - type: has-item
          data:
            object: string
      triggers:
        - type: response
          data:
            text: string

The topics a player can ask or tell characters about.

knows

- verb: string
  requires:
    - type: has-item
      data:
        object: string
  triggers:
    - type: response
      data:
        text: string

Answers not filed under any particular topic.

Messages - messages.yml

The messages file allows you to override the engine's own built-in strings - the things the engine itself renders, like a refused action or a blocked exit. A built `.stg` file never bundles Stage's defaults, only what's written here, so leaving this file out means the engine speaks in it's own words unchanged.

Key	Type	Description
messages	object	A fixed set of named strings (`action.blocked`, `get.done`, `journal.achievement` and many more) - write only the ones you want to change. Each key accepts only its own placeholders, and an empty string silences that message entirely.