Introduction

Open Story Format

This is the documentation for the Open Story Format (OSF), an open format for interactive stories: dialogues, characters, variables and their translations.

OSF has two layers. A tool only has to read or write one of them to work with every other OSF tool.

Layer	Who uses it	What it looks like
`.osf` language	Writers and designers, by hand	Brace-based blocks, like Terraform’s HCL. Whitespace never matters.
OSF resources	Engines, tools and validators	One file per resource with `apiVersion`, `kind` and `data`, like a Kubernetes manifest. Written as YAML or JSON and described by a JSON Schema.

osf build compiles every .osf file in a project folder into OSF resources. Every page in these docs shows the .osf source first, and the YAML and JSON it compiles to next to it.

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."
  }
}

compiled by osf build

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.

Independent of any engine

The format is independent of any game engine, game or genre, so the same story can be loaded into Unity, Unreal, Godot or your own engine. If you are building an RPG with dialogue in it, you can read OSF with a small loader and keep your existing code.

What osf build should emit specifically for game engines is still an open question in draft v1: [engine build output TBD]. Today it writes the OSF YAML resources shown in these docs.

Status

The format is a draft v1. The full specification is docs/spec.md and the language is osf/language.md. The osf CLI used in these docs is in development (v0.1.0).