API Reference

Complete reference for the StoryFlow Unity plugin API. This page covers all public classes, structs, interfaces, enums, events, and methods available in the StoryFlow.Runtime assembly.

StoryFlowManager

MonoBehaviour, Singleton - Manages shared state across all StoryFlowComponent instances. Persists across scene loads via DontDestroyOnLoad. Auto-creates itself at runtime when first accessed - no manual setup required. Automatically discovers the project asset in your project.

Properties

Methods

// Example: manager setup and save/load
var manager = StoryFlowManager.Instance;
manager.SetProject(myProjectAsset);

// Save state after dialogue completes
manager.SaveToSlot("autosave");

// Load state later (ensure no dialogue is active)
if (manager.DoesSaveExist("autosave"))
{
    manager.LoadFromSlot("autosave");
}

StoryFlowComponent

MonoBehaviour - The core runtime component that drives dialogue execution. Add it to any GameObject that needs to run StoryFlow dialogue. Decorated with [DisallowMultipleComponent].

Properties

Events

StoryFlowComponent provides both standard C# events (for code subscriptions via +=) and Inspector-assignable UnityEvent fields for the most common events.

C# Events

UnityEvents (Inspector-assignable)

Methods

// Example: subscribing to events and controlling dialogue
var storyFlow = GetComponent<StoryFlowComponent>();

storyFlow.OnDialogueStarted += () => Debug.Log("Dialogue started");
storyFlow.OnDialogueUpdated += (state) =>
{
    Debug.Log($"Speaker: {state.Character?.Name}, Text: {state.Text}");
    foreach (var option in state.Options)
        Debug.Log($"  Option: {option.Text} (id: {option.Id})");
};
storyFlow.OnDialogueEnded += () => Debug.Log("Dialogue ended");
storyFlow.OnError += (msg) => Debug.LogError($"StoryFlow error: {msg}");

// Start the dialogue
storyFlow.StartDialogue();

// Later, when the player selects an option:
storyFlow.SelectOption(selectedOptionId);

// Or advance narrative text:
storyFlow.AdvanceDialogue();

// Example: typed map access as native dictionaries
var storyFlow = GetComponent<StoryFlowComponent>();

// Read a string-keyed, int-valued map
Dictionary<string, int> stats = storyFlow.GetStringToIntMap("playerStats", global: true);
int strength = stats.TryGetValue("strength", out var s) ? s : 0;
stats["strength"] = strength + 1;

// Write the whole dictionary back (fires OnVariableChanged, re-renders dialogue)
storyFlow.SetStringToIntMap("playerStats", stats, global: true);

// Dictionary order is not guaranteed - walk keys in authoritative insertion order
foreach (string key in storyFlow.GetMapKeysInOrder("playerStats", global: true))
    Debug.Log($"{key}: {stats[key]}");

StoryFlowDialogueState

[Serializable] class - Namespace: StoryFlow.Data - Represents the current state of a dialogue node. Passed to OnDialogueUpdated listeners and returned by GetCurrentDialogue().

StoryFlowOption

StoryFlowTextBlock

StoryFlowVariable

[Serializable] class - Namespace: StoryFlow.Data - Represents a single variable in a StoryFlow project. Used for both local (script-scoped) and global variables.

StoryFlowVariant

[Serializable] class - Namespace: StoryFlow.Data - A polymorphic value container that holds a single typed value. Used as the Value field on StoryFlowVariable and for character variables.

Properties

Getters

Setters

Static Factory Methods

Other

StoryFlowMapEntry

[Serializable] class - Namespace: StoryFlow.Data - A single key/value entry in a map variable. Added in v1.2.0. Map variables store their entries as List<StoryFlowMapEntry>, preserving insertion order. Returned by StoryFlowComponent.GetMapVariable and StoryFlowVariant.GetMap.

StoryFlowCharacterData

[Serializable] class - Namespace: StoryFlow.Data - Runtime character data resolved from the imported character definitions. Contains the character's name, portrait image, and per-character variables.

Methods

StoryFlowSettings

ScriptableObject - Namespace: StoryFlow.Data - Project-wide settings for the StoryFlow plugin. Create via Assets > Create > StoryFlow > Settings and place in a Resources/ folder named StoryFlowSettings.

Static Methods

UI Classes

The plugin provides an interface and an abstract base class for building dialogue UIs. You can choose whichever approach fits your project architecture.

IStoryFlowDialogueUI

interface - Namespace: StoryFlow.UI - Implement this when your class already extends another MonoBehaviour base and cannot inherit from StoryFlowDialogueUI. You must manually subscribe to events on StoryFlowComponent.

StoryFlowDialogueUI

abstract MonoBehaviour, implements IStoryFlowDialogueUI - Namespace: StoryFlow.UI - The recommended base class for dialogue UIs. Extend this and override the virtual methods. The component automatically subscribes to events when initialized.

Lifecycle

Virtual Methods (Override These)

Convenience Methods

// Example: custom dialogue UI
using StoryFlow.Data;
using StoryFlow.UI;
using UnityEngine;
using UnityEngine.UI;

public class MyDialogueUI : StoryFlowDialogueUI
{
    [SerializeField] private Text nameText;
    [SerializeField] private Text dialogueText;
    [SerializeField] private GameObject optionsPanel;
    [SerializeField] private Button continueButton;
    [SerializeField] private GameObject panel;

    public override void OnDialogueStarted()
    {
        panel.SetActive(true);
    }

    public override void HandleDialogueUpdated(StoryFlowDialogueState state)
    {
        nameText.text = state.Character?.Name ?? "";
        dialogueText.text = state.Text;

        // Show continue button or options
        continueButton.gameObject.SetActive(state.CanAdvance);
        optionsPanel.SetActive(state.Options.Count > 0);

        // Build option buttons...
    }

    public override void OnDialogueEnded()
    {
        panel.SetActive(false);
    }
}

StoryFlowSaveHelpers

static class - Namespace: StoryFlow.Utilities - Low-level save/load utilities used internally by StoryFlowManager. Save files are stored at Application.persistentDataPath/StoryFlow/Saves/{slotName}.json.

StoryFlowNodeDispatcher

static class - Namespace: StoryFlow.Execution.NodeHandlers - The dispatch table that maps StoryFlowNodeType values to handler methods. Provides extension points for custom node types.

// Example: registering a custom node handler
StoryFlowNodeDispatcher.RegisterCustomHandler("myCustomNode",
    (component, node) =>
    {
        Debug.Log($"Custom node executed: {node.Id}");
        // Do your custom logic here, then advance to the next node:
        // component.ProcessNextNodeFromSource(node.Id);
    });

Enums

BuiltInUIStyle

Namespace: StoryFlow - Selects which built-in fallback UI is auto-created when a StoryFlowComponent has no DialogueUI assigned. Set via the UIStyle field on the component. Added in v1.1.0.

StoryFlowVariableType

Namespace: StoryFlow.Data - Defines the data types available for StoryFlow variables.

StoryFlowNodeType

Namespace: StoryFlow.Data - Defines all node types supported by the runtime. Organized into categories: