Documentation menu

Documentation

Open Story Format

An engine independent format for the dialogues of any game. Write stories in the .osf language, compile them to YAML or JSON resources, and read them from any engine or tool.

Plain text you can read

Stories are text files that people write by hand, review in pull requests and diff in Git. Every example in these docs is shown three ways: the .osf source, and the YAML and JSON resources it compiles to.

Engine independent and flexible

The format describes what is said, by whom, and where each choice leads. How it looks and sounds is up to your game, so writing your own player is a short job. The dialogue player tutorial builds one in under 100 lines.

Story as code

Every resource carries an apiVersion, and one Versions block pins the language and plugin versions a project uses, so an upgrade is a one-line change. A JSON Schema describes every resource file.

Self validating

osf validate checks references, ids, variable types, unreachable nodes and missing translations before your game ever loads the story.

OSF.osf source
arc_1_war/01_intro_scene.osf
Dialogue 01_intro_scene {

  Node node_01 {
    next: node_02
    speaker: protagonist
    text: "Where am I?"
  }

  Node node_02 {
    speaker: stranger
    text: "Somewhere you should not be."
  }
}
arc_1_war/01_intro_scene.yaml
apiVersion: dialogue/v1
kind: Dialogue
data:
  id: 01_intro_scene
  startNode: node_01
  nodes:
    node_01:
      next: node_02
      content:
        speaker: Character.protagonist
        text: Where am I?
    node_02:
      content:
        speaker: Character.stranger
        text: Somewhere you should not be.

Where to start