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).

DialoguePresenterBase

A MonoBehaviour that is informed of important events occurring in your dialogue, when it receives them from a DialogueRunner and are used for a variety of different tasks. Primarily these are how you show lines and options to the player.
public abstract class DialoguePresenterBase : MonoBehaviour

Inherits from MonoBehaviour

When the Dialogue Runner encounters content that the user should see - that is, lines or options - it sends that content to all of the dialogue presenters stored in Yarn.Unity.DialogueRunner.dialoguePresenters. The Dialogue Runner then waits until all Dialogue Presenters have reported that they have finished presenting the content. To use this class, subclass it, and implement its required methods. Once you have written your subclass, attach it as a component to a GameObject, and add this game object to the list of Dialogue presenters in your scene's DialogueRunner.

Dialogue Presenters do not need to handle every kind of content that the Dialogue Runner might produce. For example, you might have one Dialogue Presenter that handles Lines, and another that handles Options. The built-in LinePresenter class is an example of this, in that it only handles Lines and does nothing when it receives Options.

You may also have multiple Dialogue Presenters that handle the same kind of content. For example, you may have a Dialogue Presenter that receives Lines and uses them to play voice-over audio, and a second Dialogue Presenter that also receives Lines and uses them to display on-screen subtitles.

While the main focus of Dialogue Presenters is on the presentation of content to the user they also are informed of a much wider gamut of important dialogue events. There is no restriction or limitation on what you do with your Dialogue Presenters, other than with the exception of Options, you cannot use them to influence how the dialogue works. Think of Dialogue Presenters as a read-only responder to your story.

See also

#Properties

#Typewriter

The typewriter is the object that is responsible for controlling the timing of visual presentation content. As such not all Dialogue Presenters have or need one.
public virtual IAsyncTypewriter? Typewriter { get; set; }

Type IAsyncTypewriter

The typewriter by itself won't do anything and needs to be told when to do things by the presenter however because the style of typewriter can change this property exists so that there is a common point to assign the typewriter.

See also

#Methods

#OnDialogueCompleteAsync() Obsolete

This method is deprecated in favour of OnDialogueCompleteAsync(CancellationToken)

Called by the DialogueRunner to signal that the dialogue has ended, and no more content will be delivered.
public virtual YarnTask OnDialogueCompleteAsync();

Parameters

  • token(unknown)
    The cancellation token for this task, if cancelled this method should finish as soon as possible.

Returns YarnTask: A task that represents any work done by this dialogue presenter in order to clean up after running dialogue.

This method is called after the last piece of content (that is, lines, options or commands) finished running.

This method is a good place to perform tasks like dismissing on-screen dialogue UI (for example, turning off a letterboxing effect, or hiding dialogue UI elements.)

The default implementation of this method does nothing.

#OnDialogueCompleteAsync(CancellationToken)

Called by the DialogueRunner to signal that the dialogue has ended, and no more content will be delivered.
public virtual YarnTask OnDialogueCompleteAsync(CancellationToken token);

Parameters

  • tokenSystem.Threading.CancellationToken
    The cancellation token for this task, if cancelled this method should finish as soon as possible.

Returns YarnTask: A task that represents any work done by this dialogue presenter in order to clean up after running dialogue.

This method is called after the last piece of content (that is, lines, options or commands) finished running.

This method is a good place to perform tasks like dismissing on-screen dialogue UI (for example, turning off a letterboxing effect, or hiding dialogue UI elements.)

The default implementation of this method does nothing.

#OnDialogueStartedAsync() Obsolete

This method is deprecated in favour of OnDialogueStartedAsync(CancellationToken)

Called by the DialogueRunner to signal that dialogue has started.
public virtual YarnTask OnDialogueStartedAsync();

Parameters

  • token(unknown)
    The cancellation token for this task, if cancelled this method should finish as soon as possible.

Returns YarnTask: A task that represents any work done by this dialogue presenter in order to get ready for dialogue to run.

This method is called before any content (that is, lines, options or commands) are delivered.

This method is a good place to perform tasks like preparing on-screen dialogue UI (for example, turning on a letterboxing effect, or making dialogue UI elements visible.)

The default implementation of this method does nothing.

#OnDialogueStartedAsync(CancellationToken)

Called by the DialogueRunner to signal that dialogue has started.
public virtual YarnTask OnDialogueStartedAsync(CancellationToken token);

Parameters

  • tokenSystem.Threading.CancellationToken
    The cancellation token for this task, if cancelled this method should finish as soon as possible.

Returns YarnTask: A task that represents any work done by this dialogue presenter in order to get ready for dialogue to run.

This method is called before any content (that is, lines, options or commands) are delivered.

This method is a good place to perform tasks like preparing on-screen dialogue UI (for example, turning on a letterboxing effect, or making dialogue UI elements visible.)

The default implementation of this method does nothing.

#OnNodeEnter(string, CancellationToken)

Called by the DialogueRunner when a node is entered.
public virtual YarnTask OnNodeEnter(string nodeName, CancellationToken token = default);

Parameters

  • nodeNamestring
    the node being entered
  • tokenSystem.Threading.CancellationToken
    The cancellation token for this task, if cancelled this method should finish as soon as possible.

Returns YarnTask

This will be called before any content from that node has been presented, but other content may have already been shown from other nodes.

The default implementation of this method does nothing.

#OnNodeExit(string, CancellationToken)

Called by the DialogueRunner when a node is exited.
public virtual YarnTask OnNodeExit(string nodeName, CancellationToken token = default);

Parameters

  • nodeNamestring
    the node being exited
  • tokenSystem.Threading.CancellationToken
    The cancellation token for this task, if cancelled this method should finish as soon as possible.

Returns YarnTask

This will be called before after all content from that node has been presented, but does not necessarily signal the end of dialogue.

The default implementation of this method does nothing.

#RunCommand(Command, LineCancellationToken)

Called by the dialogue runner whenever a command is encountered in the dialogue.
public virtual YarnTask RunCommand(Command command, LineCancellationToken cancellationToken);

Parameters

Returns YarnTask

This is called on all presenters before the normal command dispatch flow occurs. You cannot prevent the normal command dispatch happening from within your presenter. But if this will be called regardless of if there are any handlers for the command registered on the dialogue runner.

Because the nature of command parsing has more edge-cases than it might first seem if you do want to perform your own processing here, the SplitCommandText(string) method handles splitting apart the command into it's parameters for you. While a command is just a series of individual words the way it ends up being broken up and how escape characters work changes on if strings are used within the command or not. The first parameter of the command will always be name of the command.

#RunLineAsync(LocalizedLine, LineCancellationToken)

Called by the DialogueRunner to signal that a line should be displayed to the user.
public virtual YarnTask RunLineAsync(LocalizedLine line, LineCancellationToken token);

Parameters

Returns YarnTask: A task that completes when the dialogue presenter has finished showing the line to the user.

When this method is called, the Dialogue Presenter should present the line to the user. The content to present is contained within the line parameter, which contains information about the line in the user's current locale.

It's up to the Dialogue Presenter to decide what "presenting" the line may mean; for example, showing on-screen text, playing voice-over audio, or updating on-screen portraits to show a picture of the speaking character.

The DialogueRunner will wait until the tasks from all of its dialogue presenters have completed before continuing to the next piece of content. If your dialogue presenter does not need to handle the line, it should return immediately.

The value of the line parameter is produced by the Dialogue Runner's LineProviderBehaviour.

The default implementation of this method takes no action and returns immediately.

See also

  • RunOptionsAsync

#RunOptionsAsync(DialogueOption[], LineCancellationToken)

Called by the DialogueRunner to signal that a set of options should be displayed to the user.
public virtual YarnTask<DialogueOption?> RunOptionsAsync(DialogueOption[] dialogueOptions, LineCancellationToken cancellationToken);

Parameters

Returns YarnTask: A task that indicates which option was selected, or that this dialogue presenter did not select an option.

This method is called when the Dialogue Runner wants to show a collection of options that the user should choose from. Each option is represented by a DialogueOption object, which contains information about the option.

When this method is called, the Dialogue Presenter should display appropriate user interface elements that let the user choose among the options.

This method should await until an option is selected, and then return the selected option. If this view doesn't handle options, or is otherwise unable to select an option, it should return NoOptionSelected. The dialogue runner will wait for all dialogue views to return, so if a dialogue presenter doesn't or can't handle options, it's good practice to return as soon as possible.

If the cancellationToken becomes cancelled, this means that the dialogue runner no longer needs this Dialogue presenter to make a selection, and this method should return as soon as possible; its return value will not be used.

The default implementation of this method returns NoOptionSelected.

See also

Generated from Yarn Spinner for Unity 3.3.