DialoguePresenterBase
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 : MonoBehaviourInherits 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
Yarn.Unity.LineProviderBehaviourYarn.Unity.DialogueRunner.dialoguePresenters
#Properties
#Typewriter
public virtual IAsyncTypewriter? Typewriter { get; set; }Type IAsyncTypewriter
See also
#Methods
#OnDialogueCompleteAsync() Obsolete
This method is deprecated in favour of OnDialogueCompleteAsync(CancellationToken)
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)
public virtual YarnTask OnDialogueCompleteAsync(CancellationToken token);Parameters
tokenSystem.Threading.CancellationTokenThe 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)
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)
public virtual YarnTask OnDialogueStartedAsync(CancellationToken token);Parameters
tokenSystem.Threading.CancellationTokenThe 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)
public virtual YarnTask OnNodeEnter(string nodeName, CancellationToken token = default);Parameters
nodeNamestringthe node being enteredtokenSystem.Threading.CancellationTokenThe cancellation token for this task, if cancelled this method should finish as soon as possible.
Returns YarnTask
The default implementation of this method does nothing.
#OnNodeExit(string, CancellationToken)
public virtual YarnTask OnNodeExit(string nodeName, CancellationToken token = default);Parameters
nodeNamestringthe node being exitedtokenSystem.Threading.CancellationTokenThe cancellation token for this task, if cancelled this method should finish as soon as possible.
Returns YarnTask
The default implementation of this method does nothing.
#RunCommand(Command, LineCancellationToken)
public virtual YarnTask RunCommand(Command command, LineCancellationToken cancellationToken);Parameters
commandYarn.CommandThe command. It's values come entirely from the YarncancellationTokenYarn.Unity.LineCancellationTokenThe cancellation token for this task, if cancelled this method should finish as soon as possible.
Returns YarnTask
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)
public virtual YarnTask RunLineAsync(LocalizedLine line, LineCancellationToken token);Parameters
- The line to present.
- A LineCancellationToken that represents whether the dialogue presenter should hurry it its presentation of the line, or stop showing the current line.
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)
public virtual YarnTask<DialogueOption?> RunOptionsAsync(DialogueOption[] dialogueOptions, LineCancellationToken cancellationToken);Parameters
dialogueOptionsYarn.Unity.DialogueOption[]The set of options that should be displayed to the user.cancellationTokenYarn.Unity.LineCancellationTokenA LineCancellationToken that becomes cancelled when the dialogue runner no longer needs this dialogue presenter to return an option.
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
Yarn.Unity.DialoguePresenterBase.RunLineAsyncYarnAsync.NoOptionSelected
Generated from Yarn Spinner for Unity 3.3.