StoryFlow Component

The StoryFlow Component is the core actor component that drives dialogue execution in your Unreal Engine project. It manages the runtime, processes node graphs, and broadcasts events your UI can respond to.

Overview

UStoryFlowComponent is a UActorComponent declared with UCLASS(BlueprintType, ClassGroup=(StoryFlow), meta=(BlueprintSpawnableComponent)). This means you can add it to any actor in your level — an NPC, a trigger volume, a game mode, or any other actor that needs to run dialogue.

Internally, the component manages two key objects:

• FStoryFlowExecutionContext — The execution engine that walks the node graph, manages the call stack, handles script transitions, and produces dialogue state.
• FStoryFlowEvaluator — The expression evaluator that resolves variable chains, boolean logic, arithmetic, string operations, and type conversions during execution.

You do not interact with these objects directly. The component exposes a clean Blueprint API for starting dialogue, selecting options, reading variables, and listening to events.

Adding the Component

In Blueprint

1. Open the actor Blueprint that should run dialogue (for example, your NPC actor).
2. In the Components panel, click Add and search for "StoryFlow".
3. Select StoryFlow Component from the list.
4. The component appears in your component hierarchy, ready to configure in the Details panel.

In C++

// In your actor's header
UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "StoryFlow")
UStoryFlowComponent* StoryFlowComponent;

// In your actor's constructor
AMyNPC::AMyNPC()
{
    StoryFlowComponent = CreateDefaultSubobject<UStoryFlowComponent>(
        TEXT("StoryFlowComponent")
    );
}

Configuration Properties

All configuration properties are exposed in the Details panel when you select the component. They are also available in C++ and Blueprints via EditAnywhere and BlueprintReadWrite.

General Settings

Audio Settings

These properties control how dialogue audio is played. They appear under the StoryFlow | Audio category in the Details panel.

Events and Delegates

The component broadcasts events through BlueprintAssignable multicast delegates under the StoryFlow | Events category. Bind to these in Blueprint (using Event Dispatchers) or in C++ to react to dialogue state changes.

Binding in Blueprint:

1. Select the StoryFlow Component in your actor's Blueprint.
2. In the Details panel, scroll to the Events section.
3. Click the + button next to the event you want to bind (for example, OnDialogueUpdated).
4. A new event node is created in your Event Graph, ready for you to add logic.

Binding in C++:

// In BeginPlay or wherever you set up your component
StoryFlowComponent->OnDialogueUpdated.AddDynamic(
    this, &AMyNPC::HandleDialogueUpdated
);
StoryFlowComponent->OnDialogueEnded.AddDynamic(
    this, &AMyNPC::HandleDialogueEnded
);

// Handler signatures
void AMyNPC::HandleDialogueUpdated(const FStoryFlowDialogueState& DialogueState)
{
    // Update your UI with the new dialogue state
}

void AMyNPC::HandleDialogueEnded()
{
    // Clean up UI, re-enable player input
}

Control Functions

These BlueprintCallable functions control the dialogue flow. Call them from Blueprint event graphs, player input handlers, or C++ game logic.

Basic Blueprint flow example:

// Player interacts with NPC
void AMyNPC::OnInteract(APlayerCharacter* Player)
{
    if (!StoryFlowComponent->IsDialogueActive())
    {
        StoryFlowComponent->StartDialogue();
    }
}

// Player presses "Continue" key
void AMyNPC::OnContinuePressed()
{
    if (StoryFlowComponent->IsDialogueActive()
        && !StoryFlowComponent->IsWaitingForInput())
    {
        StoryFlowComponent->AdvanceDialogue();
    }
}

// UI button calls this when the player picks an option
void AMyNPC::OnOptionSelected(const FString& OptionId)
{
    StoryFlowComponent->SelectOption(OptionId);
}

State Access

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

Variable Access

These BlueprintCallable functions (under the StoryFlow | Variables category) let you read and write StoryFlow variables from game code. Each variable type has its own getter and setter pair.

Example — Checking and setting variables:

// Check if the player has completed a quest (global variable)
bool bQuestDone = StoryFlowComponent->GetBoolVariable(
    TEXT("mainQuestCompleted"), true  // bGlobal = true
);

// Give the player gold (local script variable)
int32 CurrentGold = StoryFlowComponent->GetIntVariable(TEXT("gold"));
StoryFlowComponent->SetIntVariable(TEXT("gold"), CurrentGold + 100);

// Set a character-specific variable
StoryFlowComponent->SetCharacterVariable(
    TEXT("characters/elder"),
    TEXT("trustLevel"),
    FStoryFlowVariant::FromInt(5)
);

// Reset all local variables to their default values
StoryFlowComponent->ResetVariables();

Lifecycle

The component follows a straightforward lifecycle tied to its owning actor:

• BeginPlay — The component retrieves a reference to the UStoryFlowSubsystem from the game instance. It then initializes its internal FStoryFlowExecutionContext with the subsystem's shared state (global variables, runtime character copies, and once-only option tracking). After initialization, the component is ready to start dialogue.
• During Play — You call StartDialogue to begin execution. The component walks the node graph, fires events, and waits for player input. You can pause, resume, or stop at any time.
• EndPlay — The component stops any active dialogue, releases its audio components, and cleans up the execution context. Global state in the subsystem is not affected by a single component's destruction.

// Simplified lifecycle overview
void UStoryFlowComponent::BeginPlay()
{
    Super::BeginPlay();

    // Get the subsystem from the game instance
    Subsystem = GetOwner()->GetGameInstance()
        ->GetSubsystem<UStoryFlowSubsystem>();

    // Initialize execution context with shared state
    ExecutionContext.Initialize(
        Subsystem->GetGlobalVariables(),
        Subsystem->GetRuntimeCharacters(),
        Subsystem->GetOnceOnlyTracker()
    );
}

void UStoryFlowComponent::EndPlay(const EEndPlayReason::Type EndPlayReason)
{
    if (IsDialogueActive())
    {
        StopDialogue();
    }

    ExecutionContext.Cleanup();
    Super::EndPlay(EndPlayReason);
}

Relationship with UStoryFlowSubsystem

The UStoryFlowSubsystem is a GameInstanceSubsystem that lives for the entire game session. It acts as the central authority for shared state, while each UStoryFlowComponent operates as an independent dialogue runner.

What the subsystem manages:

• 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 asset. 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 Asset — Holds the imported StoryFlow project (UStoryFlowProject) with all scripts, characters, and resolved media assets.

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 spawns and manages its own audio components.
• Delegates — Events are fired per-component, so each actor's UI only receives updates for its own dialogue.