API Reference
Complete reference for the StoryFlow Unreal Engine plugin API. This page covers all public classes, structs, enums, delegates, and functions available in both Blueprint and C++.
Reading This Reference
Properties marked EditAnywhere / BlueprintReadWrite can be set in the Details panel and from Blueprints. Functions marked BlueprintCallable appear in the Blueprint action menu. Functions marked BlueprintPure can be used as expression nodes without execution pins.
UStoryFlowComponent
UActorComponent — declared with BlueprintType, ClassGroup=(StoryFlow), meta=(BlueprintSpawnableComponent). The core runtime component that drives dialogue execution. Add it to any actor that needs to run StoryFlow dialogue.
Properties
Script FString Script path relative to the StoryFlow project root. Uses meta=(GetOptions="GetAvailableScripts") to provide a dropdown of all imported scripts in the editor Details panel.
LanguageCode FString default: "en" Language code used for string table lookup. Determines which localized text is displayed in dialogue. Currently only "en" is supported — multi-language localization is planned for a future release.
DialogueWidgetClass TSubclassOf<UStoryFlowDialogueWidget> Optional. If set, the component automatically creates and manages an instance of this widget class. The widget is added to the viewport when dialogue starts and removed when it ends.
bStopAudioOnDialogueEnd bool default: true When enabled, all audio spawned by this component is stopped when the dialogue ends. Disable if you want audio to continue playing after the conversation finishes.
DialogueSoundClass USoundClass* Assigns all dialogue audio to a specific sound class. Use this to control volume through your game's audio mix.
DialogueVolumeMultiplier float default: 1.0 Volume multiplier applied to all dialogue audio. Clamped between 0.0 and 2.0.
DialogueConcurrency USoundConcurrency* Controls how multiple audio sources from this component interact. Define priority and fade behavior when dialogue audio overlaps.
Functions
| Function | Return Type | Description |
|---|---|---|
| Dialogue Control | ||
StartDialogue() | void | Begin dialogue execution using the configured Script property. |
StartDialogueWithScript(FString ScriptPath) | void | Begin dialogue execution with a specific script, overriding the component's Script property. |
SelectOption(FString OptionId) | void | Select a dialogue option by its ID. Advances execution along the chosen path. |
AdvanceDialogue() | void | Advance a narrative-only dialogue node (no options). Equivalent to the player clicking "continue". |
StopDialogue() | void | Immediately stop dialogue execution. Fires OnDialogueEnded. |
PauseDialogue() | void | Pause dialogue execution. State is preserved; no further events fire until resumed. |
ResumeDialogue() | void | Resume a paused dialogue. Execution continues from where it was paused. |
| State Access (BlueprintPure) | ||
GetCurrentDialogue() | FStoryFlowDialogueState | Get the current dialogue state containing text, character, options, images, and audio. |
IsDialogueActive() | bool | Check if a dialogue is currently running. |
IsWaitingForInput() | bool | Check if the dialogue is waiting for the player to select an option. |
IsPaused() | bool | Check if the dialogue is currently paused. |
GetStoryFlowSubsystem() | UStoryFlowSubsystem* | Get a reference to the game instance subsystem for shared state access. |
GetProject() | UStoryFlowProjectAsset* | Get the project asset containing all imported scripts, characters, and media. |
| Variable Access | ||
GetBoolVariable(FString Id, bool bGlobal) | bool | Get a boolean variable value. Set bGlobal to access global variables. |
SetBoolVariable(FString Id, bool Value, bool bGlobal) | void | Set a boolean variable value. |
GetIntVariable(FString Id, bool bGlobal) | int32 | Get an integer variable value. |
SetIntVariable(FString Id, int32 Value, bool bGlobal) | void | Set an integer variable value. |
GetFloatVariable(FString Id, bool bGlobal) | float | Get a float variable value. |
SetFloatVariable(FString Id, float Value, bool bGlobal) | void | Set a float variable value. |
GetStringVariable(FString Id, bool bGlobal) | FString | Get a string variable value. |
SetStringVariable(FString Id, FString Value, bool bGlobal) | void | Set a string variable value. |
GetEnumVariable(FString Id, bool bGlobal) | FString | Get an enum variable value as its string representation. |
SetEnumVariable(FString Id, FString Value, bool bGlobal) | void | Set an enum variable value. |
GetCharacterVariable(FString CharPath, FString VarName) | FStoryFlowVariant | Get a character-specific variable by character path and variable name. |
SetCharacterVariable(FString CharPath, FString VarName, FStoryFlowVariant Value) | void | Set a character-specific variable. |
ResetVariables() | void | Reset all local script variables to their default values. Does not affect global variables. |
| Localization | ||
GetLocalizedString(FString Key) | FString | Look up a localized string from the string table using the current LanguageCode. BlueprintPure. |
Delegates
All delegates are BlueprintAssignable multicast delegates under the StoryFlow | Events category. Bind to these in Blueprint event graphs or in C++ with AddDynamic.
| Delegate | Parameters | Description |
|---|---|---|
OnDialogueStarted | None | Fired when dialogue execution begins. Use to show UI, disable player input, or enter a dialogue camera. |
OnDialogueUpdated | FStoryFlowDialogueState | Fired every time dialogue state changes — new text, options, character, or variable interpolation update. The primary UI update event. |
OnDialogueEnded | None | Fired when dialogue execution completes (End node reached or StopDialogue called). Use to hide UI and re-enable input. |
OnVariableChanged | FString Id, FStoryFlowVariant Value, bool bGlobal | Fired whenever a variable is modified during execution. Useful for HUD updates, animation triggers, or logging. |
OnScriptStarted | FString ScriptPath | Fired when execution enters a new script via a runScript node. |
OnScriptEnded | FString ScriptPath | Fired when execution returns from a script. |
OnError | FString Message | Fired when the runtime encounters an error (missing script, invalid connection, stack overflow). |
OnBackgroundImageChanged | FString ImagePath | Fired when a setBackgroundImage node executes. Use to update scene backgrounds or visual novel imagery. |
OnAudioPlayRequested | FString AudioPath, bool bLoop | Fired when a playAudio node executes. Use for custom audio handling instead of the built-in audio system. |
OnDialogueUpdated Is Your Main Hook
In most projects, OnDialogueUpdated is the only event you need to build a complete dialogue UI. It provides the full FStoryFlowDialogueState including text, character, options, images, and audio every time anything changes.
UStoryFlowSubsystem
UGameInstanceSubsystem — lives for the entire game session. Acts as the central authority for shared state: the project asset, global variables, runtime characters, and save/load operations. All UStoryFlowComponent instances share the same subsystem.
Functions
| Function | Return Type | Description |
|---|---|---|
| Project Access | ||
GetProject() | UStoryFlowProjectAsset* | Get the currently loaded project asset. |
SetProject(UStoryFlowProjectAsset* NewProject) | void | Manually set the project asset. Useful for runtime project switching. |
HasProject() | bool | Check if a project is currently loaded. |
GetScript(FString ScriptPath) | UStoryFlowScriptAsset* | Get a specific script asset by its path. |
GetAllScriptPaths() | TArray<FString> | Get an array of all available script paths in the project. |
| State Management | ||
ResetGlobalVariables() | void | Reset all global variables to their default values defined in the project. |
ResetRuntimeCharacters() | void | Reset all runtime character data to the defaults imported from the project. |
ResetAllState() | void | Reset everything — global variables, runtime characters, and once-only tracking. Use for "New Game" scenarios. |
| Save / Load | ||
SaveToSlot(FString SlotName, int32 UserIndex) | bool | Save the current StoryFlow state (global variables, characters, once-only tracking) to a named save slot. Returns true on success. |
LoadFromSlot(FString SlotName, int32 UserIndex) | bool | Load StoryFlow state from a named save slot. Returns true on success. |
DoesSaveExist(FString SlotName, int32 UserIndex) | bool | Check if a save slot exists. Static function — can be called without a subsystem reference. |
DeleteSave(FString SlotName, int32 UserIndex) | bool | Delete a save slot. Static function. Returns true on success. |
| Query | ||
IsDialogueActive() | bool | Check if any UStoryFlowComponent in the game currently has an active dialogue. |
Key Data Structs
These structs are used throughout the plugin API to pass dialogue state, option data, character information, and variable values between the runtime and your game code.
FStoryFlowDialogueState
The primary data struct passed through OnDialogueUpdated. Contains a complete snapshot of the current dialogue state, including resolved text, character, options, and media.
| Field | Type | Description |
|---|---|---|
NodeId | FString | The ID of the current dialogue node in the script graph. |
Title | FString | The resolved title text for this dialogue node. May be empty if no title is defined. |
Text | FString | The resolved dialogue text with all variable interpolation applied. This is the main body text to display. |
Image | UTexture2D* | The current dialogue image, if any. May be nullptr. |
Audio | USoundBase* | The current dialogue audio, if any. May be nullptr. |
Character | FStoryFlowCharacterData | The speaking character's data, including name, portrait, and variables. |
TextBlocks | TArray<FStoryFlowDialogueOption> | Non-interactive text blocks displayed alongside the dialogue. These are informational and cannot be selected. |
Options | TArray<FStoryFlowDialogueOption> | Clickable choices the player can select. Pass the option's Id to SelectOption when chosen. |
bIsValid | bool | Whether this state represents an active dialogue. false if no dialogue is running. |
bCanAdvance | bool | Whether the dialogue can be advanced (narrative-only mode with no options). When true, call AdvanceDialogue to proceed. |
FStoryFlowDialogueOption
Represents a single dialogue choice or text block within a dialogue node.
| Field | Type | Description |
|---|---|---|
Id | FString | Unique identifier for this option. Pass to SelectOption when the player makes a choice. |
Text | FString | The resolved display text for this option with variable interpolation applied. |
FStoryFlowCharacterData
Contains the resolved data for a character in the current dialogue, including their name, portrait image, and custom variables.
| Field | Type | Description |
|---|---|---|
Name | FString | The resolved display name for this character (localized if a string table entry exists). |
Image | UTexture2D* | The character's portrait image. May be nullptr if no image is assigned. |
Variables | TMap<FString, FStoryFlowVariant> | Custom variables defined on this character. Keys are variable names, values are typed variants. |
FStoryFlowVariable
Represents a variable definition as imported from the StoryFlow project. Contains metadata about the variable in addition to its current value.
| Field | Type | Description |
|---|---|---|
Id | FString | Generated hash identifier in the format var_XXXXXXXX. Used when calling Get/Set variable functions. |
Name | FString | The string table key for this variable's display name. |
Type | EStoryFlowVariableType | The data type of this variable (Boolean, Integer, Float, String, Enum, etc.). |
Value | FStoryFlowVariant | The current value of the variable, stored as a type-safe variant. |
bIsArray | bool | Whether this variable holds an array of values rather than a single value. |
EnumValues | TArray<FString> | For enum-type variables, the list of valid enum options. Empty for non-enum types. |
FStoryFlowVariant
A type-safe value container used throughout the plugin to hold variable values of any supported type. Internally stores the value and its type tag, providing typed accessors and factory methods.
Accessor methods (return the stored value or a default if the type does not match):
GetBool()— returnsboolGetInt()— returnsint32GetFloat()— returnsfloatGetString()— returnsFString
Factory methods (create a variant from a typed value):
FStoryFlowVariant::FromBool(bool Value)FStoryFlowVariant::FromInt(int32 Value)FStoryFlowVariant::FromFloat(float Value)FStoryFlowVariant::FromString(const FString& Value)
Use the setter methods (SetBool, SetInt, SetFloat, SetString, SetEnum) on an existing variant, or use the static factory methods to create a new variant in one step.
Enums
EStoryFlowVariableType
Defines the data type for a StoryFlow variable:
| Value | Description |
|---|---|
None | Untyped / uninitialized variable. |
Boolean | True/false value. |
Integer | Whole number (int32). |
Float | Floating-point number. |
String | Text value. |
Enum | Enumeration value (stored as string, constrained to defined options). |
Image | Image asset reference. |
Audio | Audio asset reference. |
Character | Character asset reference. |
EStoryFlowNodeType
Enumerates all node types supported by the StoryFlow runtime. There are over 200 node types covering the full range of StoryFlow Editor functionality, including:
- Control flow — start, end, branch, runScript, runFlow, forEach, while, wait
- Dialogue — dialogue nodes with text, options, characters, and media
- Variables — get/set nodes for all types (bool, int, float, string, enum)
- Logic — and, or, not, equal, compare, arithmetic operations
- Arrays — push, pop, get, set, length, contains, forEach, sort, filter
- Loops — forEach, while, break, continue
- Media — setImage, setAudio, setBackgroundImage, playAudio
- Characters — getCharacter, setCharacterVariable, getCharacterVariable
UStoryFlowDialogueWidget
UUserWidget — declared with Blueprintable. A base widget class designed to be subclassed in Blueprint for building dialogue UI. When assigned to a component's DialogueWidgetClass, the component automatically creates, shows, and removes the widget during dialogue lifecycle.
Setup function:
InitializeWithComponent(UStoryFlowComponent* Component)— Called automatically by the component after widget creation. Stores a reference to the owning component and binds internal delegate handlers.
Blueprint-implementable events (override these in your widget Blueprint):
OnDialogueUpdated(FStoryFlowDialogueState State)— Called when the dialogue state changes. Update your text, character portrait, and option buttons here.OnDialogueStarted()— Called when dialogue begins. Use to play intro animations or show the widget.OnDialogueEnded()— Called when dialogue ends. Use to play outro animations or trigger cleanup.OnVariableChanged(FString Id, FStoryFlowVariant Value, bool bGlobal)— Called when a variable changes during dialogue. Use for live HUD updates.
Helper functions (callable from your widget Blueprint):
SelectOption(FString OptionId)— Convenience wrapper that callsSelectOptionon the owning component.AdvanceDialogue()— Convenience wrapper that callsAdvanceDialogueon the owning component.GetCurrentDialogueState()— Returns the currentFStoryFlowDialogueStatefrom the owning component.IsDialogueActive()— Returns whether the owning component has an active dialogue.GetLocalizedString(FString Key)— Convenience wrapper for string table lookup using the component's language code.
Widget Lifecycle
When using DialogueWidgetClass, you do not need to manually create or destroy the widget. The component handles adding it to the viewport on StartDialogue and removing it on OnDialogueEnded. You only need to implement the Blueprint events to update your UI.
UStoryFlowEditorSubsystem
UEditorSubsystem — editor-only. Manages the connection between the Unreal Editor and the StoryFlow Editor desktop application for live sync and project import. This class is only available in editor builds and is not included in packaged games.
Connection functions:
ConnectToStoryFlow(FString Host, int32 Port)— Establish a WebSocket connection to a running StoryFlow Editor instance.Disconnect()— Close the active connection.IsConnected()— Check if currently connected to the StoryFlow Editor.
Sync and import functions:
RequestSync()— Request a full project sync from the connected StoryFlow Editor.ImportProject(FString BuildDirectory, FString ContentPath = "/Game/StoryFlow")— Import a StoryFlow project from a build directory containing exported JSON files. ReturnsUStoryFlowProjectAsset*.ImportScript(FString JsonPath, FString ContentPath = "/Game/StoryFlow/Data")— Import a single script from a JSON file. ReturnsUStoryFlowScriptAsset*.SetContentPath(FString Path)/GetContentPath()— Get or set the content directory path where imported assets are stored.GetProjectAsset()— Get the project asset that was created or updated by the last import.
Delegates:
OnConnected— Fired when a connection to the StoryFlow Editor is established.OnDisconnected— Fired when the connection is lost or closed.OnSyncComplete— Fired when a sync or import operation completes successfully.
Editor-Only API
The UStoryFlowEditorSubsystem and all live sync functionality are available only in the Unreal Editor. They are compiled out of packaged builds. Your game code should never depend on this class. See the Live Sync guide for usage details.