DialogueRunner

class DialogueRunner

The DialogueRunner is the engine that executes Jenny’s dialogue at runtime.

If you imagine YarnProject as a “program”, consisting of multiple Nodes as “functions”, then DialogueRunner is a virtual machine, capable of executing a single “function” in that “program”.

A single DialogueRunner may only execute one dialogue node at a time. It is an error to try to run another node before the first one concludes. However, it is possible to create multiple DialogueRunners for the same YarnProject, and then they would be able to execute multiple dialogues simultaneously (for example, in a crowded room there could be multiple dialogues occurring at once within different groups of people).

The job of a DialogueRunner is to fetch the dialogue lines in the correct order and at the appropriate pace, to execute the logic in dialogue scripts, and to branch according to user input in DialogueChoices. The output of a DialogueRunner, therefore, is a stream of dialogue statements that need to be presented to the player. Such presentation, is handled by DialogueViews.

Constructors

DialogueRunner({required YarnProject yarnProject, required List<DialogueView> dialogueViews})

Creates a DialogueRunner for executing the yarnProject. The dialogue will be delivered to all the provided dialogueViews. Each of these dialogue views may only be assigned to a single DialogueRunner at a time.

Properties

project : YarnProject

The YarnProject that this dialogue runner is executing.

Methods

startDialogue(String nodeName) → Future<void>

Starts the dialogue with the node nodeName, and returns a future that completes once the dialogue finishes running. While this future is pending, the DialogueRunner cannot start any other dialogue.

sendSignal(dynamic signal)

Delivers the given signal to all dialogue views, in the form of a DialogueView method onLineSignal(line, signal). This can be used, for example, as a means of communication between the dialogue views.

The signal object here is completely arbitrary, and it is up to the implementations to decide which signals to send and to receive. Implementations should ignore any signals they do not understand.

stopLine()

Requests (via onLineStop()) that the presentation of the current line be finished as quickly as possible. The dialogue will then proceed normally to the next line.

Execution model

The DialogueRunner uses futures as a main mechanism for controlling the timing of the dialogue progression. For each event, the dialogue runner will invoke the corresponding callback on all its DialogueViews, and each of those callbacks may return a future. The dialogue runner then awaits on all of these futures (in parallel), before proceeding to the next event.

For a simple .yarn script like this

title: main
---
Hello
-> Hi
-> Go away
   <<jump Away>>
===

title: Away
---
<<OhNo>>
===

the sequence of emitted events will be as follows (assuming the second option is selected):

• onDialogueStart()

• onNodeStart(Node("main"))

• onLineStart(Line("Hello"))

• onLineFinish(Line("Hello"))

• onChoiceStart(Choice(["Hi", "Go away"]))

• onChoiceFinish(Option("Go away"))

• onNodeFinish(Node("main"))

• onNodeStart(Node("Away"))

• onCommand(Command("OhNo"))

• onNodeFinish(Node("Away"))

• onDialogueFinish()

Note

Keep in mind that if a DialogueError is thrown while running the dialogue, then the dialogue will terminate immediately and none of the *Finish callbacks will run.