Learn about Options View, a component used to display an option in an Options List View.
An Option View is an object that the Options List View uses when presenting options. When the Dialogue Runner 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.
Learn about Options List View, a Dialogue View that displays a list dialogue options.
Options List View is a Dialogue View that presents a list of options in a list.
When this view receives options from the Dialogue Runner, it creates an instance of the Option View prefab you specify in the Option View Prefab property, and adds it as a child of the options list view.
Learn about Dialogue Views, which present dialogue content to the user.
A Dialogue View is a kind of node 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.
Because every game's needs are different, a Dialogue View is designed to be extremely customizable, and you can to suit the needs of your game.
However, because there are common patterns of how games work with dialogue, Yarn Spinner for Godot comes with some pre-built Dialogue Views that handle common use cases:
is a Dialogue View that displays a single line of dialogue in a RichTextLabel on a CanvasLayer, and shows a button that the user can click to proceed.
Label
A RichTextLabel node 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.
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 packed scene containing an Option View. The Options List View will create an instance of this packed scene for each option that needs to be displayed.
Last Line Text
A RichTextLabel node 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.
Pallete
An optional MarkupPallete resource. Used to represent a collection of marker names and colours.
Option List View is a Dialogue View that displays a collection of options in a list.
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 with a set of components parented to a Godot Control. 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.
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 RichTextLabel, then the character's name will appear in this object.
If you don't attach a RichTextLabel 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 scene comes set up with a 'Continue' button that calls this method. You can also call this method from code.
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 signal that's emitted 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 RichTextLabel node 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 Control that will be made visible 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.
View Control Path
This Control node will be made visible when the Line View is displaying a line, and invisible when not displaying a line.
Convert Html to Bb Code
If enabled, matched pairs of the characters '<' and > will be replaced by [ and ] respectively, so that you can leverage Godot's RichTextLabel's BBCode. If you need a more advanced or nuanced way to use BBCode in your yarn scripts, it's recommended to implement your own custom dialogue view.
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 Path
A RichTextLabel node 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.
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 write a script that implements the DialogueViewBase interface, and add your script to a node in your scene. You can then add this node to the Dialogue Views list on your scene's Dialogue Runner.
On its own, an empty script implementing the DialogueViewBase interface 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 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.
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 to provide it with a LocalizedLine]object. This object contains the text of the line or option, in the user's current locale.
The provided with the plugin creates LocalizedLine objects for views to display.
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 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.
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.)
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 to indicate 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, implementers 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.
UserRequestedViewAdvancement can be called by any part of your code.
To access the 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.
Two example scenes are provided with Yarn Spinner for Godot: addons/YarnSpinner-Godot/Scenes/DefaultDialogueSystem.tscn and addons/YarnSpinner-Godot/Scenes/RoundedDialogueSystem.tscn.
Many projects ultimately end up needing to write their own custom dialogue view scripts to achieve the desired level of control over line and option presentation, but when first starting to integrate Yarn Spinner with your Godot game, it can be useful to start with the provided example views and modify their appearance and layout. These .tscn files provide a pre-configured LineView, DialogueRunner, and OptionsListView.
To create your modified version, start by navigating to the .tscn file that you would like to base your views on in addons/YarnSpinner-Godot/Scenes/. In this example, we'll use the RoundedDialogueSystem. Right click RoundedDialogueSystem.tscn and select the option "Move/Duplicate to...". Choose the directory in your project that you would like to save your dialogue system to, then click the 'Copy' button.
Be careful not to select the 'Move' button on this step. If you do accidentally move the file instead of copying it, you can move it back by following the same process, selecting addons/YarnSpinner-Godot/Scenes/ as the destination directory.
You now have a duplicate of the original .tscn file. You can rename it to anything you like. Double click your duplicated file to edit it.
Before modifying any styles in your copy of the dialogue system, make sure to right click the StyleBox resource and select 'Make Unique' or 'Save As...'. If you select 'Save As...', chose a directory outside of the addons/ directory to save your modified style. If you don't do this step, any modifications that you make to the styles will be saved to the .tres files in Yarn Spinner for Godot's directory, meaning you will lose these changes the next time you update the plugin.
Keep an eye on the addons/YarnSpinner-Godot directory as you customize your view using version control to ensure the .tres and .tscn files are not being modified.
You can now edit the Controls in your new scene to arrange and style them to your liking. The Controls that your scene contains, such as Panels, RichTextLabels, VBoxContainers, and others, are built-in Godot UI components, so you use the same techniques that you would for any other Godot UI component to re-style them. One way to customize the appearance of your scene is by adding or modifying StyleBox resources on the various components (visible in the inspector for each node under Theme Overrides > Styles). You can also modify the anchor points of the Controls to change their position relative to the screen's edges and center.
It's recommended to become familiar with the fundamentals of working with Godot UI components before attempting to customize your dialogue system.
(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.)