StoryGraph

Overview

StoryGraph is a node-based dialogue and narrative system for Unreal Engine 5. Stories are authored as visual graphs in a dedicated asset editor, designers connect Dialogue, Choice, Condition, Event, and Jump nodes to build branching conversations without writing code. At runtime, a single UStoryGraphComponent drives playback through a delegate-based API: your UI binds to events, advances through lines, and presents choices, StoryGraph handles traversal state.

The runtime graph is compiled from the editor graph at save time and stored in a UStoryGraphAsset. Each PlayStory() call clones the compiled data so multiple components can run the same asset simultaneously without sharing state. Speaker metadata, portrait, voice, and name color, lives in reusable UStoryGraphSpeakerDataAsset data assets loaded on demand.

Getting Started

A story running on an NPC is up in five steps. No C++ is required beyond adding the module dependency if you're using Blueprints.

// In your NPC .h
UPROPERTY(VisibleAnywhere)
TObjectPtr<UStoryGraphComponent> StoryComp;

UFUNCTION()
void OnDialogueLine(const FText& DialogueText, const FString& SpeakerName);

UFUNCTION()
void OnStoryComplete();

// In BeginPlay
StoryComp->OnDialogueLine.AddDynamic(this, &AMyNPC::OnDialogueLine);
StoryComp->OnStoryComplete.AddDynamic(this, &AMyNPC::OnStoryComplete);

// When the player interacts with the NPC
StoryComp->PlayStory(StoryAsset);

Story Graph Asset

UStoryGraphAsset is the top-level data asset for a story. It stores the visual editor graph (EditorGraph) and the compiled runtime data (RuntimeGraph). The runtime graph is compiled from the editor graph each time you save the asset, you never author RuntimeGraph directly. Assign a UStoryGraphAsset reference to any actor that needs to play it, then pass it to UStoryGraphComponent::PlayStory().

Node Types

StoryGraph provides five node types that cover all branching dialogue patterns. Every node inherits from UStoryGraphNode, which exposes a NodeLabel property, an optional name used by Jump nodes to locate their target at compile time.

Speaker Data Asset

UStoryGraphSpeakerDataAsset defines a character that speaks in a story graph. Create one asset per NPC or player character and assign it to Dialogue nodes in the graph editor. All media properties use soft references, portrait textures and voice audio are only loaded into memory when that speaker is actively displayed.

Retrieve the current speaker asset during playback via UStoryGraphComponent::GetCurrentSpeakerAsset(). The returned soft reference can be async-loaded to access portrait and voice without blocking the game thread.

Story Graph Component

UStoryGraphComponent is the primary runtime interface. Add it to any actor, an NPC, player controller, or trigger volume. It wraps UStoryGraphRuntime, clones the compiled graph on each PlayStory() call, and routes runtime events to its own delegates. Bind your UI and game logic to these delegates in BeginPlay; then control playback with the four core functions.

Delegates

All runtime events are surfaced as BlueprintAssignable dynamic multicast delegates on UStoryGraphComponent. Bind them in BeginPlay, Blueprint or C++, and react to the events your UI and game logic need. The graph waits at Dialogue and Choice nodes until your code calls AdvanceToNextNode() or SelectChoice(); Event and Jump nodes advance automatically.

Condition Handling

Condition nodes bridge the story graph and your game state. The graph fires OnConditionRequested with a named condition, halts, and waits. Your handler reads game state for that condition name and calls SelectChoice to branch. This keeps condition logic in your game code, the graph itself has no knowledge of quests, inventory, or game variables.

// In your NPC header
UFUNCTION()
void HandleCondition(FName ConditionName);

// In BeginPlay
StoryComp->OnConditionRequested.AddDynamic(this, &AMyNPC::HandleCondition);

// Handler, evaluate and branch
void AMyNPC::HandleCondition(FName ConditionName)
{
    bool bResult = false;

    if (ConditionName == "HasKey")
    {
        bResult = PlayerInventory->HasItem(KeyItemDefinition);
    }
    else if (ConditionName == "QuestComplete")
    {
        bResult = QuestManager->IsComplete(FName("MainQuest"));
    }

    // 0 = True branch, 1 = False branch
    StoryComp->SelectChoice(bResult ? 0 : 1);
}