StoryFlow for Unity

The StoryFlow Unity package lets you import StoryFlow projects directly into Unity and run them as fully interactive dialogue systems. Design your stories visually in the StoryFlow Editor, export as JSON, and bring them to life in Unity with a pure C# API.

What the Package Provides

The package is split into two assemblies:

• StoryFlow.Runtime - The gameplay assembly that ships with your built game. Contains the StoryFlowComponent, the StoryFlowManager, data assets, and the full node execution runtime.
• StoryFlow.Editor - An editor-only assembly for importing projects, resolving media assets (images, audio), and live syncing with the StoryFlow Editor via WebSocket.

Features

• Full node graph execution - All 150+ node types from the StoryFlow Editor are supported, including branching, loops, type conversions, string operations, and array manipulation.
• Event-driven C# API - Clean C# events and callbacks for dialogue state changes. Build your entire dialogue UI in code or with UI Toolkit / uGUI without any special base classes.
• Dialogue display - Rich dialogue state with title, text, character data, images, audio, options, and text blocks. Variable interpolation happens automatically.
• Characters - Full character support with names, portraits, and per-character variables. Character data is resolved and ready to display.
• Audio - Built-in dialogue audio playback with looping, reset, and volume control. Audio files are imported as native AudioClip assets.
• Save & Load - Persist global variables, character state, and once-only option tracking across sessions with a simple slot-based API.
• Multiple scripts - Full support for runScript (with return) and runFlow (in-script macros) with call stack management.
• Live Sync - Connect to the StoryFlow Editor via WebSocket and see your changes reflected in Unity in real time, without re-importing.

Architecture Overview

At the core of the package are three main classes:

• StoryFlowManager - A singleton MonoBehaviour that manages the project asset, shared global variables, runtime character copies, and once-only option tracking. It persists across scenes via DontDestroyOnLoad.
• StoryFlowComponent - A MonoBehaviour you add to any GameObject that needs to run dialogue. It handles script execution, broadcasts dialogue state updates via C# events, and provides public methods for controlling the dialogue flow.
• StoryFlowDialogueUI - An optional base MonoBehaviour you can extend to build your dialogue UI. Alternatively, implement IStoryFlowDialogueUI or subscribe to events directly for full control.

Documentation Sections

Getting Started

• Installation - System requirements, package setup, and project configuration
• Quick Start - End-to-end tutorial from export to in-game dialogue

Core Concepts

• StoryFlow Component - The main runtime component, its properties, events, and lifecycle
• Displaying Dialogue - Reading dialogue state, building your UI, and variable interpolation
• Handling Choices - Options, input types, once-only options, and conditional visibility
• Variables - Types, scopes, C# access, arrays, and reactive updates

Features

• Characters - Character data, portraits, per-character variables, and interpolation
• Audio - Dialogue audio playback, looping, format support, and component settings
• Images & Media - Image persistence, background images, and asset resolution
• Save & Load - Slot-based persistence with full state serialization
• Multiple Scripts - Script calls, flows, and call stack management

Advanced

• Live Sync - Real-time WebSocket connection with the StoryFlow Editor
• API Reference - Complete reference for all classes, structs, events, and methods
• Troubleshooting - Common issues, error messages, and solutions