StoryFlow Component

The StoryFlow Component is the core MonoBehaviour that drives dialogue execution in your Unity project. It manages the runtime, processes node graphs, and fires events your UI can respond to.

Overview

StoryFlowComponent is a MonoBehaviour that you attach to any GameObject in your scene - an NPC, a trigger volume, a game manager, or any other object that needs to run dialogue. It is marked with [DisallowMultipleComponent], so each GameObject can have at most one instance.

Internally, the component manages a StoryFlowExecutionContext that walks the node graph, handles the call stack, processes script transitions, and produces dialogue state. You do not interact with the execution context directly. The component exposes a clean C# API for starting dialogue, selecting options, reading variables, and listening to events.

Adding the Component

There are two ways to add the component to a GameObject:

1. In the Inspector, click Add Component and search for "StoryFlow Component" (listed under StoryFlow).
2. In code, call AddComponent<StoryFlowComponent>() on any GameObject.

using StoryFlow;

// Add the component to an NPC at runtime
var storyFlow = npcObject.AddComponent<StoryFlowComponent>();
storyFlow.Script = elderScript; // assign a StoryFlowScriptAsset reference

// Or reference it from a serialized field
[SerializeField] private StoryFlowComponent storyFlowComponent;

Configuration Properties

All configuration properties are exposed in the Inspector. They are also accessible from C# scripts as public fields.

General Settings

Audio Settings

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

Events

The component provides two categories of events: C# events (Action-based, for code subscribers) and UnityEvents (Inspector-assignable, for designer workflows). Both fire at the same time.

C# Events (Action-based):

UnityEvents (Inspector-assignable):

Subscribing in C#:

using StoryFlow;
using StoryFlow.Data;

public class NPCDialogue : MonoBehaviour
{
    [SerializeField] private StoryFlowComponent storyFlow;

    private void OnEnable()
    {
        storyFlow.OnDialogueStarted += HandleDialogueStarted;
        storyFlow.OnDialogueUpdated += HandleDialogueUpdated;
        storyFlow.OnDialogueEnded += HandleDialogueEnded;
    }

    private void OnDisable()
    {
        storyFlow.OnDialogueStarted -= HandleDialogueStarted;
        storyFlow.OnDialogueUpdated -= HandleDialogueUpdated;
        storyFlow.OnDialogueEnded -= HandleDialogueEnded;
    }

    private void HandleDialogueStarted()
    {
        // Show your dialogue UI
    }

    private void HandleDialogueUpdated(StoryFlowDialogueState state)
    {
        // Update your UI with the new dialogue state
    }

    private void HandleDialogueEnded()
    {
        // Hide your dialogue UI, re-enable player input
    }
}

Control Methods

These public methods control the dialogue flow. Call them from your input handlers, UI buttons, or game logic scripts.

// Player interacts with NPC
public void OnInteract()
{
    if (!storyFlowComponent.IsDialogueActive())
    {
        storyFlowComponent.StartDialogue();
    }
}

// Player presses "Continue" key
public void OnContinuePressed()
{
    if (storyFlowComponent.IsDialogueActive()
        && storyFlowComponent.IsWaitingForInput())
    {
        storyFlowComponent.AdvanceDialogue();
    }
}

// UI button calls this when the player picks an option
public void OnOptionSelected(string optionId)
{
    storyFlowComponent.SelectOption(optionId);
}

State Access

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

Variable Access

These methods let you read and write StoryFlow variables from game code. Each variable type has its own getter and setter pair. All lookups are by display name (the name shown in the StoryFlow Editor), not by internal ID.

// Check if the player has completed a quest (global variable)
bool questDone = storyFlowComponent.GetBoolVariable("mainQuestCompleted", global: true);

// Give the player gold (local script variable)
int currentGold = storyFlowComponent.GetIntVariable("gold");
storyFlowComponent.SetIntVariable("gold", currentGold + 100);

// Set a character-specific variable
storyFlowComponent.SetCharacterVariable(
    "characters/elder",
    "trustLevel",
    StoryFlowVariant.Int(5)
);

// Reset all local variables to their default values
storyFlowComponent.ResetVariables();

Lifecycle

The component follows a straightforward lifecycle tied to Unity's MonoBehaviour callbacks:

• StartDialogue() - When you call StartDialogue(), the component retrieves a reference to StoryFlowManager.Instance, initializes its execution context with the shared state (global variables, runtime characters, once-only option tracking), and auto-binds to the DialogueUI if one is assigned. It subscribes the UI to OnDialogueStarted, OnDialogueUpdated, OnDialogueEnded, OnVariableChanged, and OnBackgroundImageChanged. It then walks the node graph, fires events, and waits for player input. You can pause, resume, or stop at any time.
• OnDisable - If a dialogue is active, it is stopped cleanly, firing OnDialogueEnded.
• OnDestroy - Stops any active dialogue and nullifies all C# event subscribers to prevent memory leaks from dangling references.

// Simplified lifecycle overview
private void OnDisable()
{
    if (isDialogueActive)
        StopDialogue();
}

private void OnDestroy()
{
    if (isDialogueActive)
        StopDialogue();

    // Clear all C# event subscribers to prevent memory leaks
    OnDialogueStarted = null;
    OnDialogueUpdated = null;
    OnDialogueEnded = null;
    OnVariableChanged = null;
    OnError = null;
    OnAudioPlayRequested = null;
    OnBackgroundImageChanged = null;
    OnScriptStarted = null;
    OnScriptEnded = null;
}

Relationship with StoryFlowManager

StoryFlowManager is a singleton MonoBehaviour that persists across scene loads via DontDestroyOnLoad. It acts as the central authority for shared state, while each StoryFlowComponent operates as an independent dialogue runner. The manager auto-creates itself at runtime when first needed - you do not need to manually add it to your scene. It automatically discovers the project asset in your project.

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 - Deep 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 (StoryFlowProjectAsset) with all scripts, characters, and resolved media assets.
• Save/Load - Provides SaveToSlot() and LoadFromSlot() methods that serialize and restore all shared 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 creates and manages its own AudioSource on demand.
• Events - C# events and UnityEvents are fired per-component, so each GameObject's UI only receives updates for its own dialogue.