🤖 Agent Prompt
The Ogham Graph Editor is the primary authoring environment for Ogham Storyteller. It is a visual node graph tool that lives directly inside the engine editor, so writers and developers work in the same environment as the rest of the project with no round-trip to an external tool. Every story is represented as a directed graph of nodes connected by options; the graph is saved to a human-readable .ogham JSON file that is easy to version-control and review in a pull request diff.
The canvas shows your whole project as one unified story tree — nodes organised into Collections (folders), not separate story files. A large project can still be split across multiple physical files for team/version-control reasons (see Best Practice, below), but the editor always shows one tree regardless of how many files it’s stored across. Nodes can be annotated with highlight colours and labels, grouped with Trello-style label pills, connected with bezier wires or compact tab-flag jumps, and rearranged with a one-click auto-layout. An in-editor play window lets writers simulate the full story, including state variable interpolation and option conditions, without entering Play mode.
Getting Started #
Open Window > Heathen > Storyteller to start. There’s no separate “create a story” step — the project’s story tree is created automatically the first time you save or build. By default everything lives in one file (Assets/Story.ogham); see the Best Practice section below if you want to split a large project across multiple files for team version control.
Open the Editor #
You can now open the Ogham Storyteller.
The Ogham Storyteller is a Node Graph based editor similar to Twine, ArticyDraft and other interactive narrative tools.
Best Practice #
Your project’s story tree can still be split across multiple physical files for organisation and version control — by region, character, topic, or however suits your project. Enable a split from the Files tab under Project Settings › Subsystems › Ogham Storyteller (see the Configuration article). The files themselves are simple JSON and work well with any source control or change management tool.
The graph editor always shows one unified tree regardless of how many files your project is split across — splitting only changes what’s on disk, not what you see. Nodes are colour-coded per Collection (not per file) to help you visually organise a large tree, and the Files tab lets you disable a file entirely if you want to hide that part of the tree temporarily — its content stays untouched on disk and simply doesn’t load until re-enabled.
Add New Entry Node #
When you create a node you need to give it a name, this name is a Gameplay Tag. If the tag is new it will automatically be added to your gameplay tags settings.
This is also true for options, they are identified via a Gameplay Tag and if you type a new tag it will automatically be added to your gameplay tags settings.
Right click in the graph and create your first node.
Once you have nodes and options you can create a new node by simply pulling off an option and drooping in the a clear space on the graph.
We have an article dedicated to Nodes and the key components features of the Node system.
Snap & Layout #
You can toggle snap mode, in this mode when moving nodes they will follow a strict grid pattern.
Layout can be pressed to automatically layout all of the nodes in the graph, this can be useful after import to de-tangle a large imported story.
Import #
You can import a story from an existing Twine file aka a “Twee” file. This feature is in preview and only supports “SugarCube” additional import formats will be added as requested by the community. It is also possible to create your own Twee importer using the ITweeFormatParser interface, or create a non-Twee based importer using the IOghamImporter interface.
Play Testing #
So you have your story written but you haven’t tested it yet. We have you covered. In the upper right corner of the editor you will find a Play button. Click it and select the node you want to start from and it will simulate your story with full state.
The Ogham Play window display’s your formatted text, obeys conditions and executes operations and displays the resulting state and history of your play through.
Export – Voice Over Script #
When its time to voice your story Ogham can help you produce a script suitable for your voice actors. Use the Export button in the upper right of the window and chose the export format.
