Pardon our dust! Docs for Yarn Spinner for Unity 3.2 and Yarn Spinner for Godot C# are on docs.yarnspinner.dev (the old docs site). Docs for Yarn Spinner for Unity 3.3 (pre-release, out ASAP), Yarn Spinner for Godot GDScript and Yarn Spinner for Unreal Engine (work in progress) are on /docs/ (the new docs site).

DialogueRunner

public class DialogueRunner

Inherits from MonoBehaviour

Implements Yarn.Unity.IActionRegistration, Yarn.IDialogueResponder

#Fields

#autoStart

Whether the dialogue runner will immediately start running dialogue after loading.
public bool autoStart = false;

Type Boolean

If this is set the dialogue runner will wait one frame after Yarn.Unity.DialogueRunner.Start is called and then start dialogue. This one frame wait is due to some timing issues that can occur but if it is an issue disable this and manually call RunDialogue(string,CancellationToken) yourself on the first frame.

#runSelectedOptionAsLine

If this value is set, when an option is selected, the line contained in it (Line) will be delivered to the dialogue runner's dialogue presenters as though it had been written as a separate line.
public bool runSelectedOptionAsLine = false;

Type Boolean

This allows a Yarn script to

#startNode

The name of the node that will start running immediately after loading.
public string startNode = "Start";

Type String

This value must be the name of a node present in YarnProject.

See also

#verboseLogging

If true, will print Debug.Log messages every time it enters a node, and other frequent events.
public bool verboseLogging = false;

Type Boolean

#Properties

#Dialogue

The current dialogue for this runner.
public Dialogue Dialogue { get; }

Type Dialogue

#DialoguePresenters

Gets or sets the collection of dialogue presenters attached to this dialogue runner.
public IEnumerable<DialoguePresenterBase?> DialoguePresenters { get; set; }

Type IEnumerable

#IsDialogueRunning

Gets a value that indicates if the dialogue is actively running.
public bool IsDialogueRunning { get }

Type Boolean

#IsInPlaymode

Convenience property to determine if the game is in playmode or editor mode
public static bool IsInPlaymode { get; }

Type Boolean

#LineProvider

Gets the ILineProvider that this dialogue runner uses to fetch localized line content.
public ILineProvider LineProvider { get; }

Type ILineProvider

#NoOptionSelected

public static YarnTask<DialogueOption?> NoOptionSelected { get; }

Type YarnTask

#VariableStorage

Gets the VariableStorage that this dialogue runner uses to store and access Yarn variables.
public VariableStorageBehaviour VariableStorage { get; set; }

Type VariableStorageBehaviour

If there is no variable storage set an InMemoryVariableStorage will be created and used instead.

#YarnProject

Gets the YarnProject asset that this dialogue runner uses.
public YarnProject? YarnProject { get }

Type YarnProject

See also

#Methods

#AddCommandHandler(string, Delegate)

Adds a command handler and registers the command with Yarn as one that can be called.
public void AddCommandHandler(string commandName, Delegate handler);

Parameters

  • commandNamestring
    The name of the command.
  • handlerDelegate
    The CommandHandler that will be invoked when the command is called.

You can also register commands via the YarnCommandAttribute attribute on your methods.

When this command handler has been added, it can be called from your Yarn scripts like so:

     <<commandName param1 param2>>
     

If handler is a method that returns a YarnTask, Task, Awaitable, or UniTask when the command is run, the DialogueRunner will wait for the task to finish before delivering any more content.

If handler is a method that returns a Coroutine, when the command is run, the DialogueRunner will wait for the returned coroutine to stop before delivering any more content.

If handler is a method that returns an System.Collections.IEnumerator, when the command is run, the DialogueRunner will start a coroutine using that method and wait for that coroutine to stop before delivering any more content.

#AddCommandHandler(string, MethodInfo)

Adds a command handler and registers the command with Yarn as one that can be called.
public void AddCommandHandler(string commandName, MethodInfo method);

Parameters

  • commandNamestring
    The name of the command.
  • handler(unknown)
    The CommandHandler that will be invoked when the command is called.
  • commandName(unknown)
    The name of the command.
  • methodInfo(unknown)
    The method that will be invoked when the command is called.
  • methodMethodInfo

You can also register commands via the YarnCommandAttribute attribute on your methods.

When this command handler has been added, it can be called from your Yarn scripts like so:

     <<commandName param1 param2>>
     

If handler is a method that returns a YarnTask, Task, Awaitable, or UniTask when the command is run, the DialogueRunner will wait for the task to finish before delivering any more content.

If handler is a method that returns a Coroutine, when the command is run, the DialogueRunner will wait for the returned coroutine to stop before delivering any more content.

If handler is a method that returns an System.Collections.IEnumerator, when the command is run, the DialogueRunner will start a coroutine using that method and wait for that coroutine to stop before delivering any more content.

#AddFunction(string, Delegate)

Add a new function that returns a value, so that it can be called from Yarn scripts.
public void AddFunction(string name, Delegate implementation);

Parameters

  • namestring
    The name of the function to add.
  • implementationDelegate
    The System.Delegate that should be invoked when this function is called.

You can also register functions via the YarnFunctionAttribute attribute on your methods.

When this function has been registered, it can be called from your Yarn scripts like so:

     <<if myFunction(1, 2) == true>>
         myFunction returned true!
     <<endif>>
     

See also

  • Library

#AddPresenter(DialoguePresenterBase)

Adds the new presenter into the collection of dialogue presenters the runner will inform of important dialogue events.
public void AddPresenter(DialoguePresenterBase presenter)

Parameters

#CanCallFunction(string)

public bool CanCallFunction(string functionName)

Parameters

  • functionNamestring

Returns Boolean

#FindRunner(Component)

Attempts to find the "nearest" dialogue runner for the requested component
public static DialogueRunner? FindRunner(Component component)

Parameters

  • componentComponent
    The component whos dialogue runner we are after

Returns DialogueRunner: The runner, or null if one couldn't be found

Because there can be multiple dialogue runners in a scene performing a normal FindAnyObjectByType call may return a runner that isn't the runner we are after. This method makes an assumption about scene hierarchy (but one we've seen multiple times) that the dialogue runner you care about is a parent or sibling of the current component. This works because dialogue and related components tend to be all ultimately packaged together into one Game Object in the scene. If this assumption fails to find it will fall back on a FindAnyObjectByType call to collect any runner.

#HandleCommand(Command, CancellationToken)

public async ValueTask HandleCommand(Command command, CancellationToken token)

Parameters

Returns ValueTask

#HandleDialogueComplete()

public async ValueTask HandleDialogueComplete()

Returns ValueTask

#HandleLine(Line, CancellationToken)

public async ValueTask HandleLine(Line line, CancellationToken token)

Parameters

Returns ValueTask

#HandleNodeComplete(string, CancellationToken)

public async ValueTask HandleNodeComplete(string node, CancellationToken token)

Parameters

  • nodestring
  • tokenCancellationToken

Returns ValueTask

#HandleNodeStart(string, CancellationToken)

public async ValueTask HandleNodeStart(string node, CancellationToken token)

Parameters

  • nodestring
  • tokenCancellationToken

Returns ValueTask

#HandleOptions(OptionSet, CancellationToken)

public async ValueTask<int> HandleOptions(OptionSet options, CancellationToken token)

Parameters

Returns ValueTask

#InvokeFunction(string, IConvertible[], CancellationToken)

public async ValueTask<IConvertible> InvokeFunction(string functionName, IConvertible[] parameters, CancellationToken token)

Parameters

  • functionNamestring
  • parametersIConvertible[]
  • tokenCancellationToken

Returns ValueTask

#LoadStateFromPersistentStorage(string)

Loads all variables from the requested file in persistent storage into the Dialogue Runner's variable storage.
public bool LoadStateFromPersistentStorage(string saveFileName)

Parameters

  • saveFileNamestring
    the name the save file should have on disc, including any file extension

Returns Boolean: true if the variables were successfully loaded from the player preferences; false otherwise.

This method loads the file saveFileName from the persistent data storage and attempts to read it as JSON. This is then deserialised and loaded into the VariableStorage.

The loaded information can be stored via the SaveStateToPersistentStorage(string) method.

#PrepareForLines(List<string>, CancellationToken)

public async ValueTask PrepareForLines(List<string> lineIDs, CancellationToken token)

Parameters

  • lineIDsList<string>
  • tokenCancellationToken

Returns ValueTask

#RemoveCommandHandler(string)

Removes a command handler. This does not impact the compiled Yarn program, only the runtime actions. The Yarn VM will still attempt to call the command when it encounters it, likely results in an exception being thrown. In general you should only remove commands if you know they won't be needed.
public void RemoveCommandHandler(string commandName);

Parameters

  • commandNamestring
    The name of the command to remove.

#RemoveFunction(string)

Remove a registered function.
public void RemoveFunction(string name);

Parameters

  • namestring
    The name of the function to remove.

After a function has been removed, it cannot be called from Yarn scripts.

This does not impact the compiled Yarn program, only the runtime actions. The Yarn VM will still attempt to call the function when it encounters it, likely resulting in an exception being thrown. In general you should only remove functions if you know they won't be needed.

See also

#RemovePresenter(DialoguePresenterBase)

Removes the requested parameter from the collection of presenters
public bool RemovePresenter(DialoguePresenterBase presenter)

Parameters

Returns Boolean: true if the presenter was in the collection, false otherwise

#RequestHurryUpContent()

Requests that all dialogue presenters speed up their delivery of the current content.
public void RequestHurryUpContent()

The specific behaviour of what happens when this method is called depends on the implementation of the Dialogue Runner's current dialogue presenters.

If the dialogue runner is not currently running dialogue this method has no effect.

#RequestHurryUpLine() Obsolete

This method has been superceded by RequestHurryUpContent and now forwards calls to that

Requests that all dialogue presenters speed up their delivery of the current line.
public void RequestHurryUpLine()

#RequestHurryUpOption() Obsolete

This method has been superceded by RequestHurryUpContent and now forwards calls to that

Requests that all dialogue presenters speed up their delivery of the current option group
public void RequestHurryUpOption()

#RequestNextContent()

Requests that presenters stop showing the current content (be that line, command, or option), and prepare to show the next piece of content.
public void RequestNextContent()

The specific behaviour of what happens when this method is called depends on the implementation of the Dialogue Runner's current dialogue presenters.

If the dialogue runner is not currently running dialogue at all, this method has no effect.

#RequestNextLine() Obsolete

This method has been superceded by RequestNextContent and now forwards calls to that

Requests that all dialogue presenters stop showing the current line, and prepare to show the next piece of content.
public void RequestNextLine()

#RunDialogue(string, CancellationToken)

Starts running a node of dialogue.
public async YarnTask RunDialogue(string nodeName, CancellationToken cancellationToken = default)

Parameters

  • nodeNamestring
    The name of the node to run.
  • cancellationTokenCancellationToken

Returns YarnTask

nodeName must be the name of a node in YarnProject.

This task that starts will run the entire duration of the dialogue. Essentially this task will only complete once the dialogue ends or Stop() is called.

#SaveStateToPersistentStorage(string)

Saves all variables from variable storage into the persistent storage.
public bool SaveStateToPersistentStorage(string saveFileName)

Parameters

  • saveFileNamestring
    the name the save file should have on disc, including any file extension

Returns Boolean: true if the variables were successfully written into the player preferences; false otherwise.

This method attempts to writes the contents of VariableStorage as a JSON file and saves it to the persistent data storage under the file name saveFileName. The saved information can be loaded via the LoadStateFromPersistentStorage(string) method.

If saveFileName already exists, it will be overwritten, not appended.

#SetProject(YarnProject)

Sets the dialogue runner's Yarn Project.
public void SetProject(YarnProject project)

Parameters

Exceptions

  • System.InvalidOperationException
    Thrown when attempting to set a new project while a dialogue is currently running.
If the dialogue runner is currently running (that is, IsDialogueRunning is true), an System.InvalidOperationException is thrown.

#SplitCommandText(string)

Splits input into a number of non-empty sub-strings, separated by whitespace, and grouping double-quoted strings into a single sub-string.
public static IEnumerable<string> SplitCommandText(string input)

Parameters

  • inputstring
    The string to split.

Returns IEnumerable: A collection of sub-strings.

This method behaves similarly to the System.String.Split(System.Char[],System.StringSplitOptions) method with the System.StringSplitOptions parameter set to System.StringSplitOptions.RemoveEmptyEntries, with the following differences:
  • Text that appears inside a pair of double-quote characters will not be split.
  • Text that appears after a double-quote character and before the end of the input will not be split (that is, an unterminated double-quoted string will be treated as though it had been terminated at the end of the input.)
  • When inside a pair of double-quote characters, the string \\ will be converted to \, and the string \" will be converted to ".

#StartDialogue(string) Obsolete

This method kicks off dialogue but doesn't await it's completion. Prefer RunDialogue where possible

Starts running a node of dialogue.
public void StartDialogue(string nodeName)

Parameters

  • nodeNamestring
    The node to start dialogue from

This method asks the runner to begin dialogue and then returns immediately. This means your presenters may not yet have been told that dialogue has started by the time this method finishes.

Where possible we recommend that you initiate dialogue with RunDialogue(string,CancellationToken) which holds until the dialogue finishes entirely before returning.

#Stop()

Stops the dialogue immediately, and cancels any currently running dialogue presenters.
public async YarnTask Stop()

Returns YarnTask

Generated from Yarn Spinner for Unity 3.3.