Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Learn about the Dialogue Runner, which runs the contents of your Yarn Scripts and delivers lines, options and commands to your game.
The Dialogue Runner is the bridge between the dialogue that you've written in your Yarn scripts and the other components of your game. It's a component that's responsible for loading, running and managing the contents of a Yarn Project, and for delivering the content of your Yarn scripts to the other parts of your game, such as your user interface.
Setting up a Dialogue Runner is the first step in adding dialogue to your game. To use a Dialogue Runner, you add it to a game object in your scene, connect it to Dialogue Views, and provide it with a Yarn Project to run.
When you want to start running the dialogue in your game, you call the Dialogue Runner's StartDialogue method. When you do this, the Dialogue Runner will begin delivering lines, options and commands to its Dialogue Views.
The Dialogue Runner is designed to work with other components of Yarn Spinner for Unity:
The contents of your dialogue are delivered to your Dialogue Views.
The values of variables are stored and retrieved using the Dialogue Runner's Variable Storage.
The content that users should see - that is, the text in their current language, voice over clips, and other assets - are retrieved using the Dialogue Runner's Line Provider.
The bare-bones minimum that a Dialogue Runner needs in order to work is a Yarn Project and at least one Dialogue View. If you don't set up a Variable Storage or a Line Provider, the Dialogue Runner will use temporary placeholders.
If your game is using the Unity Localization system, your Dialogue Runner must use a Unity Localised Line Provider.
Yarn Project
Variable Storage
Line Provider
Dialogue Views
Start Automatically
Start Node
If Start Automatically is turned on, the Dialogue Runner will start running this node when the scene starts. (If your Yarn Project does not contain a node with this name, an error will be reported.)
Run Selected Options as Lines
If this is turned on, when the user chooses an option, the Dialogue Runner will run the selected option as if it were a Line.
Verbose Logging
If this is turned on, the Dialogue Runner will log information about the state of each line to the Console as it's run.
On Node Start
A Unity Event that's fired when the Dialogue Runner begins running a new node. This may be fired multiple times during a dialogue run.
On Node Complete
A Unity Event that's fired when the Dialogue Runner reaches the end of a node. This may be fired multiple times during a dialogue run.
On Dialogue Complete
A Unity Event that's fired when the Dialogue Runner stops running dialogue.
On Command
The that this Dialogue Runner is running.
The to store and retrieve variable data from. If you do not set this, the Dialogue Runner will create an for you at runtime.
The to use to get user-facing content for each line. If you do not set this, the Dialogue Runner will create a for you at runtime.
The to send lines, options and commands to.
If this is turned on, the Dialogue Runner will start running the node named Start Node when the scene starts. If this is not turned on, you will need to call to start running.
A Unity Event that's fired when a Command is encountered. This will only be called if no other part of the system has already handled the command, such as command handlers registered via or .
Learn how to create Dialogue Views that are designed for the specific needs of your game.
While the Line View and Options List View are useful for lots of situations, your game might need to display lines and options in specific ways. In these situations, you can write your own custom Dialogue View, and handle the presentation of lines and options in ways that are entirely in your control.
To create a Dialogue View, you subclass the DialogueViewBase class, and add it as a component to a game object in your scene. You can then add this game object to the Dialogue Views list on your scene's Dialogue Runner.
If you just want to skip straight to the sample code, take a look at the SimpleSpeechBubbleLineView sample code in the Yarn Spinner examples repository.
On its own, an empty subclass of DialogueViewBase will not do anything useful. To make it display lines and options, you'll need to implement certain methods.
To understand how to create a custom Dialogue View, it's useful to understand how the Dialogue Runner works with content.
Yarn Spinner scripts deal in three different kinds of content: lines, options, and commands. Of these, only the first two - lines and options - are content that need to be shown directly to the player.
When the Dialogue Runner encounters lines or options, it first needs to determine the specific content the user needs to see. Once it has this, it sends the content to each of its Dialogue Views.
Your scene can have multiple Dialogue Views, and they can all do different things. It can be useful to create, for example, a Dialogue View that handles lines, and a separate Dialogue View that handles options.
Lines and options are represented in compiled Yarn scripts as line IDs. A line ID is a unique identifier for the text of a line or an option. When Yarn Spinner needs to show a line or option to the user, it asks its Line Provider to provide it with a LocalizedLine object. This object contains the text of the line or option, in the user's current locale.
As discussed in Line Providers, you can have different kinds of Line Providers; for example, the Text Line Provider creates LocalizedLine objects that just contain text, while Audio Line Provider creates objects that also contain an AudioClip.
When displaying a collection of options, each individual option has its own LocalizedLine.
Once a LocalizedLine has been created, the Dialogue Runner has everything that it needs to show content to the user. The next steps vary depending on whether it's showing a line or an option.
When Yarn Spinner encounters a line of dialogue, it calls the RunLine method on each Dialogue View. This method takes two parameters: the first is the LocalizedLine that the Line Provider created, and the second is a delegate that the Dialogue View should call when the line has finished being presented.
In Dialogue Views, a line is presented when the user has received the entire line, and is ready to move on to the next line. The practical outcome of what this means depends on the Dialogue View itself; for example, a Dialogue View that plays voice-over audio might finish presenting when all of the audio has played, while a Dialogue View that gradually reveals the text of a line might finish presenting when all of the text is visible.
The Dialogue Runner will wait until all Dialogue Views report that they've finished presenting the line. Once this happens, it moves on to the next part of the dialogue.
If you're making a game where you want the dialogue to pause until the user gives a signal to proceed, your Dialogue View can pause the dialogue by not calling the completion handler until it receives the signal. Because the Dialogue Runner will wait until all Dialogue Views report that they're done, the dialogue will wait until your view tells it to continue.
At any point during a line's presentation, a Dialogue View can interrupt the line. It does this by calling the requestInterrupt method, which is a delegate that's set by its controlling Dialogue Runner. When this method is called, all Dialogue Views that have not yet finished their presentation receive a call to their InterruptLine method.
InterruptLine is very similar to RunLine, in that it receives a line to present and a completion handler to call when the presentation is complete. However, while RunLine is expected to present the line at its own pace, InterruptLine is a signal to finish the presentation as quickly as possible.
As before, the actual details of this depend on the Line View. To continue the examples from before, a Dialogue View that plays voice-over audio might fade out the audio over a short period of time, or even cut off playback immediately; a Dialogue View that's gradually revealing text might reveal the remaining text all at once, or rapidly reveal the remaining text.
When a Dialogue View receives a call to InterruptLine, it should not call the completion handler that it received from the call to RunLine. Calls to interrupt a line supersede calls to run a line.
Any Dialogue View may request that a line be interrupted. If multiple Dialogue Views request it, only the first request does anything.
When the last Dialogue View reports that its presentation is complete, either because RunLine finished its presentation, or because InterruptLine was called and it quickly finished its presentation, it needs to tell the dialogue views to get rid of the line, and potentially prepare for more content.
The Dialogue Runner does this by calling DismissLine on all Dialogue Views. As with RunLine and InterruptLine before it, DismissLine receives a completion handler to call when it has finished dismissing the line.
As before, the details of how a line is dismissed vary with what the Dialogue View actually does. A Dialogue View that plays voice-over audio may not need to do anything to dismiss a line, because the playback has already finished; a Dialogue View that shows line text on screen might need to hide the text, possibly with an animation.
When the last Dialogue View reports that it has finished dismissing its line, the Dialogue Runner continues running the script.
Options are slightly different to lines, in that they rely on receiving some kind of user input before the dialogue can continue: the Dialogue Runner needs to know which option was selected.
To handle options, Dialogue Views implement the RunOptions method. This method receives an array of DialogueOption objects, each of which represents an option that can be shown to the user, as well as a completion handler.
When this method is called, the Dialogue View uses the information contained within the DialogueOption objects to present the choices to the player, and then awaits user input. Once it knows which option was selected, it calls the completion handler, passing in the DialogueOptionID of the selected option.
When the Dialogue Runner delivers options to its Dialogue Views, it expects exactly one of them to call the completion handler that RunOptions receives.
If none of them call it, then the Dialogue Runner will never receive the option that was selected (and will wait for it forever.)
If more than one of them call it, the Dialogue Runner will throw an error.
(In most situations, you will generally only have one Dialogue View in your scene that handles options. If you have more than one, then you will need to control which one of them will call their completion handler.)
Dialogue Runners can use multiple Dialogue Views. This is actually recommended, because it makes it easier to separate the code for handling lines, from that of running options.
All of the methods in DialogueViewBase are optional. If you don't implement a method, then the default implementation of that method is used instead; the default implementation either does nothing, or as close to nothing as it can while still working. For example, the default implementation of RunLine immediately signals that presentation is complete.
To create a Dialogue View that shows lines, implement RunLine, InterruptLine and DismissLine.
To create a Dialogue View that shows options, implement RunOptions.
To create a Dialogue View that supports both, implement all four.
During gameplay, your user may wish signal that they want to advance the dialogue: that is, they want to proceed to the next line, or they want the current line to be presented more quickly.
To handle this case, subclasses of DialogueViewBase may implement the method UserRequestedViewAdvancement, which can be called by other parts of the game.
In most cases, it is generally appropriate for implementations of UserRequestedViewAdvancement to call the requestInterrupt method, which tells the Dialogue Runner to interrupt the line (across all views) and to proceed to the next one. However, a Dialogue View may choose to perform other actions that deliver the line more quickly.
For example, in several text-based RPG games, dialogue is delivered as a text box, one letter at a time; when it's all delivered, the user can press the A button (to choose an arbitrary example) to proceed.
If, however, you press the A button while the text is still appearing, all of the text appears all at once (as though we'd jumped ahead).
Alternatively, if you pressed the B button while the text was still appearing, the line would be skipped, the dialogue would move to the next line.
UserRequestedViewAdvancement can be called by any part of your code. Additionally, you may wish to use DialogueAdvanceInput, which is a class that listens for user input, and when it receives it, calls UserRequestedViewAdvancement on a view you specify.
To access the tags on a line, you use the Metadata property on the LocalizedLine objects you receive. It's up to your code to decide what to do with the tags themselves.
Yarn Spinner will automatically add certain tags to lines. For example, the #lastline tag is automatically added to any line that's immediately followed by options, which allows your dialogue view to change its behaviour when options are about to appear.
To demonstrate how a custom Dialogue View is put together, we've created an example Dialogue View, which demonstrates the above features and is heavily commented. For more information, see the code on GitHub.
Learn about Line View, a Dialogue View that displays a single line of dialogue on a Canvas.
Line View is a Dialogue View that displays a single line of dialogue inside a Unity UI canvas. When the Dialogue Runner encounters a line in your Yarn Script, the Line View will display it, wait for the user to indicate they're done reading it, and then dismiss it.
Line View only displays lines, and doesn't display options. You can use an additional Dialogue View to handle these, like an Options List View or a custom Dialogue View of your own.
If a line contains a character's name at the start, Line View can be configured to show the name in a separate text view to the line text itself. If the Character Name Text property is connected to a TextMeshPro Text object, then the character's name will appear in this object.
If you don't attach a Text object to the Character Name Text property, you can choose to either show the character name as part of the line (that is, in the Line Text view), or don't show it all.
Line View can be configured to use visual effects when presenting lines.
You can choose to have the Line View fade in when a line appears, and fade out when the line is dismissed.
You can choose to have the text of the line appear, one letter at a time, with a "typewriter" effect.
The Dialogue Runner will automatically proceed to the next piece of content once all dialogue views have reported that they've finished with a line.
If the 'Auto Advance' option on a Line View is turned on, then the Line View will signal that it's done with a line as soon as all visual effects have finished.
If 'Auto Advance' is turned off, then the Line View will not signal that it's done when the effects have finished, and the line's delivery will stop. To make the Line View finish up, you can call the UserRequestedViewAdvancement method, which tells the Line View that the user wants to proceed. The built-in Dialogue System prefab comes set up with a 'Continue' button that calls this method. You can also call this method from code, or use the Dialogue Advance Input component to trigger it based on user input.
Canvas Group
The Canvas Group that the Line View will control. The Canvas Group will be made active when the Line View is displaying a line, and inactive when not displaying a line.
Auto Advance
If this is turned on, the Line View will finish presenting the line, and then wait. This is useful for games where the user has control over the timing of lines of dialogue. If this is turned off, the Line View will signal to the Dialogue Runner that it's done showing the line once all animations are complete.
Hold Time
If Auto Advance is turned on, the Line View will wait this many seconds after all animations are complete before signalling that it's done showing the line. This option is only available when Auto Advance is turned on.
Line Text
A TextMeshPro Text object that the text of the line will be displayed in.
Use Fade Effect
If this is turned on, the Line View will fade the opacity of the Canvas Group from 0% to 100% opacity when lines appear, and fade back to 0% when lines are dismissed.
Fade In Time
The duration of the Fade effect when fading a new line in, in seconds. If this is zero, the line will appear immediately.
Fade Out Time
The duration of the Fade effect when fading a line out, in seconds. If this is zero, the line will disappear immediately.
Use Typewriter Effect
If this is turned on, the text of the line will appear one character at a time. This will take place after the Fade effect, if enabled.
On Character Typed
A Unity Event that's called every time the Typewriter effect displays new text.
Typewriter Effect Speed
The number of characters per second to display when performing a Typewrite effect. Larger values means that text will appear faster.
Character Name Text
A TextMeshPro Text object that will display the name of the character currently speaking the line.
Show Character Name In Line View
If this is turned on, lines that contain a character's name will display the name in the Line Text section. If it is turned off, character names will not be shown at all. This option is only available when Character Name Text is empty.
Continue Button
A game object that will be made active when the line has finished appearing. This is intended to be used for controlling the appearance of a button that the user can interact with to continue to the next line.
Learn about Dialogue Advance Input, a component that can signal to a Dialogue View that the user wants to proceed to the next piece of content.
Dialogue Advance Input is a component that receives user input, and uses it to signal to a Dialogue View that the user wants to advance to the next piece of content. Dialogue Advance Input is generally used to implement a 'press spacebar to continue / skip' mechanic.
Dialogue Advance Input isn't a Line View itself, but it's designed to work with other line views, to interrupt and control the flow of dialogue.
To use a Dialogue Advance Input, create a new game object, and attach a Dialogue Advance Input component to it using the Add Component button.
You can control what specific input the component is looking for by changing the Continue Action Type setting:
If you set the Continue Action Type to Key Code, you can select a key on the keyboard that will continue to the next line on press.
If you set the Continue Action Type to Input Action, you can create an Action from an input device (such as from a keyboard, gamepad, or other method).
If you set the Continue action Type to Input Action from Asset, you can attach an Action from an Input Actions asset that you've set up elsewhere.
If you want to use Input Actions, your project will need to be set up to use the new Unity Input System.
Dialogue View
The that will be signalled when the user performs the continue action.
Continue Action Type
A drop-down list that selects how user input will be used to continue to the next line.
When set to None, the dialogue will not continue based on user input.
When set to Key Code, the dialogue will continue when the user presses the keyboard key specified in Continue Action Key Code.
When set to Input System Action, the dialogue will continue when the user performs the Action set up in Continue Action.
When set to Input System Action from Asset, the dialogue will continue when the user performs the Action specified by the Continue Action Reference field.
Continue Action Key Code
The keyboard key that the user should press to continue to the next line.
Continue Action
An Input Action that the user should perform to continue to the next line.
Continue Action Reference
An Input Action, stored inside an Input Actions asset, that the user should perform to continue to the next line.
Learn about Options List View, a Dialogue View that displays a list dialogue options.
Options List View is a that presents a list of options in a list.
When this view receives options from the Dialogue Runner, it creates an instance of the prefab you specify in the Option View Prefab property, and adds it as a child of the options list view.
Options List View only displays options, and doesn't display lines. You can use an additional Dialogue View to handle these, like a or a custom Dialogue View of your own.
Learn about Options View, a component used to display an option in an Options List View.
An Option View is an object that the uses when presenting options. When the delivers options to your game, Options List View will create an Option View for each option that could be selected.
When the Option View is pressed, the Options List View will notify the Dialogue Runner of the user's selection.
Line Providers are components that are responsible for taking the objects that the produces, and fetches the appropriate localised content for that line. Line Providers produce objects, which are sent to the Dialogue Runner's .
When a Yarn script runs, the Dialogue Runner produces Line objects. These objects contain information about the line, but not the text of the line itself. This is because it's the responsibility of the game to load the user-facing parts of the line, including the text of the line in the player's current language setting, as well as any other assets that may be needed to present the line (such as audio files for voiceover.)
Yarn Spinner comes with three built-in types of line providers:
is a Line Provider that fetches the text of a line, given a language to use.
is a Line Provider that fetches the text of a line as well as an , given languages to use.
is a Line Provider that fetches the text and any localised assets from .
If you don't set up a Line Provider for a Dialogue Runner, it will automatically create a Text Line Provider, and configure it to use the user's current language.
Variable Storage components are responsible for storing and retrieving the values of variables in your Yarn scripts. When a Yarn script needs to get the value of a variable, it asks the Variable Storage for it; when a Yarn script sets the value of a variable, the Variable Storage is given the value.
Each game has different requirements for how variables are stored, which means that Yarn Spinner doesn't make any assumptions how the information is actually stored on disk. Instead, you can create your own custom Variable Storage script that implements the methods that Yarn Spinner needs.
If you don't have a game save system, you can use the component. This is a simple Variable Storage component that's built into Yarn Spinner.
The In-Memory Variable Storage stores everything in memory; when the game ends, all variables that have been stored are erased.
If you don't connect a Variable Storage to your Dialogue Runner, it will create an In-Memory Variable Storage when the game starts, and use that.
Every game's data storage requirements are different. For this reason, Yarn Spinner is designed to make it straightforward to create your own custom component for managing how Yarn scripts store and load variables in ways that work with the other parts of your game.
Custom Variable Storage components are subclasses of the abstract class VariableStorageBehaviour. To implement your own, you need to implement the following methods:
For a complete tutorial on how to build an entirely custom variable storage system, see .
Canvas Group
The Canvas Group that the Options List View will control. The Canvas Group will be made active when the Options List View is displaying options, and inactive when not displaying options.
Option View Prefab
A prefab containing an Option View. The Options List View will create an instance of this prefab for each option that needs to be displayed.
Last Line Text
A TextMeshPro Text object that will display the text of the last line that appeared before options appeared. If this is not set, or no line has run before options are shown, then this property will not be used.
Fade Time
The time, in seconds, that the Options List View will take to fade in. If this is zero, the Options List View will appear immediately.
Show Unavailable Options
If this is turned on, then any options whose line condition has failed will still appear to the user, but they won't be selectable. If this is off, then these options will not appear at all.
Text
A TextMeshPro text object that will display the text of the line.
Show Character Name
If this is turned on, the Text component will show any character name present in the option. If this is turned off, the character name will not be included.
Audio Line Provider is a Line Provider that fetches localized text for a line of dialogue, as well as a localized AudioClip.
Audio Line Provider will automatically use Addressable Assets, if the Addressables package is installed in your Unity project and the Yarn Project is configured to use Addressable Assets.
Use this Line Provider if you are using the Built-In Localisation system. If you are using the Unity Localisation system, use the Unity Localised Line Provider instead.
Text Language Code
The language that the Audio Line Provider should use to fetch localised text for.
Audio Language
The language that the Audio Line Provider should use to fetch localised audio clips for.
Learn about Dialogue Views, which present dialogue content to the user.
A Dialogue View is a kind of component that receives content from a Dialogue Runner, and presents it to the player. Dialogue Views are how the player sees your game's lines of dialogue, and how they select choices in the dialogue.
A Dialogue Runner can have multiple Dialogue Views. For example, you might have one Dialogue View that's designed to display lines of dialogue, and another that's in charge of displaying options to the player.
If you want a custom dialogue view that can display Night in the Woods-style speech bubbles, or a Mass Effect style dialogue wheel, then check out our premium Unity Add-Ons. They're a great way to support the project, and get some fancy dialogue views into your game. ❤️
Because every game's needs are different, a Dialogue View is designed to be extremely customisable, and you can create your own custom dialogue views to suit the needs of your game.
However, because there are common patterns of how games work with dialogue, Yarn Spinner for Unity comes with some pre-built Dialogue Views that handle common use cases:
Line View is a Dialogue View that displays a single line of dialogue in a text box that's inside a canvas, and shows a button that the user can click to proceed.
Option List View is a Dialogue View that displays a collection of options in a list.
The In-Memory Variable Storage component is a Variable Storage component that stores all variables in memory. These variables are erased when the game stops.
The In-Memory Variable Storage component is intended to be a useful tool for getting started, and to be replaced with a custom variable storage that meets your game's needs.
However, if your game has no need to save and restore game state, then this class can be used in your final game, too.
Debug Text View
A Unity UI Text object that will display a summary of the variables that have been stored in this component. If this is not set, this property will not be used.
You can use this property to display a debug summary of your variables at run-time in your games.
Debug Variables
This area of the Inspector shows a summary of the variables. This works similarly to the Debug Text View property, but the summary is only ever shown in the Editor, and it doesn't require any setup.
Learn about the Unity components that you use when working with Yarn Spinner for Unity.
Yarn Spinner for Unity is made up of a number of components. The most important of these are the Dialogue Runner, which loads and runs your scripts, and the Dialogue Views that show content to your player.
In this section, you'll learn about how to work with each of these.
Unity Localised Line Provider is a Line Provider that fetches localized text and assets for a line of dialogue from a String Table and optionally from an Asset Table, based on the project's current localization settings.
Use this Line Provider if you are using the Unity Localisation system. If you are using the Built-In Localisation system, use the Text Line Provider or the Audio Line Provider instead.
Strings Table
The String Table Collection containing localised line text. See to learn how to populate it with your project's dialogue.
Assets Table
(Optional) The Asset Table Collection containing localised assets. If an Asset Table is provided, then the Unity Localised Line Provider will fetch localised assets for each line, based on the line's ID.
Text Line Provider is a Line Provider that fetches localized text for a line of dialogue, given the user's language.
Use this Line Provider if you are using the Built-In Localisation system. If you are using the Unity Localisation system, use the Unity Localised Line Provider instead.
Text Language Code
The language that the Text Line Provider should use to fetch localised text for.