API

Overview

Every file in your game says in its name whose it is and what it holds, so you can tell any file apart at a glance. A name has three parts before .yml (or .yaml): who it belongs to, what kind of thing that is, and what the file holds.

ferryman.game.config.yml        the game's settings
ferryman.game.vocabulary.yml    the game's words
tavern.scene.config.yml         the tavern itself
tavern.scene.topics.yml         what can be asked about in the tavern
lantern.object.config.yml       a lantern
guard.character.config.yml      the guard

Vocabulary

The most important file in your source, what your game understands - Verbs, Articles, Prepositions, Conjunctions, Topics and Directions. It is named for your game, as all of the game's own files are.

verbs:
  - id: walk
    synonyms: [go, head, enter]
    navigational: true

  - id: look
    synonyms: [examine, read]

  - id: ask
    synonyms: [question]
    conversational: true

  - id: wait
    synonyms: [z]

directions:
  - id: north
    synonyms: [n]

  - id: south
    synonyms: [s]

articles:
  - id: the
    synonyms: []

prepositions:
  filler:
    - id: to
      synonyms: [towards, at]

  significant:
    - id: with
      synonyms: [using]

conjunctions:
  coordinating: [and, then]
  subordinating: []

Game

The game's config gives the engine its basic information. Its name gives your game its id.

id: reading-room
start: reading-room

metadata:
  title: The Reading Room
  version: 1.0.0

store:
  description: A quiet room, a fast clock and a drawer that won't open.
  assets:
    tile: tile.png
  genres: [Mystery]

export:
  bundle-id: com.example.reading-room
  platforms:
    macos: [arm64, x86_64]
    windows: [x86_64]
  icon: icon.png

gui: gui/

Player

Who the player is, and what they carry, in a file of its own. Leave the file out and the player is just "you", with nothing to carry a limit on and no words of their own. Leave out the name and the words, and nothing in your game can name the player at all, which suits a game that never needs to.

name: Wren
noun: proper
synonyms: [wren, me, myself]

actions:
  - id: look
    triggers:
      - type: response
        data:
          text: Mud to the knees, and the coin still in your fist.

carries: load

measures:
  - id: load
    min: 0
    max: 3
    start: 0

The file holds the player's fields directly, with no player: line above them. If you are moving a game written before this file existed, cut the player: block out of your config, paste it here and unindent it.

Achievements

The things a player can earn in your game, listed in a file of their own. Each one is unlocked by an achievement:unlock trigger wherever you decide it's been earned - see Triggers.

- id: lit-the-lantern
  title: First Light
  description: Light the lantern.
  icon: assets/lantern.png

- id: nine-rings
  title: Nine Rings
  description: Count the stump's rings all the way round.
  secret: true

The file holds the list directly, with no achievements: line above it.

Sounds

The sounds your game carries, listed once and played by id. The file holds the list directly; every field each sound takes is in Sound.

- id: drawer-lock
  file: sounds/drawer-lock.mp3

- id: clock-ticking
  file: sounds/clock-ticking.wav
  loop: true

Images

The images your game carries, listed once and shown by id. The file holds the list directly; every field each image takes is in Images.

- id: reading-room
  file: images/reading-room.jpg
  alt: A long room of mismatched chairs, with a writing desk against the wall and a clock above it.

Scene

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.

id: garden

name: The Walled Garden

presence:
  - triggers:
      - type: response
        data:
          text: A walled garden, four beds and a wet path, with the rain just off.

objects:
  - id: path
    synonyms: [gravel]
    actions:
      - id: look
        triggers:
          - type: response
            data:
              text: Wet gravel, and one set of footprints going up it ahead of yours.

navigation:
  - id: south
    synonyms: [door, inside]
    triggers:
      - type: scene:change
        data: { scene: reading-room }

Objects

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

id: key

name: brass key
synonyms: [little key]
portable: true
start: reading-room

actions:
  - id: look
    triggers:
      - type: response
        data:
          text: Small and brass, and warm from wherever it has been.

Characters

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

id: librarian

synonyms: [them, they]
start: reading-room

actions:
  - id: look
    triggers:
      - type: response
        data:
          text: Halfway through a tray of cards, and glad of the interruption.

knowledge:
  - topic: lock
    triggers:
      - type: response
        data:
          text: '"The key lives behind the clock," they say, without looking up.'

Giving orders

Sooner or later a player will try bossing your characters about, with librarian, open the door or tell the librarian to open the door. An order is just another of the character's actions, marked ordered: true: something the player does to them, by telling them to do something. A character only answers the orders you've written. Everything else gets turned down, and the player never ends up doing the job themselves. Either way it costs them a turn, so anything you've set to happen every turn carries on happening.

id: genie
synonyms: [genie, demon]
actions:
  - ordered: true
    conditions:
      - type: flag:is
        negate: true
        data: { flag: genie-paid }
    triggers:
      - type: response
        data:
          text: '"My fee is not paid!"'
  - id: give
    ordered: true
    object: wand
    indirect: player
    triggers:
      - type: object:move
        data: { object: wand, to: held:player }
      - type: response
        data:
          text: '"I hear and obey!"'
  - ordered: true
    triggers:
      - type: response
        data:
          text: The genie folds its arms.

Ordered actions are tried from the top. The first one that fits the order and whose conditions hold is the answer. Leave out id, object, preposition or indirect and that order fits anything there, so the last one above catches whatever's left. A condition with its own failure answers with that when it fails; one without moves on to the next. indirect: player is how genie, give the wand to me names the player, as long as you've given the player words like me to answer to. The player can have ordered actions of their own too, in the player block.

To have the character actually do what they were told, the way the player would, put a character:obey in the triggers. At that point they walk through the room's real exits, take and drop things with their own hands, or set off the actions on whatever they were told to touch. Anything before it is said first, anything after it afterwards. Leave it out and the order is only answered, which is how the genie above refuses and how a companion says "Lead on" below.

id: robot
actions:
  - id: walk
    ordered: true
    triggers:
      - type: response
        data:
          text: '"Whirr, buzz, click!"'
      - type: character:obey
  - id: push
    ordered: true
    triggers:
      - type: character:obey
  - ordered: true
    triggers:
      - type: response
        data:
          text: '"My programming is insufficient."'

While a character is carrying out an order, they're the one doing it. here is where they're standing, inventory is their own hands, and scene:change walks them off rather than the player. So the robot above walks through an exit into a room the player can't fit into, and pushes a button there that only works for it, using character:obeying. When you really do mean the player, say so: held:player is always the player's hands, and character:here with player asks whether the player's in the same room as them. Flags, measures and achievements work exactly as they always do.

When a character does something, the usual messages are used, like get.done for taking a thing. If yours reads oddly for anyone but the player, write a second one with -by-character on the end, and <Character> to name them: get.done-by-character: <Character> picks up <thing>. The player keeps using the first.

Normally you can only boss about someone who's in the room with you. Give a character hears: adjacent and they'll hear you from next door too, through any exit between the rooms, even a locked one. Give them hears: anywhere and they'll take orders wherever they are, as long as they're somewhere in the game. That's how you shout instructions to the robot you've squeezed through a gap you can't fit through yourself. When they're in another room, character:here with player doesn't hold, so their ordered actions can tell you're not with them.

A companion who walks with you

There's no special setting for a companion. They're a character with an ordered action that sets a flag, and an every-turn rule that brings them along while the flag's set. The rule's own conditions say where they won't go.

# in the character's actions
- id: follow
  ordered: true
  triggers:
    - type: flag:set
      data: { flag: following }
    - type: response
      data:
        text: '"Lead on."'

# in your game's turns file
every:
  - conditions:
      - type: flag:is
        data: { flag: following }
      - type: character:here
        negate: true
        data: { character: companion }
      - type: scene:is
        negate: true
        data: { tag: haunted }
    triggers:
      - type: object:move
        data: { object: companion, to: here }
      - type: response
        data:
          text: Your companion catches up with you.

There are four ways an order gets turned down: it was given to something that isn't a character, to somebody who isn't in the room, about more than one thing at once, or the character simply won't. Each one is a message, so you can put it in your game's own words. Alongside a message's usual <thing> and <name>, <named> is the word the player used.

# in your game's messages file
order.not-character: You can't give orders to <thing>.
order.absent: There is nobody called <named> here to listen.
order.many: One thing at a time, please.
order.refused: <Thing> pretends not to hear you.
order.crowd: Nobody is listening to "<named>" all at once.
order.self: Talking to yourself again?

order.crowd is for an order given to more than one character at a time, like tell the troll and the thief to go north. Nothing in the player's line happens, and it doesn't cost them a turn. order.self is for the player bossing themselves about, if you've given them words like me to answer to.

A comma only counts as giving an order when what comes before it is one of your characters. Anything else keeps its usual meaning, so take the lamp, the key is still a list, and the fire, touch it is still about the fire. Talking isn't an order either: librarian, hello is just the player saying hello, as long as your greeting verb is marked conversational.

Actions

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 [id].scene.actions.yml file to better organise their actions.

The file is the list of actions itself, so there's no actions: line at the top: the name of the file already says what's in it.

- id: wait
  triggers:
    - type: response
      data:
        text: Time passes, and nothing comes of it.

Every turn

The turns file gives you the ability to write rules that happen on each turn with optional conditions - luck among them - and finally triggers. The game's own runs on every scene's turns; a scene's own, [id].scene.turns.yml, runs only while the player is in that scene.

The rules go under every:, since they are checked every turn. That leaves room for more ways of time passing beside it later.

every:
  - conditions:
      - type: scene:is
        data: { tag: outdoors }
      - type: chance
        data: { name: thunder, of: 6, index: 1 }
    triggers:
      - type: response
        data:
          text: Somewhere over the hills, thunder.

Topics

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. Your game's own, [id].game.topics.yml, applies everywhere; a scene's own, [id].scene.topics.yml, only applies there, and its topic IDs are qualified with the scene's own.

The file is the list of topics itself. Answers that aren't about any one topic live in a knowledge file of their own, so a topic and an answer never get mixed up.

- id: lock

- id: garden
  synonyms: [flowers]

Answers anybody gives

Sometimes a reply isn't about any topic at all: what anybody says when they're asked something they know nothing about, or when the player just says hello. Those answers live in a knowledge file, holding the list directly. Your game's own is heard everywhere, and a scene's own, [id].scene.knowledge.yml, only there.

- verb: ask
  triggers:
    - type: response
      data:
        text: '"No idea," comes the answer.'

An answer here can't name a topic. If it's about one, write it under that topic in topics file instead.

Messages

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.

Each message sits at the top of the file under its own key, with no messages: line above them.

get.done: "Taken: <name>."
action.blocked: Not just yet.