Skip to main content

API Reference

Complete reference for the StoryFlow Godot plugin API. This page covers all public classes, data types, enums, signals, and functions available in GDScript.

Reading This Reference

Properties marked @export are configurable in the Inspector panel. Signals can be connected via the editor's Node panel or in code with .connect(). All functions are callable from any GDScript file that has a reference to the relevant object.

StoryFlowComponent

Node - The core runtime node that drives dialogue execution. Add it as a child of any scene that needs to run StoryFlow dialogue.

Export Properties

script_path String

Script path relative to the StoryFlow project root. Selects which script to run when start_dialogue() is called.

language_code String default: "en"

Language code used for string table lookup. Determines which localized text is displayed in dialogue.

dialogue_ui_scene PackedScene

Optional. If set, the component automatically creates and manages an instance of this scene as the dialogue UI. The UI is added to the viewport when dialogue starts and removed when it ends.

stop_audio_on_dialogue_end 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.

dialogue_audio_bus StringName default: &"Master"

The audio bus to use for dialogue audio playback. Use this to route dialogue audio through your game's audio mix.

dialogue_volume_db float default: 0.0

Volume offset in decibels applied to all dialogue audio playback.

Signals

Connect to these signals in GDScript with .connect() or via the Node panel's Signals tab in the editor.

Signal Parameters Description
dialogue_started None Fired when dialogue execution begins. Use to show UI, disable player input, or enter a dialogue camera.
dialogue_updated state: StoryFlowDialogueState Fired every time dialogue state changes - new text, options, character, or variable interpolation update. The primary UI update signal.
dialogue_ended None Fired when dialogue execution completes (End node reached or stop_dialogue() called). Use to hide UI and re-enable input.
variable_changed info: StoryFlowVariableChangeInfo Fired whenever a variable is modified during execution. The info contains id, name, value, and is_global.
script_started script_path_name: String Fired when execution enters a new script via a runScript node.
script_ended script_path_name: String Fired when execution returns from a script.
error_occurred message: String Fired when the runtime encounters an error (missing script, invalid connection, stack overflow).
background_image_changed image_path: String Fired when a setBackgroundImage node executes. Use to update scene backgrounds or visual novel imagery.
audio_play_requested audio_path: String, loop: bool Fired when a playAudio node executes. Use for custom audio handling instead of the built-in audio system.

dialogue_updated Is Your Main Hook

In most projects, dialogue_updated is the only signal you need to build a complete dialogue UI. It provides the full StoryFlowDialogueState including text, character, options, images, and audio every time anything changes.

Control Functions

Function Return Type Description
start_dialogue() void Begin dialogue execution using the configured script_path property.
start_dialogue_with_script(path: String) void Begin dialogue execution with a specific script, overriding the component's script_path property.
select_option(option_id: String) void Select a dialogue option by its ID. Advances execution along the chosen path.
advance_dialogue() void Advance a narrative-only dialogue node (no options). Equivalent to the player clicking "continue".
stop_dialogue() void Immediately stop dialogue execution. Emits dialogue_ended.
pause_dialogue() void Pause dialogue execution. State is preserved; no further signals fire until resumed.
resume_dialogue() void Resume a paused dialogue. Execution continues from where it was paused.

State Functions

Function Return Type Description
get_current_dialogue() StoryFlowDialogueState Get the current dialogue state containing text, character, options, images, and audio.
is_dialogue_active() bool Check if a dialogue is currently running.
is_waiting_for_input() bool Check if the dialogue is waiting for the player to select an option or advance.
is_paused() bool Check if the dialogue is currently paused.
get_manager() Node Get a reference to the StoryFlowRuntime autoload manager singleton for shared state access.

Variable Functions

Function Return Type Description
get_bool_variable(name: String) bool Get a boolean variable by display name.
set_bool_variable(name: String, value: bool) void Set a boolean variable by display name.
get_int_variable(name: String) int Get an integer variable by display name.
set_int_variable(name: String, value: int) void Set an integer variable by display name.
get_float_variable(name: String) float Get a float variable by display name.
set_float_variable(name: String, value: float) void Set a float variable by display name.
get_string_variable(name: String) String Get a string variable by display name.
set_string_variable(name: String, value: String) void Set a string variable by display name.
get_enum_variable(name: String) String Get an enum variable by display name as its string representation.
set_enum_variable(name: String, value: String) void Set an enum variable by display name.
get_character_variable(character_path: String, variable_name: String) StoryFlowVariant Get a character-specific variable by character path and variable name.
set_character_variable(character_path: String, variable_name: String, value: StoryFlowVariant) void Set a character-specific variable.
reset_variables() void Reset all local script variables to their default values. Does not affect global variables.
get_localized_string(key: String) String Get a localized string by key from the current script or global strings, using the component's language_code.

StoryFlowManager

Node (Autoload Singleton) - Lives for the entire game session. Acts as the central authority for shared state: the project resource, global variables, runtime characters, and save/load operations. All StoryFlowComponent instances share the same manager. Access it globally via StoryFlowRuntime or from a component via get_manager().

Project Functions

Function Return Type Description
get_project() StoryFlowProject Get the currently loaded project resource.
set_project(project: StoryFlowProject) void Manually set the project resource. Useful for runtime project switching.
has_project() bool Check if a project is currently loaded.
get_storyflow_script(path: String) StoryFlowScript Get a specific script resource by its path.
get_all_script_paths() PackedStringArray Get an array of all available script paths in the project.

Global Variable Functions

Function Return Type Description
get_global_variables() Dictionary Get a reference to all global variables as a dictionary keyed by variable ID.
get_global_variable(id: String) Dictionary Get a single global variable entry by its ID. Returns a dictionary with keys like "id", "name", "type", "value" (StoryFlowVariant). Returns an empty dictionary if the ID is not found.
set_global_variable(id: String, value: StoryFlowVariant) void Set a global variable by its ID.
reset_global_variables() void Reset all global variables to their default values defined in the project.

Character Functions

Function Return Type Description
get_runtime_characters() Dictionary Get all runtime character data as a dictionary keyed by normalized character path.
get_runtime_character(path: String) StoryFlowCharacter Get a specific runtime character by its path.
reset_runtime_characters() void Reset all runtime character data to project defaults.

Once-Only Functions

Function Return Type Description
mark_option_used(key: String) void Mark a once-only option as used. Called internally by the runtime.
is_option_used(key: String) bool Check if a once-only option has been used.
get_used_once_only_options() Dictionary Get the full set of used once-only option keys.

State Functions

Function Return Type Description
is_dialogue_active() bool Check if any StoryFlowComponent in the game currently has an active dialogue.
register_dialogue_start() void Register that a dialogue has started. Called internally by components.
register_dialogue_end() void Register that a dialogue has ended. Called internally by components.

Save & Load Functions

Function Return Type Description
save_to_slot(slot_name: String) bool Save global variables, runtime characters, and once-only tracking to a named slot. Returns true on success.
load_from_slot(slot_name: String) bool Load state from a named slot. Returns false if dialogue is active, file missing, or parse error.
does_save_exist(slot_name: String) bool Check if a save file exists for the given slot name.
delete_save(slot_name: String) void Delete a save file for the given slot name.
list_save_slots() PackedStringArray List all save slot names that have existing save files.

Reset Functions

Function Return Type Description
reset_global_variables() void Reset all global variables to their default values defined in the project.
reset_runtime_characters() void Reset all runtime character data to project defaults.
reset_all_state() void Reset everything - global variables, runtime characters, and once-only tracking. Use for "New Game" scenarios.

Data Classes

These classes are used throughout the plugin API to pass dialogue state, option data, character information, and variable values between the runtime and your game code.

StoryFlowDialogueState

The primary data class passed through dialogue_updated. Contains a complete snapshot of the current dialogue state, including resolved text, character, options, and media.

Property Type Description
is_valid bool Whether this state represents a valid dialogue. Check before using other fields.
node_id String The ID of the current dialogue node in the script graph.
title String The resolved title text for this dialogue node. May be empty.
text String The resolved dialogue text with all variable interpolation applied.
character StoryFlowCharacterData The character associated with this dialogue node. May be null.
image Texture2D The current dialogue image, if any. May be null.
image_key String The asset key for the current image. Used internally for asset resolution.
audio AudioStream The current dialogue audio, if any. May be null.
audio_key String The asset key for the current audio. Used internally for playback logic.
options Array[StoryFlowDialogueOption] Available dialogue options. Empty array if this is a narrative-only node.
text_blocks Array[StoryFlowTextBlock] Text blocks for structured text content within the dialogue.
can_advance bool Whether the dialogue can be advanced with advance_dialogue() (true for narrative-only nodes).
audio_advance_on_end bool Whether the dialogue will auto-advance after the attached audio finishes playing.
audio_allow_skip bool Whether the player can skip audio and advance early (only relevant when audio_advance_on_end is true).

Methods:

Method Return Type Description
find_option(option_id: String) StoryFlowDialogueOption Find a specific option by its ID. Returns null if not found.

StoryFlowDialogueOption

Represents a single dialogue option (button/choice) within a dialogue node.

Property Type Description
id String Unique identifier for this option. Pass to select_option().
text String The display text for this option, with variable interpolation applied.

StoryFlowCharacterData

Contains resolved character information for display in dialogue UI.

Property Type Description
name String The character's display name.
image Texture2D The character's portrait image. May be null.
variables Dictionary Per-character variables as a dictionary keyed by variable name.

StoryFlowTextBlock

Represents a block of structured text within a dialogue node.

Property Type Description
id String Unique identifier for this text block.
text String The text content of this block, with variable interpolation applied.

StoryFlowVariableChangeInfo

Contains information about a variable change event, passed through the variable_changed signal.

Property Type Description
id String The internal ID of the changed variable.
name String The display name of the changed variable.
value StoryFlowVariant The new value of the variable.
is_global bool Whether this is a global variable (true) or a local script variable (false).

StoryFlowVariant

A type-safe variant that can hold boolean, integer, float, string, enum, or array values. Used throughout the plugin for variable storage and manipulation.

Properties:

Property Type Description
type StoryFlowTypes.VariableType The type of value this variant holds (BOOLEAN, INTEGER, FLOAT, STRING, ENUM, etc.).

Getters and Setters:

Method Return / Param Type Description
Getters
get_bool(default: bool = false) bool Get the boolean value. Returns default if the type doesn't match.
get_int(default: int = 0) int Get the integer value. Returns default if the type doesn't match.
get_float(default: float = 0.0) float Get the float value. Returns default if the type doesn't match.
get_string(default: String = "") String Get the string or enum value. Returns default if the type doesn't match. Enum values are stored as strings internally, so use get_string() to read both string and enum types.
get_array() Array Get the array value.
Setters
set_bool(value: bool) void Set a boolean value.
set_int(value: int) void Set an integer value.
set_float(value: float) void Set a float value.
set_string(value: String) void Set a string value.
set_enum(value: String) void Set an enum value.
set_array(value: Array) void Set an array value.

Factory Methods (Static):

Method Return Type Description
StoryFlowVariant.from_bool(value: bool) StoryFlowVariant Create a variant holding a boolean value.
StoryFlowVariant.from_int(value: int) StoryFlowVariant Create a variant holding an integer value.
StoryFlowVariant.from_float(value: float) StoryFlowVariant Create a variant holding a float value.
StoryFlowVariant.from_string(value: String) StoryFlowVariant Create a variant holding a string value.
StoryFlowVariant.from_enum(value: String) StoryFlowVariant Create a variant holding an enum value.
StoryFlowVariant.from_array(value: Array) StoryFlowVariant Create a variant holding an array value.

Utility Methods:

Method Return Type Description
is_valid() bool Check if this variant holds a valid value (type is not NONE).
to_display_string() String Get a human-readable string representation of the value.
duplicate_variant() StoryFlowVariant Create a deep copy of this variant.
reset() void Reset this variant to an uninitialized state. Sets the type to NONE and clears all stored values.
StoryFlowVariant.deep_copy_variables(source: Dictionary) Dictionary Static. Deep copy a dictionary of StoryFlowVariant values.

StoryFlowCallFrame

Captures the state of a script call for the call_stack. Created internally when a runScript node executes and popped when the called script reaches an End node.

Property Type Description
script_path String Path of the script that made the call.
return_node_id String The runScript node to resume execution from on return.
script_asset StoryFlowScript Reference to the calling script resource.
saved_variables Dictionary Snapshot of local variables at the time of the call.
saved_flow_stack Array[String] Active flow IDs at the time of the call.

StoryFlowLoopFrame

Tracks loop execution state for forEach and similar loop nodes.

Property Type Description
node_id String The ID of the loop node.
type StoryFlowTypes.LoopType The type of loop (e.g., FOR_EACH).
current_index int The current iteration index.

Resource Classes

These classes represent the imported StoryFlow project structure. They all extend RefCounted (not Resource) because the plugin uses JSON-based persistence rather than Godot's .tres serialization.

StoryFlowProject

RefCounted - The top-level container for an imported StoryFlow project. Holds all scripts, characters, and resolved asset references.

Property Type Description
version String The project version string.
api_version String The API version of the exported project format.
title String The project title.
description String The project description.
startup_script String The path of the default startup script.
scripts Dictionary All scripts keyed by normalized path. Values are StoryFlowScript resources.
characters Dictionary All characters keyed by normalized path. Values are StoryFlowCharacter resources.
global_variables Dictionary Default global variables defined at the project level.
global_strings Dictionary Global localization strings keyed by "lang.key" format (e.g. "en.greeting").
resolved_assets Dictionary Project-level resolved media assets (images, audio).

Methods:

Method Return Type Description
get_storyflow_script(path: String) StoryFlowScript Get a script by its normalized path. Returns null if not found.
get_all_script_paths() PackedStringArray Get all script paths in the project.
get_localized_string(key: String, language: String) String Look up a string from the global string table. Falls back to the key itself if not found.
find_character(character_path: String) StoryFlowCharacter Find a character by path (automatically normalized). Returns null if not found.

StoryFlowScript

RefCounted - Represents a single imported script file. Contains the node graph, connections, local variables, and script-specific assets.

Property Type Description
script_path String The file path of this script within the project.
nodes Dictionary All nodes in the script keyed by node ID.
connections Array All connections between nodes. Each entry is a Dictionary with "id", "source", "target", "source_handle", "target_handle".
variables Dictionary Local variables defined in this script.
strings Dictionary Localization strings for this script. Keyed by "lang.key" format (e.g. "en.greeting").
assets Dictionary Raw asset definitions keyed by ID. Each value is a Dictionary with "id", "type", "path".
flows Dictionary Flow definitions keyed by flow ID. Each value is a Dictionary with "id", "name", "is_exit".
resolved_assets Dictionary Script-specific resolved media assets.

StoryFlowCharacter

RefCounted - Represents an imported character definition with name, portrait, and per-character variables.

Property Type Description
character_name String String table key for the character's display name.
image_key String Asset key for the character's default portrait image. The actual Texture2D is resolved via resolved_assets.
character_path String Normalized character path used for lookup.
variables Dictionary Per-character variables. Keyed by variable name, values are dictionaries with "name", "type", "value" (StoryFlowVariant).
resolved_assets Dictionary Resolved media assets for this character. Keyed by asset key, values are Resource objects (e.g. Texture2D).

Enums

All enums are defined in the StoryFlowTypes class and accessed via StoryFlowTypes.EnumName.VALUE.

StoryFlowTypes.VariableType

Value Description
NONE No type / invalid.
BOOLEAN Boolean value (true / false).
INTEGER Integer value.
FLOAT Floating-point value.
STRING String value.
ENUM Enum value (stored as string).
IMAGE Image asset reference.
AUDIO Audio asset reference.
CHARACTER Character asset reference.

StoryFlowTypes.NodeType (Summary)

The NodeType enum contains 160+ values covering every node type in the StoryFlow Editor. Here are the most commonly referenced types:

Category Key Values
Flow Control START, END, BRANCH, DIALOGUE, RUN_SCRIPT, RUN_FLOW, ENTRY_FLOW
Boolean GET_BOOL, SET_BOOL, NOT_BOOL, AND_BOOL, OR_BOOL, EQUAL_BOOL
Integer GET_INT, SET_INT, PLUS, MINUS, MULTIPLY, DIVIDE, RANDOM
Float GET_FLOAT, SET_FLOAT, PLUS_FLOAT, MINUS_FLOAT, MULTIPLY_FLOAT, DIVIDE_FLOAT, RANDOM_FLOAT
String GET_STRING, SET_STRING, CONCATENATE_STRING, LENGTH_STRING, EQUAL_STRING, CONTAINS_STRING
Enum GET_ENUM, SET_ENUM, EQUAL_ENUM, SWITCH_ON_ENUM, RANDOM_BRANCH
Arrays GET_*_ARRAY, SET_*_ARRAY, ADD_TO_*_ARRAY, REMOVE_FROM_*_ARRAY, CLEAR_*_ARRAY, ARRAY_LENGTH_*, FOR_EACH_*_LOOP (where * is BOOL, INT, FLOAT, STRING, IMAGE, CHARACTER, or AUDIO)
Media GET_IMAGE, SET_IMAGE, GET_AUDIO, SET_AUDIO, GET_CHARACTER, SET_CHARACTER
Conversion INT_TO_FLOAT, FLOAT_TO_INT, INT_TO_STRING, BOOLEAN_TO_INT, INT_TO_BOOLEAN, ENUM_TO_STRING, etc.

StoryFlowTypes.AssetType

Value Description
IMAGE Image asset (PNG, JPG, WebP).
AUDIO Audio asset (WAV, OGG).
VIDEO Video asset.

StoryFlowTypes.LoopType

Value Description
FOR_EACH Iterates over each element in an array.

StoryFlowDialogueUI

Control - The default dialogue UI scene included with the plugin. It auto-binds to a StoryFlowComponent and displays character info, dialogue text, options, and an advance button. You can use it as-is or duplicate and customize it.

option_button_scene PackedScene

Optional custom button scene for dialogue options. If not set, the UI creates plain Button nodes for each option.

The UI is connected to a StoryFlowComponent via the initialize_with_component(component) method, which is called automatically when instantiated through the component's dialogue_ui_scene property. It then listens to dialogue_started, dialogue_updated, and dialogue_ended signals and updates its child nodes (character name label, portrait texture, rich text label, option buttons container, advance button) based on the current StoryFlowDialogueState.

StoryFlowWebSocketSync

RefCounted - Editor-only class that manages the WebSocket connection to the StoryFlow Editor for live synchronization. Not available in exported builds.

Signals:

Signal Parameters Description
connected None Fires when WebSocket connection is established.
disconnected None Fires when WebSocket connection is lost.
sync_complete project: StoryFlowProject Fires when project sync finishes with the new project resource.

Methods:

Method Return Type Description
connect_to_editor(host: String = "localhost", port: int = 9000) void Establish WebSocket connection to StoryFlow Editor.
disconnect_from_editor() void Close the WebSocket connection.
is_connected_to_editor() bool Check if WebSocket is currently connected.
request_sync() void Request a full project sync from the editor.
set_output_dir(dir: String) void Set the output directory for imported files.
poll() void Process incoming WebSocket messages. Called by the editor dock timer at 0.1s intervals.

Related Topics

→ StoryFlow Component → Variables → Save & Load → Troubleshooting

Need Help?

Join our Discord community to ask questions, share your projects, report bugs, and get support from the team and other users.

Join Discord