API Reference

Complete API reference for DialogueCraft runtime classes, organized by category. All classes are in the DialogueCraft namespace unless noted otherwise.

Core

DialogueRunner

namespace DialogueCraft
[AddComponentMenu("CraftWorks/DialogueCraft/Dialogue Runner")]
public class DialogueRunner : MonoBehaviour

The primary runtime component that plays dialogue assets. Attach to a GameObject and assign a DialogueAsset to begin. Handles node processing, typewriter effects, variable evaluation, sub-dialogues, and voice playback.

Serialized Fields

Field	Type	Default	Description
`dialogue`	`DialogueAsset`	`null`	The dialogue asset to play.
`characterDatabase`	`CharacterDatabase`	`null`	Character database for resolving character references. Falls back to `DialogueCraftSettings.Characters`.
`autoStart`	`bool`	`false`	Start dialogue automatically on scene load.
`useTypewriter`	`bool`	`true`	Enable typewriter effect for text.
`typingSpeed`	`float`	`0.05`	Seconds per character for typewriter effect. Range: 0.01--0.2.
`useLocalization`	`bool`	`true`	Use localized text from `LocalizationManager`.

Events

Event	Type	Description
`OnDialogueStart`	`UnityEvent`	Fired when a dialogue begins.
`OnDialogueEnd`	`UnityEvent`	Fired when a dialogue ends.
`OnDialogueLine`	`DialogueLineEvent`	Fired when a text line is ready to display. Carries `DialogueLineEventArgs`.
`OnChoicesPresented`	`DialogueChoicesEvent`	Fired when choices are presented. Carries `DialogueChoicesEventArgs`.
`OnDialogueEvent`	`DialogueTriggerEvent`	Fired by Event nodes. Parameters: `(string eventName, string parameter)`.
`OnWaitingForInput`	`UnityEvent`	Fired when the runner is waiting for player input (continue or choice).
`OnVoiceStart`	`VoiceStartEvent`	Fired when voice audio starts playing. Carries `VoiceEventArgs`. For lip sync integration.
`OnVoiceEnd`	`VoiceEndEvent`	Fired when voice audio finishes. Carries `VoiceEventArgs`.

Properties

Property	Type	Description
`State`	`DialogueState`	Current state of the runner. Read-only.
`IsRunning`	`bool`	Whether a dialogue is currently running (`State != Idle`).
`IsWaitingForInput`	`bool`	Whether waiting for player input (`WaitingForContinue` or `WaitingForChoice`).
`IsPaused`	`bool`	Whether the dialogue is currently paused.
`Variables`	`VariableStore`	The current dialogue's variable store (legacy; prefer `SharedVariables`).
`CurrentSpeakerId`	`string`	Character ID of the current speaker from the active text node.
`CurrentListenerId`	`string`	Character ID of the current listener.
`SharedVariables`	`DialogueVariables`	Static. Shared variable system with global, actor, and local scopes. Access from anywhere via `DialogueRunner.SharedVariables`.

Methods

Method	Signature	Description
`StartDialogue`	`void StartDialogue()`	Starts the assigned `dialogue` field.
`StartDialogue`	`void StartDialogue(DialogueAsset asset)`	Starts a specific dialogue asset at the default entry point.
`StartDialogue`	`void StartDialogue(DialogueAsset asset, string entryPointName)`	Starts a specific dialogue asset at a named entry point. Pass `null` or `""` for default.
`Stop`	`void Stop()`	Stops the current dialogue. Fires `OnDialogueEnd`.
`Continue`	`void Continue()`	Advances to the next node when waiting for continue, skips typewriter when typing, or skips wait when waiting.
`Pause`	`void Pause()`	Pauses the dialogue runner and all audio.
`Resume`	`void Resume()`	Resumes a paused dialogue.
`SelectChoice`	`void SelectChoice(int index)`	Selects a choice by its index. Only valid when `State == WaitingForChoice`.
`SkipTypewriter`	`void SkipTypewriter()`	Immediately shows the full text, skipping the typewriter effect.
`GetVariable<T>`	`T GetVariable<T>(string name, T defaultValue = default)`	Gets a variable value from the legacy `Variables` store.
`SetVariable<T>`	`void SetVariable<T>(string name, T value)`	Sets a variable value in the legacy `Variables` store.
`SendSignal`	`void SendSignal(string signalName)`	Sends a named signal to resume a waiting Signal node. Call from game code.
`WasNodeVisited`	`bool WasNodeVisited(string nodeGuid)`	Checks if a specific node in the current dialogue has been visited (requires `DialogueCraftPersistence`).
`GetPlayCount`	`int GetPlayCount()`	Gets the number of times the current dialogue has been played.
`GetVariablesJson`	`string GetVariablesJson()`	Exports the current variable state as a JSON string for custom saving.
`LoadVariablesJson`	`void LoadVariablesJson(string json)`	Loads variable state from a JSON string.
`GetStateSnapshot`	`DialogueStateSnapshot GetStateSnapshot()`	Captures the current dialogue state for mid-dialogue saves. Returns `null` if no dialogue is running.
`RestoreFromSnapshot`	`bool RestoreFromSnapshot(DialogueStateSnapshot snapshot)`	Restores dialogue state from a snapshot. Returns `true` on success.

DialogueState Enum

public enum DialogueState
{
    Idle,               // No dialogue running
    Running,            // Processing nodes
    Typing,             // Typewriter effect in progress
    Waiting,            // Waiting for a timed delay or sequence
    WaitingForContinue, // Text displayed, awaiting player continue
    WaitingForChoice,   // Choices displayed, awaiting selection
    WaitingForVoice     // Voice audio playing, awaiting completion
}

DialogueAsset

namespace DialogueCraft
[CreateAssetMenu(fileName = "NewDialogue", menuName = "CraftWorks/DialogueCraft/Dialogue")]
public class DialogueAsset : ScriptableObject

A ScriptableObject containing a complete conversation graph. Each dialogue asset has its own graph, local variables, and cast of participants.

Serialized Fields

Field	Type	Default	Description
`dialogueId`	`string`	Asset name	Unique identifier for this dialogue. Auto-set from asset name.
`description`	`string`	`""`	Description for reference (shown in editor).
`tags`	`List<string>`	`[]`	Tags for organizing dialogues (e.g., "Chapter 1", "Tutorial").
`variables`	`List<DialogueVariable>`	`[]`	Local variables scoped to this dialogue. Override globals.
`graph`	`DialogueGraph`	Auto-created	The dialogue graph containing all nodes and connections.

Properties

Property	Type	Description
`ParticipantIds`	`IReadOnlyList<string>`	Character IDs of the dialogue's cast.
`ParticipantCount`	`int`	Number of participants in the cast.

Methods

Method	Signature	Description
`CreateVariableStore`	`VariableStore CreateVariableStore()`	Creates a new `VariableStore` seeded with global variables then local overrides.
`GetEntryNode`	`DialogueNodeData GetEntryNode()`	Gets the default entry node of this dialogue.
`GetCharacter`	`CharacterData GetCharacter(string nameOrId)`	Gets a character by name or ID from `DialogueCraftSettings.Characters`.
`GetVariable`	`DialogueVariable GetVariable(string name)`	Gets a variable definition (local first, then global).
`GetVariableWithScope`	`(DialogueVariable, VariableScope) GetVariableWithScope(string name)`	Gets a variable and its scope (local or global).
`GetVariableNames`	`string[] GetVariableNames()`	Gets all variable names (global + local combined).
`GetParticipants`	`List<CharacterData> GetParticipants()`	Gets all participant `CharacterData` objects.
`HasParticipant`	`bool HasParticipant(string characterId)`	Checks if a character is in the cast.
`AddParticipant`	`bool AddParticipant(string characterId)`	Adds a character to the cast. Returns `false` if already present or not in database.
`RemoveParticipant`	`bool RemoveParticipant(string characterId)`	Removes a character from the cast.
`ClearParticipants`	`void ClearParticipants()`	Clears all participants.

DialogueGraph

namespace DialogueCraft
[Serializable]
public class DialogueGraph

Serialized graph data for a dialogue. Contains all nodes, connections, and groups.

Fields

Field	Type	Description
`entryNodeGuid`	`string`	GUID of the default entry node.
`nodes`	`List<DialogueNodeData>`	All nodes in the graph (uses `[SerializeReference]`).
`connections`	`List<NodeConnection>`	All connections between nodes.
`groups`	`List<GroupData>`	Visual groups for organizing nodes.

Methods

Method	Signature	Description
`CreateDefault`	`static DialogueGraph CreateDefault()`	Creates a new empty graph with a default entry node.
`GetNode`	`DialogueNodeData GetNode(string guid)`	Gets a node by its GUID.
`GetEntryNode`	`DialogueNodeData GetEntryNode()`	Gets the default entry node.
`GetEntryNode`	`EntryNodeData GetEntryNode(string entryPointName)`	Gets an entry node by name. Falls back to default.
`GetEntryPointNames`	`List<string> GetEntryPointNames()`	Gets all entry point names (always includes "default").
`GetNodeByLabel`	`DialogueNodeData GetNodeByLabel(string label)`	Gets a node by its label string.
`GetAllLabels`	`List<string> GetAllLabels()`	Gets all node labels in the graph.
`GetConnectionsFrom`	`List<NodeConnection> GetConnectionsFrom(string nodeGuid)`	Gets all outgoing connections from a node.
`GetConnectionsTo`	`List<NodeConnection> GetConnectionsTo(string nodeGuid)`	Gets all incoming connections to a node.
`GetNextNode`	`DialogueNodeData GetNextNode(string nodeGuid, string portId = "output")`	Gets the node connected to a specific output port.
`GetConnectedNodes`	`List<DialogueNodeData> GetConnectedNodes(string nodeGuid)`	Gets all nodes connected to a node's outputs.
`AddNode`	`void AddNode(DialogueNodeData node)`	Adds a node to the graph. Prevents duplicates by GUID.
`RemoveNode`	`void RemoveNode(string nodeGuid)`	Removes a node and all its connections.
`AddConnection`	`void AddConnection(string fromGuid, string fromPort, string toGuid, string toPort)`	Adds a connection between two nodes.
`RemoveConnection`	`void RemoveConnection(string fromGuid, string fromPort, string toGuid, string toPort)`	Removes a specific connection.

Characters

CharacterData

namespace DialogueCraft
[Serializable]
public class CharacterData

Data for a single character stored in the CharacterDatabase. This is serializable data, not a ScriptableObject. Includes identity, typewriter voice settings (Unity + FMOD), and custom actor fields.

Fields

Field	Type	Default	Description
`id`	`string`		Unique character identifier.
`displayName`	`string`		Name shown in dialogue UI.
`nameColor`	`Color`	`Color.white`	Color for the character's name.
`portrait`	`Sprite`	`null`	Default portrait sprite.
`description`	`string`	`""`	Character description (for editor/AI context).
`tags`	`List<string>`	`[]`	Tags for grouping (e.g., "NPC", "Villain", "Party").
`fields`	`List<ActorField>`	`[]`	Custom per-character fields (e.g., Friendship, TimesVisited).
`typewriterMode`	`TypewriterMode`	`Single`	How typewriter sounds are selected.
`typewriterSound`	`AudioClip`	`null`	Sound for Single mode.
`typewriterSounds`	`AudioClip[]`	`null`	Sound pool for Random mode.
`vowelSounds`	`AudioClip[]`	`null`	Vowel sounds for VowelConsonant mode.
`consonantSounds`	`AudioClip[]`	`null`	Consonant sounds for VowelConsonant mode.
`letterSounds`	`AudioClip[26]`	`new[26]`	Per-letter sounds for PerLetter mode (index 0=a, 25=z).
`typewriterPitch`	`float`	`1.0`	Pitch multiplier. Range: 0.5--2.0.
`typewriterPitchVariation`	`float`	`0.05`	Random pitch variation. Range: 0.0--0.3.
`typewriterVolume`	`float`	`1.0`	Volume. Range: 0.0--1.0.
`typewriterFmodEventPath`	`string`	`""`	FMOD event path for Single mode.
`typewriterFmodEventPaths`	`string[]`	`null`	FMOD event paths for Random mode.
`typewriterFmodVowelPaths`	`string[]`	`null`	FMOD vowel paths for VowelConsonant mode.
`typewriterFmodConsonantPaths`	`string[]`	`null`	FMOD consonant paths for VowelConsonant mode.
`typewriterFmodLetterPaths`	`string[26]`	`new[26]`	FMOD per-letter paths for PerLetter mode.

Methods

Method	Signature	Description
`GetField`	`ActorField GetField(string fieldName)`	Gets a field definition by name.
`HasField`	`bool HasField(string fieldName)`	Checks if a field exists.
`AddField`	`ActorField AddField(string fieldName, VariableType type)`	Adds a new field.
`RemoveField`	`bool RemoveField(string fieldName)`	Removes a field by name.
`GetFieldNames`	`string[] GetFieldNames()`	Gets all field names.
`GetTagsDisplay`	`string GetTagsDisplay()`	Gets tags as a comma-separated string.
`HasTag`	`bool HasTag(string tag)`	Checks if the character has a specific tag.

TypewriterMode Enum

public enum TypewriterMode
{
    Single,         // One sound with pitch variation
    Random,         // Pick randomly from a pool
    VowelConsonant, // Different sounds for vowels vs consonants
    PerLetter       // Unique sound per letter a-z (Animal Crossing style)
}

CharacterDatabase

namespace DialogueCraft
[CreateAssetMenu(fileName = "CharacterDatabase", menuName = "CraftWorks/DialogueCraft/Character Database")]
public class CharacterDatabase : ScriptableObject

Project-wide database of all characters. One per project, referenced in DialogueCraftSettings.

Properties

Property	Type	Description
`Characters`	`IReadOnlyList<CharacterData>`	All characters in the database.

Methods

Method	Signature	Description
`GetCharacter`	`CharacterData GetCharacter(string characterId)`	Gets a character by ID.
`GetCharacterByName`	`CharacterData GetCharacterByName(string displayName)`	Gets a character by display name.
`AddCharacter`	`CharacterData AddCharacter(string displayName)`	Creates and adds a new character. Returns the new `CharacterData`.
`AddCharacter`	`void AddCharacter(CharacterData character)`	Adds a pre-configured character. Auto-generates ID if empty.
`RemoveCharacter`	`bool RemoveCharacter(string characterId)`	Removes a character by ID.
`ResolveCharacter`	`CharacterData ResolveCharacter(string nameOrId)`	Resolves a name or ID. Tries exact ID, then case-insensitive name with underscores treated as spaces.
`IndexOf`	`int IndexOf(CharacterData character)`	Gets the index of a character.

ActorField

namespace DialogueCraft
[Serializable]
public class ActorField

Defines a custom field on a character/actor. Fields persist across dialogues and are accessible via {Actor.CharacterID.FieldName} in text or DialogueRunner.SharedVariables.Actor("id").GetValue<T>("field") in code.

Fields

Field	Type	Default	Description
`name`	`string`		Field name (e.g., "Friendship", "TimesVisited").
`description`	`string`	`""`	Description of what this field tracks.
`type`	`VariableType`	`Int`	Field data type.
`intValue`	`int`	`0`	Default integer value.
`floatValue`	`float`	`0f`	Default float value.
`boolValue`	`bool`	`false`	Default boolean value.
`stringValue`	`string`	`""`	Default string value.

Methods

Method	Signature	Description
`GetDefaultValue`	`object GetDefaultValue()`	Returns the default value as a boxed object based on `type`.
`GetDefaultValueString`	`string GetDefaultValueString()`	Returns the default value formatted for display.
`GetTypeLabel`	`string GetTypeLabel()`	Returns the short type label ("int", "float", "bool", "string").

Variables

For the full DialogueVariables, VariableStore, and event types API, see the source content which continues with detailed documentation of all variable classes, persistence classes (DialogueCraftPersistence, DialogueCraftSaveData), localization classes (LocalizationManager), audio interfaces (IDialogueAudioProvider, AudioProviderManager, DialogueAudioManager), AI classes (DialogueCraftAI), UI classes (IDialogueUI, DialogueUIBase), interaction classes (DialogueTrigger, DialogueInteractable), bark classes (Barker, BarkData), and common enums.

Please refer to the individual guide pages for usage details:

Variables & Conditions -- Runtime variable API
Save & Load -- Persistence API
Localization -- Localization API
Audio -- Audio provider API
AI Features -- AI translation API
UI Customization -- UI interface API
Triggers & Interaction -- Interaction and event API
Barks -- Bark system API
Characters & Actors -- Character and actor API

Common Enums

public enum VariableType { String, Int, Float, Bool }

public enum VariableScope { Global, Actor, Local }

public enum VariableOperation { Set, Add, Subtract, Multiply, Divide, Toggle, Append }

public enum AudioSourceType { Unity, FMOD }

public enum AudioChannel { Music, Ambient, Voice, SFX }

public enum LocalizationProviderType { BuiltIn, LocalizeCraft, UnityLocalization }

Core​

DialogueRunner​

Serialized Fields​

Events​

Properties​

Methods​

DialogueState Enum​

DialogueAsset​

Serialized Fields​

Properties​

Methods​

DialogueGraph​

Fields​

Methods​

Characters​

CharacterData​

Fields​

Methods​

TypewriterMode Enum​

CharacterDatabase​

Properties​

Methods​

ActorField​

Fields​

Methods​

Variables​

Common Enums​

Core

DialogueRunner

Serialized Fields

Events

Properties

Methods

DialogueState Enum

DialogueAsset

Serialized Fields

Properties

Methods

DialogueGraph

Fields

Methods

Characters

CharacterData

Fields

Methods

TypewriterMode Enum

CharacterDatabase

Properties

Methods

ActorField

Fields

Methods

Variables

Common Enums