StoryFlow for Godot

The StoryFlow Godot plugin lets you import your StoryFlow projects directly into Godot 4 and run them as fully interactive dialogue systems in your game. Design your stories visually in the StoryFlow Editor, export as JSON, and bring them to life in Godot with pure GDScript - no C++ or GDExtension required.

What the Plugin Provides

The main runtime and editor folders inside addons/storyflow/ are:

• core/ - The runtime GDScript files that ship with your game. Contains StoryFlowManager (autoload singleton), StoryFlowComponent (the node you add to scenes), data classes, and the full node execution runtime.
• editor/ - Tools for importing StoryFlow JSON projects, resolving media assets (images, audio) and live syncing with the StoryFlow Editor via WebSocket. The dock and Live Sync only run inside the Godot editor, but the folder must still ship with your game because the runtime autoload loads the importer from it.
• ui/ - A default dialogue UI scene (.tscn) with an accompanying script that you can use out of the box or customize to match your game's visual style.
• lipsync/ - The optional StoryFlowLipsync node, live audio analysis and editable viseme resources for character face blendshapes.

Features

• Story graph execution - Run StoryFlow Editor dialogue scripts with branching, loops, type conversions, strings, arrays, maps and Data Asset nodes.
• Pure GDScript API - Every function, signal, and data type is written in GDScript. Build your entire dialogue UI without writing any C++ or using GDExtension.
• 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. Multi-character casts via character-array variables. Character data is resolved and ready to display.
• Audio - Built-in dialogue audio playback with looping, volume control, and audio bus support.
• Lip sync - Drive character face blendshapes from dialogue audio with an optional rig mapping.
• Data Assets - Read inherited values and write session changes through graph nodes or GDScript.
• Save & Load - Persist global variables, character state, Data Asset changes and once-only options with a slot-based API.
• Multiple scripts - Full support for runScript (with return) and runFlow (in-script macros) with call stack management.
• Live Sync - Request an export from StoryFlow Editor over WebSocket and import it into Godot in one step. Restart the game to test updated files.
• Localization - Import translations from StoryFlow Editor and switch the project-wide language at runtime.
• Default dialogue UI - A ready-to-use .tscn scene with character portrait, name, rich text, options, and advance button. Customize it or build your own.

Architecture Overview

At the core of the plugin are three main pieces:

• StoryFlowManager - An autoload singleton (registered as StoryFlowRuntime) that manages the project data, shared global variables, runtime character copies, and once-only option tracking. It is registered automatically when you enable the plugin.
• StoryFlowComponent - A Node you add to any scene that needs to run dialogue. It handles script execution, emits dialogue state signals, and provides functions for controlling the dialogue flow.
• StoryFlowDialogueUI - An optional Control-based scene you can instantiate for your dialogue UI. It auto-binds to a StoryFlowComponent and displays dialogue text, character info, and option buttons out of the box.

Documentation Sections

Getting Started

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

Core Concepts

• StoryFlow Component - The main runtime node, its properties, signals, 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, GDScript access, arrays, maps and reactive updates

Features

• Characters - Character data, portraits, per-character variables, and interpolation
• Data Assets - Inherited values, typed access and saved runtime changes
• Localization - Imported translations, language selection and UI updates
• Audio - Dialogue audio playback, looping, format support, and component settings
• Lip Sync - Audio-driven face animation, rig mapping and tuning
• 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
• Exporting Your Game - How the runtime finds your project in an export, and what must ship with it
• API Reference - Complete reference for all classes, signals, and functions
• Troubleshooting - Common issues and solutions