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 plugin is organized into three folders inside addons/storyflow/:

• 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/ - Editor-only tools for importing StoryFlow JSON projects, resolving media assets (images, audio), and live syncing with the StoryFlow Editor via WebSocket. This code runs only in the Godot editor.
• 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.

Features

• Full node graph execution - All 160+ node types from the StoryFlow Editor are supported, including branching, loops, type conversions, string operations, and array manipulation.
• 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. Character data is resolved and ready to display.
• Audio - Built-in dialogue audio playback with looping, volume control, and audio bus support.
• 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 Godot in real time, without re-importing.
• Localization - Built-in string table system with language code lookup. Switch languages 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, 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, signals, and functions
• Troubleshooting - Common issues and solutions