Organizing your story

Start small. You can keep all your story settings and characters in one file, then split them up when scrolling starts to get in the way. Neither layout gives your story extra features: choose whichever is easier to write. To keep a name or short recurring text consistent across branches, use a character substitution or text variable rather than copying the value into every passage. See names and recurring text.

A small story: two files

Make a folder called night-ferry with these two files:

night-ferry/
  story.talewright.yaml
  story.tale

story.talewright.yaml

game:
  id: night-ferry
  title: The Night Ferry
  start: dock

characters:
  player: { first-name: Ada, inventory: [coin] }
  ferryman: { first-name: Wick }

items:
  coin: { name: silver coin }

story.tale

=== dock
@title The Dock

> ferryman: Crossing tonight, {player:first-name}?

* [Pay with your silver coin] (requires: player has coin) { take player coin } -> crossing
* [Walk away] -> END

=== crossing
@title The Crossing

The boat slides into the dark.
-> END

That’s enough to play. Follow Your first story for checking, playing, and adding more choices.

Keep story.talewright.yaml at the top of your story folder. Put extra settings files in subfolders, and give them names ending in .talewright.yaml.

Here’s the same story split into smaller files:

night-ferry/
  story.talewright.yaml
  characters/
    player.talewright.yaml
  harbour/
    ferry.talewright.yaml
  chapters/
    story.tale

story.talewright.yaml

game:
  id: night-ferry
  title: The Night Ferry
  start: dock

characters/player.talewright.yaml

characters:
  player: { first-name: Ada, inventory: [coin] }

harbour/ferry.talewright.yaml

characters:
  ferryman: { first-name: Wick }

items:
  coin: { name: silver coin }

Move the earlier story.tale into chapters/ without changing its text. Ada still carries the coin, Wick still speaks, and the choices still lead to the same scenes.

When you separate the playable character, characters/player.talewright.yaml is a useful name. It isn’t compulsory. A file can contain several characters, or mix characters, items, factions, flags, and variables, as the ferry file does. You don’t need a folder for every kind of thing.

Names don’t change how the story works

  • Move, don’t copy. After moving a character or item into another file, remove its old declaration. Giving two characters the same id is an error, not a way to replace one.
  • Keep game: in the top-level file. Title, starting scene, rules, and character-creation settings stay under game: in story.talewright.yaml.
  • Keep one story.talewright.yaml. Don’t put another file with that name in a subfolder; it won’t create a separate story.
  • Keep names unique across the story. A character named ferryman is still ferryman wherever you put its file. A folder doesn’t make characters private, add a prefix to their names, or create a scene you can send a choice to. Write a scene in a .tale file to make a new destination.
  • Use the full ending. ferry.talewright.yaml is read; ferry.yaml and ferry.talewright.yml aren’t. Keep .talewright.yaml lowercase. Reserve that ending for Talewright story settings, not notes or files for other tools.

Talewright reads all the story’s .tale files and supporting settings files. You don’t need to list them or arrange filenames so one loads first. For example, the player’s inventory can name an item in a different file.

Keep triggers together: order matters

Put your triggers: list in story.talewright.yaml, in the order you want Talewright to check it. Triggers can change facts that later triggers check, so changing their order can change what happens.

For example, the first trigger below sets a flag that the second one checks. Add this whole list to either layout’s top-level file:

triggers:
  - id: notice-payment
    when: not player has coin
    do: set flag:paid
    once: true
  - id: count-payment
    when: flag:paid
    do: var:crossings += 1
    once: true

Only one file may contain triggers:. You can move the whole list to a supporting file, but don’t split it across files or use filenames to try to control the order.

After moving files

Check and reopen your story as you normally would. If you’re using the Author Debugger, restart the story after changing settings files. Keep the whole folder together when sharing your story.

For a larger example, browse The Lost Relic. For all available settings, see the syntax reference.

These docs are maintained with the code in squid-farm/talewright. Found a problem? Open an issue.