StoryFlow Component

The StoryFlow Component is the core node that drives dialogue execution in your Godot project. It manages the runtime, processes node graphs, and emits signals your UI can respond to.

Overview

StoryFlowComponent extends Node, which means you can add it as a child of any node in your scene tree - an NPC, a dialogue manager, a player character, or any other node that needs to run dialogue.

Internally, the component manages the execution engine that walks the node graph, handles the call stack, manages script transitions, and produces dialogue state. You do not interact with the internal engine directly. The component exposes a clean GDScript API for starting dialogue, selecting options, reading variables, and listening to signals.

Adding the Component

In the Editor

1. Open the scene where you want to run dialogue (for example, your NPC scene).
2. Select the parent node, then click Add Child Node (or press Ctrl+A).
3. Search for "StoryFlowComponent" in the Create New Node dialog.
4. Click Create. The component appears in your scene tree, ready to configure in the Inspector.

In GDScript

# Create and add the component in code
var storyflow := StoryFlowComponent.new()
storyflow.script_path = "npcs/elder"
add_child(storyflow)

# Or get a reference to one already in the scene tree
@onready var storyflow: StoryFlowComponent = $StoryFlowComponent

Export Properties

All configuration properties are exposed as @export variables and appear in the Inspector when you select the component. They can also be set from GDScript.

General Settings

Audio Settings

These properties control how dialogue audio is played. They appear in the Inspector under the audio section.

Signals

The component broadcasts events through typed signals. Connect to these signals from GDScript or via the editor's Node > Signals panel to react to dialogue state changes.

Connecting signals in GDScript:

@onready var storyflow: StoryFlowComponent = $StoryFlowComponent

func _ready():
    storyflow.dialogue_updated.connect(_on_dialogue_updated)
    storyflow.dialogue_started.connect(_on_dialogue_started)
    storyflow.dialogue_ended.connect(_on_dialogue_ended)

func _on_dialogue_updated(state: StoryFlowDialogueState):
    # Update your UI with the new dialogue state
    pass

func _on_dialogue_started():
    # Show your dialogue UI
    pass

func _on_dialogue_ended():
    # Hide your dialogue UI, re-enable player input
    pass

Connecting signals in the editor:

1. Select the StoryFlowComponent in the scene tree.
2. Go to the Node panel (next to Inspector) and click the Signals tab.
3. Double-click the signal you want to connect (for example, dialogue_updated).
4. Select the target node and method, then click Connect.

Control Functions

These functions control the dialogue flow. Call them from GDScript in response to player input or game logic.

Basic flow example:

@onready var storyflow: StoryFlowComponent = $StoryFlowComponent

# Player interacts with NPC
func on_interact():
    if not storyflow.is_dialogue_active():
        storyflow.start_dialogue()

# Player presses "Continue" key
func _on_continue_pressed():
    if storyflow.is_dialogue_active() and storyflow.is_waiting_for_input():
        storyflow.advance_dialogue()

# UI button calls this when the player picks an option
func _on_option_selected(option_id: String):
    storyflow.select_option(option_id)

State Access

These functions let you query the current state of the dialogue without modifying it. They are safe to call from UI update logic or any read-only context.

Variable Access

These functions let you read and write StoryFlow variables from game code. Variables are accessed by their display name as shown in the StoryFlow Editor. Each variable type has its own getter and setter pair.

Example - Checking and setting variables:

# Check if the player has completed a quest
var quest_done := storyflow.get_bool_variable("mainQuestCompleted")

# Give the player gold
var current_gold := storyflow.get_int_variable("gold")
storyflow.set_int_variable("gold", current_gold + 100)

# Set a character-specific variable
storyflow.set_character_variable(
    "characters/elder",
    "trustLevel",
    StoryFlowVariant.from_int(5)
)

# Reset all local variables to their default values
storyflow.reset_variables()

Lifecycle

The component follows a straightforward lifecycle tied to its position in the scene tree:

• _ready() - The component creates its internal execution context, text interpolator, audio controller, and node dispatch table. It does not contact the StoryFlowRuntime autoload at this stage - the manager is accessed later when you call start_dialogue().
• During Play - You call start_dialogue() to begin execution. The component walks the node graph, emits signals, and waits for player input. You can pause, resume, or stop at any time.
• _exit_tree() - The component silently resets its execution context and releases audio resources without emitting signals or accessing the manager (which may already be freed during tree teardown). Global state in the manager is not affected by a single component's removal.

# Simplified lifecycle overview (internal behavior)
func _ready():
    # Create execution context and helpers
    _context = StoryFlowExecutionContext.new()
    _text = StoryFlowTextInterpolator.new()
    _audio = StoryFlowAudioController.new()
    _build_dispatch_table()

func _exit_tree():
    # Silently clean up without emitting signals
    if _audio:
        _audio.stop()
    if _context and _context.is_executing:
        _context.reset()

Relationship with StoryFlowManager

The StoryFlowRuntime autoload (an instance of StoryFlowManager) is a singleton that lives for the entire game session. It acts as the central authority for shared state, while each StoryFlowComponent operates as an independent dialogue runner.

What the manager handles:

• Global Variables - A single global variable store shared by all components. When one component's dialogue sets a global variable, every other component sees the updated value immediately.
• Runtime Characters - Working copies of character data loaded from the project resource. Character variables modified during gameplay are shared across all components.
• Once-Only Options - Tracks which "show once" dialogue options have already been selected. This tracking persists across different components and script files within the same session.
• Project Resource - Holds the imported StoryFlow project with all scripts, characters, and resolved media assets.
• Save & Load - Provides slot-based persistence for the entire dialogue state.

What each component manages independently:

• Local Variables - Each component has its own local variable scope for the currently executing script.
• Execution State - Call stack, current node position, and flow state are per-component.
• Audio Playback - Each component manages its own audio playback independently.
• Signals - Signals are emitted per-component, so each node's UI only receives updates for its own dialogue.