Heathen Engineering

Ogham Storyteller Toolkit — Agent Reference (Unity)

Plain-text agent reference for the Ogham Storyteller Toolkit package (com.heathen.oghamtoolkit), covering Unity (source-verified). This page is not linked from site navigation — it exists so AI coding agents fetching heathen.group/kb/ogham-welcome have a condensed, source-verified reference to read.

Full Ogham Storyteller agent index: agent-ref-ogham-storyteller-index

---
name: heathen-ogham-storyteller-toolkit
description: Ogham Storyteller Toolkit reference for Heathen's Unity narrative graph system (com.heathen.oghamtoolkit). Use when a developer wants ready-made scene wiring for a story — text/audio/sprite/prefab display components, option buttons, inline-link handling, or Twee import.
source: https://heathen.group/kb/ogham-welcome/
generated: 2026-08-24
---

# Ogham Storyteller Toolkit — agent reference (Unity)

**Tier: [Toolkit] (Pro, paid).** Foundation alone is enough to ship a story with a bespoke reader
script (see Foundation's `Storyteller` facade); Toolkit is a pure presentation/import convenience
layer — **no story data model and no runtime session logic of its own**, every type here reads
Foundation's public API. Package id `com.heathen.oghamtoolkit`, namespace `Heathen.OghamToolkit`.
Depends on `com.heathen.oghamfoundation` (sibling repo, not UPM-resolved — install both).

## `OghamStoryReader` — the scene coordinator

The one required component for using Toolkit's display pieces. On `Start`: builds the baked story
catalog, calls `Storyteller.AcquireStory(this)` to become the active presenter, creates an asset
streamer sized by the Inspector's look-ahead depth, and auto-discovers every
`IOghamNodeListener`/`IOghamOptionsListener` in its children. On each node entry, dispatch is three
phases: node listeners render first (text displays register which options they covered as inline
links) → options listeners receive only the *uncovered* options (so a button list and inline links
never duplicate the same choice) → an `OnNodeEntered` UnityEvent fires for no-code hookups.

## Display components (`IOghamNodeListener`)

All require `OghamStoryReader` on the same GameObject, read content by index from `StoryNode`:

| Component | Reads |
|---|---|
| `OghamTextDisplay` | Text content keys → `TMP_Text`; formats inline option links as clickable rich text, optional typewriter reveal. |
| `OghamAudioDisplay` | Audio content key → `AudioSource`; OneShot or Loop, managed mode avoids restarting an identical clip across a node change. |
| `OghamSpriteDisplay` / `OghamRawImageDisplay` | Image/Sprite content keys → `UI.Image` / `UI.RawImage`; optional fade, managed mode. |
| `OghamPrefabDisplay` | Prefab content keys → spawned instances; `OghamLifecycle` controls handling of previous instances across a node change. |

## Options UI

- `OghamOptionButtonDisplay` — the common case: instantiates one button per **uncovered** option
  automatically, rebuilding as nodes change.
- `OghamOptionButton` — a single hand-placed button bound to one specific option on one specific
  node, for menu-style screens where every button is authored, not generated.
- `OghamEnterNodeButton` — a persistent nav button (Settings/Back/Quit) that calls
  `Storyteller.Enter(tag)` directly with **no** condition/active semantics, for navigation outside
  the current node's own options. Use `OghamOptionButton` instead when the button really is one of
  the current screen's choices.

## Inline link handling

`OghamLinkClickRelay` (low-level, used internally by `OghamTextDisplay`) and `OghamLinkCatcher`
(higher-level, for a label not driven by `OghamTextDisplay` — detects an `Ogham://` link click and
raises the clicked option's `GameplayTag` directly, wire straight to `Storyteller.Choose`).

## Miscellaneous bindings

`OghamTagBindings` (reads a narrative-state tag's raw value, typed, to a bound component member) and
`OghamEventTriggers` (bridges global `Storyteller` events to Inspector-wired `UnityEvent`s).

## Twee / SugarCube importer

`OghamTweeImportWindow`, reached from Foundation's Settings ▸ **Data Import** tab — a three-panel
staged editor (map `$Variables` to tag paths → toggle passages in/out → review before commit).
Commit creates one Content node per included passage directly in the project's single Ogham tree —
it does **not** create a separate `.ogham` file. SugarCube is the one built-in dialect
(`<<if>>`/`<<set>>`/all three link notations); implement `ITweeFormatParser` for another dialect
(Harlowe, Chapbook).

---
Foundation reference: https://heathen.group/agent-ref-ogham-storyteller-foundation/
Full agent index: https://heathen.group/agent-ref-ogham-storyteller-index/