StoryFlow for Unreal Engine

The StoryFlow Unreal Engine plugin lets you import your StoryFlow projects directly into Unreal Engine 5 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 Unreal with full Blueprint support.

What the Plugin Provides

The plugin is split into two modules:

• StoryFlowRuntime - The gameplay module that ships with your game. Contains the UStoryFlowComponent, the UStoryFlowSubsystem, data assets, and the full node execution runtime.
• StoryFlowEditor - An editor-only module for importing projects, resolving media assets, and live syncing with the StoryFlow Editor via WebSocket.

Features

• Story graph execution - Run dialogue, branches, loops, variables, arrays, maps and Data Asset nodes exported from story scripts.
• Blueprint-first API - Control dialogue, read story state and build your dialogue UI in Blueprints. C++ APIs are available too.
• Dialogue display - Rich dialogue state with title, text, character data, images, audio, options, and text blocks. Variable interpolation happens automatically.
• Dialogue tags - Tag a dialogue node in the StoryFlow Editor and the component raises OnDialogueTagReached as that line is entered, once per tag in authored order. The line's tags also travel on the dialogue state.
• Widget handover - Let the component create the dialogue widget and still decide where it lives. Turn off bAutoAddWidgetToViewport, catch OnDialogueWidgetCreated and put the widget in your HUD, a widget stack or a 3D widget component.
• Characters - Full character support with names, portraits and custom variables. Portraits resolve through the character, script, project asset cascade. The live OnCharacterVariableChanged delegate lets non-speaker UIs react to mutations, and helpers like GetCharacterArrayVariable, GetCharacter, GetCharacterVariableNames and GetCharacterPortrait cover the cases dialogue state does not.
• Audio - Built-in dialogue audio playback with looping, reset, volume control, and sound class support. MP3 files are automatically decoded to WAV on import.
• Save & Load - Persist globals, character state, once-only options and Data Asset changes with a slot-based API.
• Multiple scripts - Full support for runScript (with return) and runFlow (in-script macros) with call stack management.
• Live Sync - Stop Play In Editor, then request an export from StoryFlow Editor over WebSocket and import it into Unreal in one step.
• Localization - Import authored translations, switch the game-wide language and update your UI when it changes.
• Lip sync - Drive morph target faces and MetaHumans from dialogue audio with a separate actor component.

Architecture Overview

At the core of the plugin are three main classes:

• UStoryFlowSubsystem - A GameInstanceSubsystem that manages the project asset, shared variables, characters, Data Asset changes, language and save state. It auto-loads from /Game/StoryFlow/SF_Project on startup.
• UStoryFlowComponent - An ActorComponent you add to any actor that needs to run dialogue. It handles script execution, broadcasts dialogue state updates, and provides Blueprint functions for controlling the dialogue flow.
• UStoryFlowDialogueWidget - An optional base UUserWidget you can extend in Blueprint for your dialogue UI. It auto-binds to a component and receives dialogue events.

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 component, its properties, events, and lifecycle
• Displaying Dialogue - Reading dialogue state, building your UI, and variable interpolation
• Dialogue Tags - Tag events, their firing rules and reading tags off dialogue state
• Handling Choices - Options, input types, once-only options, and conditional visibility
• Variables - Types, scopes, Blueprint access, arrays, and reactive updates

Features

• Characters - Character data, portraits, per-character variables, and interpolation
• Data Assets - Inherited values for dialogue and game code
• Localization - Import translations and switch languages
• Audio - Dialogue audio playback, looping, format support, and component settings
• Lip Sync - Audio-driven mouth movement for morph target faces and MetaHumans
• 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, delegates, and functions