Yarn Spinner for Unity

https://github.com/yarnspinnertool/yarnspinner-unity
Admin
Yarn Spinner for Unity is a dialogue system that allows writers to create interactive conversations...
Tokens:63,889
Snippets:427
Trust Score:9.2
License:MIT
Update:2 days ago
Show doc for...
Tokens:
Raw
### StartDialogue usage examples

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/dialogue-runner.md

Examples showing how to start a dialogue node and how to use a per-frame guard to prevent starting if dialogue is already running.

```csharp
await dialogueRunner.StartDialogue("ShopkeeperIntro");

// or, per-frame guard:
if (!dialogueRunner.IsDialogueRunning)
{
    await dialogueRunner.StartDialogue("Start");
}
```

--------------------------------

### Action registration usage examples

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/dialogue-runner.md

Examples showing how to add and remove command handlers and register functions.

```csharp
// instance methods on a MonoBehaviour:
dialogueRunner.AddCommandHandler("start_fight", () => StartFight());
dialogueRunner.AddFunction<int, int>("square", (x) => x * x);
dialogueRunner.RemoveCommandHandler("start_fight");
```

--------------------------------

### InMemoryVariableStorage usage example

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/variable-storage.md

Shows how to add an InMemoryVariableStorage component, assign the program for initial values and change listeners, set and get a variable, and enumerate stored variables.

```csharp
var storage = gameObject.AddComponent<InMemoryVariableStorage>();
storage.Program = project.Program;          // needed for initial values & change listeners

storage.SetValue("$lives", 3f);
if (storage.TryGetValue<float>("$lives", out var lives))
{
    Debug.Log($"Lives: {lives}");
}

// Enumerate stored variables
foreach (var kvp in storage)
{
    Debug.Log($"{kvp.Key} = {kvp.Value}");
}
```

--------------------------------

### SetProject usage examples

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/dialogue-runner.md

Examples showing how to set a new project and how to guard against InvalidOperationException if the dialogue is already running.

```csharp
// Set a new project between dialogues (throws if dialogue is running):
dialogueRunner.SetProject(myProject);
await dialogueRunner.StartDialogue("Start");

// Guard against the InvalidOperationException:
if (dialogueRunner.IsDialogueRunning)
{
    await dialogueRunner.Stop();
}
dialogueRunner.SetProject(myProject);
```

--------------------------------

### RequestNextLine usage example

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/dialogue-runner.md

Example showing how to trigger the next line using user input.

```csharp
if (Input.GetKeyDown(KeyCode.Space)) { dialogueRunner.RequestNextLine(); }
```

--------------------------------

### Custom Markup Processor and Pre-loading Example

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/line-providers.md

Example of registering a custom markup processor on the built-in line provider and pre-loading voice-over audio for upcoming lines.

```APIDOC
## Custom Markup Processor and Pre-loading Example

### Description
Example of registering a custom markup processor on the built-in line provider and pre-loading voice-over audio for upcoming lines.

### Code
```csharp
// Advanced: register a custom markup processor on the built-in provider
var provider = runner.LineProvider as BuiltinLocalisedLineProvider;
provider?.RegisterMarkerProcessor("shake", new ShakeMarkerProcessor());

// Pre-load voice-over audio for upcoming lines:
await provider.PrepareForLinesAsync(project.GetLineIDsForNodes(new[] { "NodeA", "NodeB" }), CancellationToken.None);
```
```

--------------------------------

### Stop usage example

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/dialogue-runner.md

Example showing how to perform a hard-stop on the dialogue.

```csharp
await dialogueRunner.Stop(); // hard-stop; cancels the current line too
```

--------------------------------

### YarnTask Usage Examples

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/yarn-task.md

Examples of mixing backends, waiting with cancellation, fire-and-forget, parallel execution, and converting to coroutines.

```APIDOC
## YarnTask Usage Examples

### Description
Examples of mixing backends, waiting with cancellation, fire-and-forget, parallel execution, and converting to coroutines.

### Mixing backends
public async YarnTask SaveGameAsync()
{
    await Task.Run(() => WriteSaveFile());
    await YarnTask.Delay(TimeSpan.FromSeconds(0.5f));
}

### Wait until a flag, with cancellation and no-throw semantics
var wasCancelled = await YarnTask.WaitUntil(() => foo == 3, token).SuppressCancellationThrow();

### Fire-and-forget with safe exception logging
SomeAsync().Forget();

### Run several presenters in parallel
await YarnTask.WhenAll(taskA, taskB, taskC);

### YarnTasks in coroutines
IEnumerator Co() => YarnTask.ToCoroutine(() => SomeAsync());
```

--------------------------------

### Custom Line Provider Example

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/line-providers.md

Example of creating a custom line provider that uses an external translation service, and wiring it to the DialogueRunner at runtime.

```APIDOC
## Custom Line Provider Example

### Description
Example of creating a custom line provider that uses an external translation service, and wiring it to the DialogueRunner at runtime.

### Code
```csharp
// Custom line provider with an external translation source:
public class TranslationServiceLineProvider : LineProviderBehaviour
{
    public override string LocaleCode { get; set; } = "en";

    public override YarnTask<LocalizedLine> GetLocalizedLineAsync(Line line, CancellationToken cancellationToken)
    {
        var text = MyTranslationService.Translate(line.ID, line.Substitutions);
        var result = new LocalizedLine
        {
            TextID = line.ID,
            RawText = text,
            Text = new MarkupParseResult(text, new List<MarkupAttribute>()),
        };
        return YarnTask.FromResult(result);
    }

    public override void RegisterMarkerProcessor(string attributeName, IAttributeMarkerProcessor markerProcessor) { }
    public override void DeregisterMarkerProcessor(string attributeName) { }
}

// Wiring at runtime:
runner.LineProvider = gameObject.AddComponent<TranslationServiceLineProvider>();
```
```

--------------------------------

### SplitCommandText Usage Example

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/dialogue-runner.md

Demonstrates splitting a command string into parts, correctly handling the quoted 'hello world' segment.

```csharp
foreach (var part in DialogueRunner.SplitCommandText("say \"hello world\""))
{
    Debug.Log(part); // "say", "hello world"
}
```

--------------------------------

### StartDialogue method signature

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/dialogue-runner.md

The method signature for starting a dialogue node.

```csharp
public async YarnTask StartDialogue(string nodeName)
```

--------------------------------

### Action Registration Template

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/editor-tools.md

Example of the partial class structure generated by the analyser for action registration.

```csharp
// From the analyser's generated registration output (emitted into the project):
// public partial class ActionRegistration { public static void RegisterActions(IActionRegistration r, RegistrationType t) { ... } }
```

--------------------------------

### UnityLocalisedLineProvider (not installed)

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/line-providers.md

The UnityLocalisedLineProvider class when Unity Localization is not installed. It provides placeholder behavior and logs errors instructing the user to install the Unity Localization package.

```APIDOC
## UnityLocalisedLineProvider (not installed)

### Description
Placeholder implementation used when Unity Localization is not installed. All functional members log an error instructing the user to install the Unity Localization package.

### Class Declaration
```csharp
public partial class UnityLocalisedLineProvider : LineProviderBehaviour { }
```

### Members

#### PlaceholderTableReference
- **Type**: [System.Serializable] public struct
- **Description**: Mirrors the TableReference shape to preserve serialized table references when Unity Localization is installed later.

#### LocaleCode
- **Type**: string (get/set)
- **Description**: Getter returns "error". Setter does nothing.

#### PrepareForLinesAsync(...)
- **Description**: Logs NotInstalledError.

#### Start()
- **Description**: Logs NotInstalledError.

#### GetLocalizedLineAsync(...)
- **Description**: Logs error and returns a placeholder line.

#### RegisterMarkerProcessor(...)
- **Description**: Logs warning.

#### DeregisterMarkerProcessor(...)
- **Description**: Logs warning.
```

--------------------------------

### StartDialogue(string nodeName)

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/dialogue-runner.md

Starts running the node named nodeName. Validates project and program, sets up cancellation, applies saliency, invokes onDialogueStart, awaits presenters, then calls Dialogue.Continue().

```APIDOC
## StartDialogue(string nodeName)

### Description
Starts running the node named nodeName. Validates that yarnProject and yarnProject.Program are present, creates the dialogue cancellation source (linked to destroyCancellationToken), sets the program and node, applies the configured saliency strategy, invokes onDialogueStart, awaits every presenter's OnDialogueStartedAsync(), then calls Dialogue.Continue().

### Method
StartDialogue

### Parameters
#### Path Parameters
- **nodeName** (string) - Required - Name of a node in YarnProject.

### Return
YarnTask - completes after presenters finish their start-up work (the dialogue itself continues asynchronously via the VM's completion source).

### Errors
Logs Debug.LogError (does not throw) when no Yarn Project is configured or when the program is null (e.g. compile errors).

### Request Example
```csharp
await dialogueRunner.StartDialogue("ShopkeeperIntro");

// or, per-frame guard:
if (!dialogueRunner.IsDialogueRunning)
{
    await dialogueRunner.StartDialogue("Start");
}
```
```

--------------------------------

### UnityLocalisedLineProvider (installed)

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/line-providers.md

The UnityLocalisedLineProvider class when Unity Localization is installed. It overrides LineProviderBehaviour methods to provide localized lines, manage locale, and handle marker processors.

```APIDOC
## UnityLocalisedLineProvider (installed)

### Description
Provides localized lines using Unity Localization. This is the implementation used when the USE_UNITY_LOCALIZATION define is set.

### Class Declaration
```csharp
public sealed partial class UnityLocalisedLineProvider : LineProviderBehaviour { }
```

### Members

#### LocaleCode
- **Type**: string (get/set)
- **Description**: Gets the current locale code from LocalizationSettings.SelectedLocale.Identifier.Code. Setting resolves the locale via LocalizationSettings.AvailableLocales.GetLocale(value) and throws InvalidOperationException if the locale is not configured.

#### GetLocalizedLineAsync(Line line, CancellationToken cancellationToken)
- **Returns**: YarnTask<LocalizedLine>
- **Description**: Retrieves a localized line for the given line. Throws InvalidOperationException if stringsTable is null or empty. Queries LocalizationSettings.StringDatabase.GetTableEntryAsync with FallbackBehavior.UseFallback, reads LineMetadata, resolves shadow: lines, parses markup, and fetches an asset from assetTable when set.

#### RegisterMarkerProcessor(string attributeName, IAttributeMarkerProcessor markerProcessor)
- **Description**: Registers a marker processor for the specified attribute.

#### DeregisterMarkerProcessor(string attributeName)
- **Description**: Deregisters a marker processor for the specified attribute.

#### PrepareForLinesAsync(IEnumerable<string> lineIDs, CancellationToken cancellationToken)
- **Returns**: YarnTask
- **Description**: No-op. Use Unity Localization's preload support instead.

### LineMetadata Class
- **Namespace**: Yarn.Unity.UnityLocalization
- **Declaration**: [System.Serializable] public class LineMetadata : IMetadata
- **Fields**:
  - string nodeName = ""
  - string[] tags = ...
  - string? ShadowLineSource (computed)
- **Description**: Unity-Localization metadata stored per string-table entry. A tag beginning with shadow: makes the line use another line's text.
```

--------------------------------

### SaveStateToPersistentStorage Usage Example

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/dialogue-runner.md

Demonstrates how to save current variables to a file named 'save1.json'.

```csharp
if (dialogueRunner.SaveStateToPersistentStorage("save1.json"))
{
    Debug.Log("Save written.");
}
```

--------------------------------

### FadeAlphaAsync Usage Example

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/markup-and-effects.md

Example of calling FadeAlphaAsync to lerp a CanvasGroup alpha from 0 to 1 over 0.25 seconds.

```csharp
await Effects.FadeAlphaAsync(canvasGroup, 0f, 1f, 0.25f, CancellationToken.None);
```

--------------------------------

### LoadStateFromPersistentStorage Usage Example

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/dialogue-runner.md

Demonstrates how to load variables from a file named 'save1.json' and handle success or failure.

```csharp
if (dialogueRunner.LoadStateFromPersistentStorage("save1.json"))
{
    Debug.Log("Loaded variables.");
}
else
{
    Debug.LogWarning("No save file, starting fresh.");
}
```

--------------------------------

### Observing Variable Changes

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/variable-storage.md

Example of registering per-variable and global change listeners, and disposing of them to unsubscribe.

```csharp
// Observe a variable from user code:
using var sub = storage.AddChangeListener<int>("$score", newValue => scoreText.text = newValue.ToString());
using var globalSub = storage.AddChangeListener((name, value) => Debug.Log($"{name} = {value}"));

// ...later, dispose to unsubscribe
sub.Dispose();
```

--------------------------------

### Custom LineProviderBehaviour implementation

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/line-providers.md

Example of creating a custom line provider that integrates with an external translation service and wiring it to a DialogueRunner at runtime.

```csharp
// Custom line provider with an external translation source:
public class TranslationServiceLineProvider : LineProviderBehaviour
{
    public override string LocaleCode { get; set; } = "en";

    public override YarnTask<LocalizedLine> GetLocalizedLineAsync(Line line, CancellationToken cancellationToken)
    {
        var text = MyTranslationService.Translate(line.ID, line.Substitutions);
        var result = new LocalizedLine
        {
            TextID = line.ID,
            RawText = text,
            Text = new MarkupParseResult(text, new List<MarkupAttribute>()),
        };
        return YarnTask.FromResult(result);
    }

    public override void RegisterMarkerProcessor(string attributeName, IAttributeMarkerProcessor markerProcessor) { }
    public override void DeregisterMarkerProcessor(string attributeName) { }
}

// Wiring at runtime:
runner.LineProvider = gameObject.AddComponent<TranslationServiceLineProvider>();
```

--------------------------------

### CreateDialogueRunnerMenuItem.CreateDialogueRunner

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/errors.md

Creates a DialogueRunner. Throws InvalidOperationException if the Dialogue System prefab cannot be found by GUID.

```APIDOC
## CreateDialogueRunnerMenuItem.CreateDialogueRunner

### Description
Creates a DialogueRunner. Throws InvalidOperationException if the Dialogue System prefab cannot be found by GUID.

### Method
CreateDialogueRunner

### Endpoint
CreateDialogueRunnerMenuItem.CreateDialogueRunner

### Exceptions
- **InvalidOperationException** - Thrown when the Dialogue System prefab cannot be found by GUID.
```

--------------------------------

### Custom DialoguePresenter implementation

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/dialogue-presenters.md

An example of a custom presenter subclassing DialoguePresenterBase to handle dialogue lifecycle events.

```csharp
public class MyPresenter : DialoguePresenterBase
{
    public override YarnTask RunLineAsync(LocalizedLine line, LineCancellationToken token)
    {
        // show text, await input, then return
        return YarnTask.CompletedTask;
    }
    public override YarnTask OnDialogueStartedAsync() => YarnTask.CompletedTask;
    public override YarnTask OnDialogueCompleteAsync() => YarnTask.CompletedTask;
}
```

--------------------------------

### UnityLocalisedLineProvider.LocaleCode setter (installed build)

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/errors.md

Sets the locale code. Throws InvalidOperationException if the locale is not configured in LocalizationSettings.AvailableLocales.

```APIDOC
## UnityLocalisedLineProvider.LocaleCode setter (installed build)

### Description
Sets the locale code. Throws InvalidOperationException if the locale is not configured in LocalizationSettings.AvailableLocales.

### Method
Setter

### Endpoint
UnityLocalisedLineProvider.LocaleCode

### Exceptions
- **InvalidOperationException** - Thrown when setting a locale that is not configured. Message: "Can't set locale to {value}: no such locale has been configured".
```

--------------------------------

### UnityLocalisedLineProvider implementation without Unity Localization

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/line-providers.md

The class definition when Unity Localization is not installed, providing placeholder functionality and error logging.

```csharp
public partial class UnityLocalisedLineProvider : LineProviderBehaviour
{
    [System.Serializable] public struct PlaceholderTableReference { /* mirrors TableReference shape */ }
    public override string LocaleCode { get => "error"; set { } }
    public override YarnTask PrepareForLinesAsync(...);  // logs NotInstalledError
    public override void Start();                        // logs NotInstalledError
    public override YarnTask<LocalizedLine> GetLocalizedLineAsync(...); // logs error, returns placeholder line
    public override void RegisterMarkerProcessor(...);   // logs warning
    public override void DeregisterMarkerProcessor(...); // logs warning
}
```

--------------------------------

### UnityLocalisedLineProvider.GetLocalizedLineAsync (installed build)

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/errors.md

Gets a localized line asynchronously. Throws InvalidOperationException if the stringsTable is null or empty for the line being fetched.

```APIDOC
## UnityLocalisedLineProvider.GetLocalizedLineAsync (installed build)

### Description
Gets a localized line asynchronously. Throws InvalidOperationException if the stringsTable is null or empty for the line being fetched.

### Method
GetLocalizedLineAsync

### Endpoint
UnityLocalisedLineProvider.GetLocalizedLineAsync

### Exceptions
- **InvalidOperationException** - Thrown when stringsTable is null or empty for the line being fetched.
```

--------------------------------

### Configuring DialoguePresenters and Custom Presenter Implementation

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/dialogue-presenters.md

Demonstrates how to assign presenters to the DialogueRunner and how to create a custom presenter that automatically selects the first available option.

```csharp
// Presenters are components; wire them up to a runner:
// 1. Add LinePresenter, OptionsPresenter, VoiceOverPresenter to GameObjects in the scene
// 2. Assign them to runner.DialoguePresenters (inspector list)

runner.DialoguePresenters = new List<DialoguePresenterBase?> { linePresenter, optionsPresenter, voiceOver };

// Custom presenter that auto-selects the first available option:
public class AutoPickPresenter : DialoguePresenterBase
{
    public override YarnTask RunLineAsync(LocalizedLine line, LineCancellationToken token) => YarnTask.CompletedTask;
    public override YarnTask OnDialogueStartedAsync() => YarnTask.CompletedTask;
    public override YarnTask OnDialogueCompleteAsync() => YarnTask.CompletedTask;
    public override YarnTask<DialogueOption?> RunOptionsAsync(DialogueOption[] options, LineCancellationToken token)
    {
        foreach (var option in options) { if (option.IsAvailable) return YarnTask.FromResult<DialogueOption?>(option); }
        return DialogueRunner.NoOptionSelected;
    }
}
```

--------------------------------

### Advanced BuiltinLocalisedLineProvider usage

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/line-providers.md

Demonstrates registering a custom markup processor and pre-loading voice-over audio assets using the built-in provider.

```csharp
// Advanced: register a custom markup processor on the built-in provider
var provider = runner.LineProvider as BuiltinLocalisedLineProvider;
provider?.RegisterMarkerProcessor("shake", new ShakeMarkerProcessor());

// Pre-load voice-over audio for upcoming lines:
await provider.PrepareForLinesAsync(project.GetLineIDsForNodes(new[] { "NodeA", "NodeB" }), CancellationToken.None);
```

--------------------------------

### PrepareBuild class

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/editor-tools.md

Ensures Yarn action source code is generated or up to date before player builds.

```csharp
class PrepareBuild : UnityEditor.Build.BuildPlayerProcessor
{
    public override void PrepareForBuild(UnityEditor.Build.BuildPlayerContext buildPlayerContext);
    // also: callback ordering + a build clean-up callback
}
```

--------------------------------

### InMemoryVariableStorage.ValidateVariableName

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/errors.md

Validates a variable name. Throws ArgumentException if the variable name does not start with '$'.

```APIDOC
## InMemoryVariableStorage.ValidateVariableName

### Description
Validates a variable name. Throws ArgumentException if the variable name does not start with '$'.

### Method
ValidateVariableName

### Endpoint
InMemoryVariableStorage.ValidateVariableName

### Exceptions
- **ArgumentException** - Thrown when the variable name does not start with '$'. Message: "{name} is not a valid variable name: Variable names must start with a '$'. (Did you mean to use '${name}'?)"
```

--------------------------------

### Cultures.GetCulture

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/errors.md

Gets a culture by name. Throws ArgumentException if the culture name is not found.

```APIDOC
## Cultures.GetCulture

### Description
Gets a culture by name. Throws ArgumentException if the culture name is not found.

### Method
GetCulture

### Endpoint
Cultures.GetCulture

### Exceptions
- **ArgumentException** - Thrown when the culture name is not found. Message: "Culture {name} not found".
```

--------------------------------

### Manual task completion with YarnTaskCompletionSource

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/yarn-task.md

Demonstrates how to manually create, complete, and await a YarnTask using YarnTaskCompletionSource.

```csharp
var tcs = new YarnTaskCompletionSource();       // or YarnTaskCompletionSource<int>
tcs.TrySetResult();                             // or TrySetResult(42)
tcs.TrySetException(new Exception("boom"));
tcs.TrySetCanceled();
await tcs.Task;                                 // YarnTask / YarnTask<int>
```

--------------------------------

### YarnProject.GetHeaders

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/errors.md

Gets headers from the YarnProject. Always throws InvalidOperationException because the member is obsolete.

```APIDOC
## YarnProject.GetHeaders

### Description
Gets headers from the YarnProject. Always throws InvalidOperationException because the member is obsolete.

### Method
GetHeaders

### Endpoint
YarnProject.GetHeaders

### Exceptions
- **InvalidOperationException** - Always thrown (member is [Obsolete], error: true).
```

--------------------------------

### WaitForAsyncOperation usage

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/yarn-task.md

Example of awaiting an Addressables async operation within a YarnTask context.

```csharp
var entry = await YarnTask.WaitForAsyncOperation(
    LocalizationSettings.StringDatabase.GetTableEntryAsync(...), cancellationToken);
```

--------------------------------

### CreateDialogueRunnerMenuItem class

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/editor-tools.md

Instantiates the bundled 'Dialogue System' prefab into the active scene and returns its DialogueRunner. Throws InvalidOperationException if the prefab cannot be found.

```csharp
public static class CreateDialogueRunnerMenuItem
{
    [MenuItem("GameObject/Yarn Spinner/Dialogue System", priority = 11)]
    public static DialogueRunner CreateDialogueRunner()
}
```

--------------------------------

### Accessing YarnProject data and localization

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/yarn-project-and-localization.md

Demonstrates how to iterate through node names, retrieve initial variable values, add runtime localization overrides, and precompute line IDs for specific nodes.

```csharp
// Read initial values and node list at startup:
foreach (var name in project.NodeNames) { Debug.Log(name); }
if (project.InitialValues.TryGetValue("$gold", out var gold)) { Debug.Log(gold); }

// Fetch a localization and add runtime overrides:
var fr = project.GetLocalization("fr");
fr.AddLocalizedString("line:1000", "Bonjour !");

// Precompute line IDs for a set of nodes (e.g. to preload VO):
var ids = project.GetLineIDsForNodes(new[] { "Prologue", "Chapter1" });
```

--------------------------------

### Dialogue Presenter Usage

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/dialogue-presenters.md

Shows how to wire presenters to a runner and create a custom presenter that auto-selects the first available option.

```APIDOC
## Dialogue Presenter Usage

### Description
Presenters are components; wire them up to a runner. Add LinePresenter, OptionsPresenter, VoiceOverPresenter to GameObjects in the scene and assign them to runner.DialoguePresenters (inspector list).

### Example
```csharp
runner.DialoguePresenters = new List<DialoguePresenterBase?> { linePresenter, optionsPresenter, voiceOver };
```

### Custom Presenter Example
```csharp
public class AutoPickPresenter : DialoguePresenterBase
{
    public override YarnTask RunLineAsync(LocalizedLine line, LineCancellationToken token) => YarnTask.CompletedTask;
    public override YarnTask OnDialogueStartedAsync() => YarnTask.CompletedTask;
    public override YarnTask OnDialogueCompleteAsync() => YarnTask.CompletedTask;
    public override YarnTask<DialogueOption?> RunOptionsAsync(DialogueOption[] options, LineCancellationToken token)
    {
        foreach (var option in options) { if (option.IsAvailable) return YarnTask.FromResult<DialogueOption?>(option); }
        return DialogueRunner.NoOptionSelected;
    }
}
```
```

--------------------------------

### OptionItem.Option getter

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/errors.md

Gets the option item's option. Throws NullReferenceException if the option has not been set.

```APIDOC
## OptionItem.Option getter

### Description
Gets the option item's option. Throws NullReferenceException if the option has not been set.

### Method
Getter

### Endpoint
OptionItem.Option

### Exceptions
- **NullReferenceException** - Thrown when reading Option before it was set. Message: "Option has not been set on the option item".
```

--------------------------------

### DialogueRunner.CommandDispatcher getter

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/errors.md

Gets the command dispatcher for the DialogueRunner. Throws InvalidOperationException if the dispatcher could not be created.

```APIDOC
## DialogueRunner.CommandDispatcher getter

### Description
Gets the command dispatcher for the DialogueRunner. Throws InvalidOperationException if the dispatcher could not be created.

### Method
Getter

### Endpoint
DialogueRunner.CommandDispatcher

### Exceptions
- **InvalidOperationException** - Thrown when EnsureCommandDispatcherReady failed to create a dispatcher.
```

--------------------------------

### Action registration method signatures

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/dialogue-runner.md

Signatures for methods used to register and remove command handlers and functions.

```csharp
public void AddCommandHandler(string commandName, Delegate handler)
public void AddCommandHandler(string commandName, MethodInfo method)
public void RemoveCommandHandler(string commandName)
public void AddFunction(string name, Delegate implementation)
public void RemoveFunction(string name)
public void RegisterFunctionDeclaration(string name, Type returnType, Type[] parameterTypes)  // no-op
```

--------------------------------

### Create a new Git branch

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/CONTRIBUTING.md

Use this command to create and switch to a new branch before making changes to the repository.

```bash
git checkout -b my-branch-name
```

--------------------------------

### BuiltinLocalisedLineProvider.GetLocalization

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/errors.md

Gets a localized line. Throws InvalidOperationException if no YarnProject is set or the project has no localization for the requested locale.

```APIDOC
## BuiltinLocalisedLineProvider.GetLocalization

### Description
Gets a localized line. Throws InvalidOperationException if no YarnProject is set or the project has no localization for the requested locale.

### Method
GetLocalization

### Endpoint
BuiltinLocalisedLineProvider.GetLocalization

### Exceptions
- **InvalidOperationException** - Thrown when no YarnProject is set (message: "Can't get localized line: no Yarn Project set") or the project has no localization for the requested locale.
```

--------------------------------

### InputSystemAvailability Static Class

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/_autodocs/api-reference/markup-and-effects.md

Provides an abstract gateway between the legacy Input Manager and the new Input System, determined at compile time.

```csharp
public static class InputSystemAvailability
{
    public static bool GetKeyDown(KeyCode key);
    public static bool GetButtonDown(string? buttonName);
    public static float GetAxis(string? axisName);
}
```

--------------------------------

### DialoguePresenterTemplate implementation

Source: https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Editor/Templates/DialoguePresenterTemplate.txt

The base class template for implementing custom dialogue presentation logic in Yarn Spinner for Unity.

```csharp
using System.Threading;
using System.Collections.Generic;
using UnityEngine;
using Yarn;
using Yarn.Unity;

#nullable enable

public class #SCRIPTNAME# : DialoguePresenterBase
{
    public override async YarnTask OnDialogueStartedAsync()
    {
        // Called by the Dialogue Runner to signal that dialogue has just
        // started up.
        //
        // You can use this method to prepare for presenting dialogue, like
        // changing the camera, fading up your on-screen UI, or other tasks.
        //
        // The Dialogue Runner will wait until every Presenter returns from
        // this method before delivering any content.
    }

    public override async YarnTask OnDialogueCompleteAsync()
    {
        // Called by the Dialogue Runner to signal that dialogue has ended.
        //
        // You can use this method to clean up after running dialogue, like
        // changing the camera back, fading away on-screen UI, or other tasks.
    }

    public override async YarnTask RunLineAsync(LocalizedLine line, LineCancellationToken token)
    {
        // Called by the Dialogue Runner to signal that a line of dialogue
        // should be shown to the player.
        //
        // If your presenter handles lines, it should take the 'line'
        // parameter and use the information inside it to present the content to
        // the player, in whatever way makes sense.
        //
        // Some useful information:
        // - The 'Text' property in 'line' contains the parsed, localised text
        //   of the line, including attributes and text.
        // - The 'TextWithoutCharacterName' property contains all of the text
        //   after the character name in the line (if present), and the
        //   'CharacterName' contains the character name (if present).
        // - The 'Asset' property contains whatever object was associated with
        //   this line, as provided by your Dialogue Runner's Line Provider.
        //
        // The LineCancellationToken contains information on whether the
        // Dialogue Runner wants this Presenter to hurry up its
        // presentation, or to advance to the next line. 
        //
        // - If 'token.IsHurryUpRequested' is true, that's a hint that your view
        //   should speed up its delivery of the line, if possible (for example,
        //   by displaying text faster). 
        // - If 'token.IsNextContentRequested' is true, that's an instruction that
        //   your view must end its presentation of the line as fast as possible
        //   (even if that means ending the delivery early.)
        //
        // The Dialogue Runner will wait for all Presenters to return from
        // this method before delivering new content.
        //
        // If your Dialogue Presenters doesn't need to handle lines, simply return
        // from this method immediately.
    }

    public override async YarnTask<DialogueOption?> RunOptionsAsync(DialogueOption[] dialogueOptions, LineCancellationToken cancellationToken)
    {
        // Called by the Dialogue Runner to signal that options should be shown
        // to the player.
        //
        // If your Dialogue Presenter handles options, it should present them to the
        // player and await a selection. Once a choice has been made, it should
        // return the appropriate element from dialogueOptions.
        //
        // The LineCancellationToken contains information on whether the
        // Dialogue Runner wants this Presenter to hurry up its
        // presentation, or to advance to the next piece of content. 
        //
        // - If 'token.IsHurryUpRequested' is true, that's a hint that your view
        //   should speed up its delivery of the options, if possible (for example,
        //   by fading up text faster). 
        // - If 'token.IsNextContentRequested' is true, that's an instruction that
        //   your view must end handling options and return null as soon as possible.
        //
        // The Dialogue Runner will wait for all Dialogue Presenters to return from
        // this method before delivering new content.
        //
        // If your Dialogue Presenter doesn't need to handle options, simply
        // delete this method.

        return null;
    }
}
```
Tokens:
Raw