The Welcome sample is the launching point for the Yarn Spinner samples. It doesn't cover anything in of itself, it is a quick tour of every sample.

Welcome has Capsley standing in front of a projector showing slides of each sample in the package. Each sample is clustered into one of four categories:

• Basic

• Presenters

• Extending

• Advanced

The Feature Tour Sample is an ideal starting point for newcomers to Yarn Spinner. It presents a series of conversations along a corridor, each demonstrating a different capability of Yarn Spinner.

Are you ready to navigate this narrative gauntlet?

Features Covered

• Nodes, Lines and Options

• Jumps and Detours

• and

• Storylets

• A Dialogue Interactible component and node-character associations

The feature tour consists of a long corridor with multiple rooms. Each room contains one or more interactive characters, with each character showcasing a specific Yarn Spinner feature. While this sample doesn't demonstrate every Yarn Spinner capability, it covers the most commonly used ones.

At the heart of this feature tour is a class, Dialogue Interactible. This component is attached to each interactive character and associates a specific dialogue node with that character. If you're curious about how a particular feature works, you can identify which node contains that feature through this component.

For example, if you want to see which node provides dialogue for a specific character, select that character in the scene and examine the Dialogue Interactible component.

In this example, we can see the node is Room4_Variables_2. Since all dialogue in this sample is contained in a single file (Tour.yarn), you simply need to open that file and locate the node to understand its implementation.

Yarn Spinner for Unity ships with a range of samples covering common patterns for things you might want to do in your game.

Adding the Samples Package to a Project

To install the Yarn Spinner for Unity Samples, you'll need to have a Unity project with Yarn Spinner for Unity installed, so head over to Installation for Unity first.

Once Yarn Spinner for Unity is installed, you can install the Yarn Spinner for Unity Samples Package.

The best way to install the samples is to use the Samples button on the inspector of any Dialogue Runner, Yarn Project, or Yarn Script, or by choosing the Window menu -> Yarn Spinner -> and clicking Install Samples Package.

Clicking on this will work out the best way to install the samples depending on how you installed Yarn Spinner itself.

Manually Installing the Samples

While the best way to install samples is the above, depending on your environment and device setup this might not be possible. In those circumstances you will need to manually install the samples, which is what this section is about.

How you manually install the Samples depends on how you installed Yarn Spinner:

Once the Yarn Spinner Samples package is installed in your project, you can install each individual Sample by opening the Unity Package Manager through the Window menu -> Package Manager, and locating the samples.

To use each sample, locate the "Packages - Yarn Spinner Pty Ltd" section of the sidebar, and then the "Samples" tab.

If you cannot locate the Samples tab, ensure that you are looking at the entry for "Yarn Spinner Samples" under the "Packages - Yarn Spinner Pty Ltd" heading, not under the "Packages - Asset Store" heading (even if your copy of Yarn Spinner for Unity and Yarn Spinner Samples comes from the Asset Store).

To work with each individual Yarn Spinner for Unity Sample, click the Import button next to the Sample that you want to install, inside the Unity Package Manager. For example, to add the sample to the project, click its Import button:

You'll find the Sample in the Project pane:

You can open the Unity Scene (in this case Main) to explore the sample.

• - a small scene in which a character explains Yarn Spinner's inbuilt samples and what each of the others include.

• - walks through the various major features of Yarn Spinner.

• - demonstrates the creation of pools of lines or nodes which can be drawn from based on current game state to deliver dynamic, contextual content.

• - demonstrates basic customisation of dialogue views with a custom font, view background, and continue button texture.

Storylets and Saliency are a new feature of Yarn Spinner 3 that has quite a few different pieces to making it work. Because of this we have multiple samples dedicated to demonstrating these.

The samples are not about the concept of storylets and saliency, if you are new to this and wondering what this all means, then we highly recommend our Storylets and Saliency Primer.

The samples assume you are comfortable now with both the concepts of storylets and salient content and writing them in Yarn Spinner.

There are three samples around using storylets and saliency in Yarn Spinner for Unity:

• Basic Storylets and Saliency goes over the basics of using storylets in your games

• looks at how you can create custom saliency strategies

• demonstrates using storylets and interpolation together to build entire dynamic stories and events.

Yarn Spinner 3 introduced a new system for selecting which content should be presented next, called Saliency Strategies. Whenever it's time to select the next piece of salient content from node groups or line groups, Yarn Spinner consults its saliency strategy to determine which piece should be chosen.

This guide explores an implementation provided in our Custom Saliency Strategies Sample.

While we provide several built-in saliency strategies that cover common scenarios, we can't anticipate every possible need. That's where custom strategies come in, which is the focus of this sample. We'll demonstrate how to create a new custom saliency strategy to meet specific requirements.

What we'll be covering

• Creating new saliency strategies through the IContentSaliencyStrategy interface

• Reading line metadata

• Reading node headers

The IContentSaliencyStrategy interface requires implementing just two methods: QueryBestContent and ContentWasSelected.

• QueryBestContent: Called when Yarn Spinner asks, "If I were to run this block of content, what would be selected?"

• ContentWasSelected: Called when Yarn Spinner informs the strategy, "This specific piece has been chosen"

When Yarn Spinner needs to select a piece of salient content, it first asks its strategy what content would be selected (QueryBestContent) and then selects it and informs the strategy of this selection (ContentWasSelected).

You might wonder why this functionality is split into two methods, especially when the first call is often immediately followed by the second. For many saliency strategies, it won't matter - querying and selecting can effectively be the same operation, with the only required state being the list of content to analyze.

However, other strategies require maintaining state that would be affected if selection and querying were combined. For example, the built-in "Best Least Recently Viewed" strategy tracks which content it has shown previously to avoid showing the same piece of content twice in a row. Each time it selects content, it marks it as seen, which deprioritizes that specific content for future selections.

This design creates a clear separation: QueryBestContent is non-mutating, while ContentWasSelected can modify state. The alternative would be to prevent querying available content altogether, but this would be too limiting - it would prevent you from checking whether content is available, which might be useful for showing indicators that an NPC has something to say.

The sample includes a custom saliency strategy in WeightedSaliencySelector.cs. This strategy assigns a custom weight to each storylet, as specified by the writer, and uses these weights to determine the probability of each storylet being shown.

Each piece of salient content is given a range proportional to its weight, and then one is chosen randomly from the combined range of all weights. In practical terms, given the following line group:

"I am line A" will be shown approximately two-thirds of the time, while "I am line B" will appear approximately one-third of the time.

When asked for the best content, the strategy first filters out any content with failing conditions. After this filtering, we're left with content where all conditions (line conditions or when headers) have evaluated to true. The next step is to determine the weighting for each piece of content.

Our weighted saliency strategy supports both line groups and node groups, which require slightly different approaches:

For node groups, we look for the weight header in the node headers:

For line groups, we look for the weight tag in the metadata:

Once we have the string values for weights, we convert them to integers. If the conversion fails, or if there isn't a weight value in the headers or metadata, we assign a default weight of one.

With the weights established, we build a list of ranges representing those weights. Finally, we generate a random number within the combined size of all ranges and use that to select which content to present.

Yarn Spinner version 3 introduces a powerful new way to trigger events during dialogue presentation. While previous versions required custom implementations for in-line actions, v3 provides the IActionMarkupHandler interface. This system notifies handlers about key line presentation events, enabling you to respond at specific moments.

This approach offers tremendous flexibility for creating various inline events. Our sample demonstrates two practical applications: character movement and facial expression changes during dialogue presentation.

This guide explores the contents of the Inline Events Sample.

What we'll be covering

• The new IActionMarkupHandler interface

• The new ActionMarkupHandler class

• Using these with the Line Presenter to trigger events

• Two implementations: character movement and animation changes

The IActionMarkupHandler interface provides a structured approach to handling in-line actions during dialogue presentation. At its core, the system works by having the Line Presenter display dialogue one character at a time, notifying handlers throughout the process. This creates multiple opportunities to trigger events at precise moments.

The interface defines methods corresponding to different stages of the line presentation lifecycle:

1. Initial Preparation (OnPrepareForLine): Called immediately after the line is received but before any UI elements appear.

2. Display Start (OnLineDisplayBegin): Called just before characters begin appearing, but after UI elements are visible.

3. Character Display (OnCharacterWillAppear): Called each time a character in the line is about to be displayed.

Notably, OnCharacterWillAppear is an asynchronous method. The line presentation system will await each Action Markup Handler's completion before continuing, allowing events of any duration to occur at any point in the dialogue.

Yarn Spinner also provides ActionMarkupHandler, a MonoBehaviour implementation of this interface, for situations where you need component-based functionality. The Line Presenter includes a serialized field for directly connecting ActionMarkupHandler subclasses, as demonstrated in our sample.

Our sample showcases two types of action markup: moving the player character and changing NPC facial expressions. Both are implemented as ActionMarkupHandler subclasses and connected to the Line Presenter through its Event Processors field.

The movement implementation resides in the MoveEvent.cs file as an ActionMarkupHandler subclass. Most of the functionality is contained in the OnPrepareForLine method.

This method scans all markup in the current line, searching specifically for the move markup tag. When found, it extracts the name property from the marker and uses it to locate a corresponding in-scene marker with the same name. The target location and the marker position within the text are stored in a dictionary for later use.

During line presentation, the OnCharacterWillAppear method checks if the current character position corresponds to a stored location. If so, it moves the player character to that position before continuing.

This allows for dialogue lines such as: Player: So what, just part way through I stop talking... [move name="far" /] ...and move on over?

When presentation reaches position 49, it will pause, the player character will move to the GameObject named "far", and then the dialogue will resume.

The facial expression system is implemented in EmotionEvent.cs as another ActionMarkupHandler subclass. The primary logic is also in the OnPrepareForLine method.

This implementation first uses the character name from the dialogue line to find a corresponding GameObject. It then retrieves the SimpleCharacter component (a sample-specific type, not part of Yarn Spinner core) from this GameObject. After these preparations, it processes all markup in the line, looking specifically for emotion tags. The emotion property value is extracted and stored for later use.

During presentation, OnCharacterWillAppear checks if there's a cached emotion corresponding to the current position. If found, it uses this value to change the character's facial expression animation. Unlike the movement example, this change happens instantly without pausing dialogue progression.

This enables dialogue lines like: Alice: Yes... which I would have shown [emotion="angry" /] had you not interrupted me.

When presentation reaches position 32, the facial expression of the "Alice" GameObject will instantly change to whatever animation corresponds to "angry" while the dialogue continues uninterrupted.

The default Dialogue Presenters that come with Yarn Spinner have their own specific look, but they're designed to be re-themed without requiring any custom code.

The Theming Default Presenters sample and guide demonstrates how to modify the built-in line and options presenters to use a sliced sprite and different font for a complete visual overhaul—all without writing any code.

• Modifying existing dialogue presenters

Dialogue in games often extends beyond simple text on screen. Many projects incorporate voice acting alongside written dialogue, and sometimes even more complex assets. This raises important questions about handling localisation—as the number of assets per line increases, so does the complexity of ensuring everything works together seamlessly.

This sample demonstrates Yarn Spinner's approach to localisation, asset association, and audio playback in a cohesive system.

The scene features a character floating in space, conversing with a disembodied voice. The main character's dialogue includes synchronized audio that drives lip movement animations. Unlike most samples, this one includes two identical scenes that differ only in their localisation implementation: one uses Yarn Spinner's built-in localisation system, while the other leverages Unity's Localisation package.

• Associating and playing audio with dialogue lines

There have been several guides and samples about saliency and storylets in Yarn Spinner 3, so why not add one more!?

While previous samples have deliberately limited the amount of dynamic content, the Advanced Saliency Sample explores what happens when you want highly dynamic content within the already dynamic nature of storylets themselves.

• Dynamically building up Yarn content

• Dynamic selection of Yarn content

Yarn Spinner 3 introduced a new system for performing in-line text replacements using markers. Previously, text replacement based on markers was entirely handled by the view displaying the line. In Yarn Spinner 3, we've implemented a cleaner approach with IAttributeMarkerProcessor and the related ReplacementMarkupHandler.

This guide explores the implementation of this in our Replacement Markup Sample.

These components connect directly to the line provider, allowing replacements to occur before the line reaches the views. This simplifies your code architecture and creates a clearer separation of responsibilities. This sample demonstrates four different applications of replacement markup:

1. Built-in common replacements and marker palettes

2. Dynamic markup that changes with each presentation to obscure text

3. Named replacement for in-line content highlighting

4. Injecting sprites and additional text content into a line

• Using Replacement Markup through IAttributeMarkerProcessor and ReplacementMarkupHandler

• Markup Palettes and the built-in replacement processors

• Dynamically replacing text

The IAttributeMarkerProcessor interface is the primary mechanism for creating replacement markup. At its core, replacement markup works by registering with the line provider to handle specific markup tags. During line presentation, when the dialogue runner requests a line from the line provider, the provider calls its registered IAttributeMarkerProcessor instances to process the line.

Whenever a line provider encounters markup for which it has a registered processor, it calls the ProcessReplacementMarker method on that processor. This method receives four parameters:

1. marker: The marker being processed, containing position, range, and properties

2. childBuilder: A StringBuilder containing the text content of all child nodes, which you'll typically modify by adding text to the beginning and end

3. childAttributes: A list of markup inside your markup's children, which you can modify, offset, or even delete as part of your replacement

The method returns a list of LineParser.MarkupDiagnostic objects, which identify any unresolvable errors in the markup. These diagnostics can be displayed in the editor, facilitating easier debugging of invalid markup.

For convenience, we provide an abstract class ReplacementMarkupHandler, a MonoBehaviour that implements the IAttributeMarkerProcessor interface. This class includes a static ReplacementMarkupHandler.NoDiagnostics list for when your processor completes successfully without errors.

Understanding how markup processing works internally can be helpful when creating your own replacement markers. Consider this line in Yarn:

We would expect three markers:

• b marker at position 8, with a range of 7

• b marker at position 21, with a range of 18

• i marker at position 21, with a range of 4

Yarn Spinner first models this as a tree, nesting the i marker inside the second b marker:

This tree structure simplifies manipulation for replacements without manual index and range adjustments. If markup is incorrectly nested, we can rewrite the tree to maintain a valid structure while preserving the same ranges.

To flatten this tree while performing replacements, we traverse it depth-first. When we encounter a markup node with a registered replacement handler, we process it and continue to the next sibling. This ensures that when a replacement processor is called, all of its children have already been processed.

A key benefit of this approach is that each replacement processor can assume its indices start at 0. Since all children have been processed, and the root node handles final assembly and position offsetting, you don't need to know your exact position in the tree. You can trust that your children have been handled, and your siblings' positions will be managed later during final assembly.

As we traverse back up the tree, each completed branch has its siblings' text and markup attributes merged, creating a progressively flattened line.

Once the root node is processed, all replacements are complete and the tree structure becomes irrelevant. The root node simply appends all its children's text into a single line, merges all markup into a single list, and delivers it to the dialogue runner for presentation.

The sample scene includes four different examples, each NPC demonstrating a different aspect of replacement markup.

This example showcases the two built-in markup replacement systems - the only ones in this sample that don't require custom code. It uses markup palettes for basic line styling and the style replacement system for TextMeshPro (TMP) styles.

The Markup Palette provides a straightforward way to add styling to lines. It's a scriptable object that connects a marker name to styling information, allowing you to write Yarn like: Player: Hello, I want this to be [fancy]important looking[/fancy].

Which translates to TMP tags: Player: Hello, I want this to be <color=#00ff00><b>important looking</b></color>.

Markup Palettes support common styles like color, bold, and italics, or you can define custom start and end tags, including offset information for child attributes. You can create your own palettes from Assets -> Create -> Yarn Spinner -> Markup Palette. The dialogue system prefab includes common tags like [b] for bold, [u] for underline, [i] for italics, and [s] for strikethrough.

The code that processes markup palettes is in PaletteMarkerProcessor.cs. It works by creating the appropriate TMP rich text tags based on the palette, prepending opening tags to the childBuilder parameter, and appending closing tags at the end.

The other built-in replacer handles TMP styles. This adds support for any styles defined in a TMP stylesheet. Since we don't know style names in advance, the Yarn syntax looks like: Player: Hello, I want this to be [style=h1]important looking[/style].

The code in StyleMarkerProcessor.cs translates this into appropriate <style> TMP tags.

This example demonstrates using markup with variables to dynamically obscure text. Each time you talk to the character, the amount of obscured text decreases until you can understand the entire line. The obscurity level changes via a Yarn variable interpolated into the markup:

The implementation is in ObscurityMarkupProcessor.cs, which randomly replaces characters with punctuation symbols based on the obscurity level. The processor retrieves the current level from the marker:

In this sample, we defined four obscurity levels: fully obscured, two-thirds obscured, one-quarter obscured, and no obscuration. The code checks if the value is 0, 1, or 2, with any other value resulting in no obscuration.

The actual obscuring happens in the Obscure method, which:

1. Collects the index of every non-whitespace character

2. Shuffles these indices (so different characters are revealed as obscurity decreases)

3. Uses the obscurity factor to determine which characters to replace with random punctuation

This example demonstrates replacement markup where the replacement is based on the child text rather than the markup itself. The processor reads the child text inside a marker and uses it to determine what color to apply to that section.

The design philosophy is that the writer has already included the context for highlighting - the character's name. This allows writing:

Instead of needing to specify:

Of course, there are cases where an explicit property is needed:

The implementation is in EntityColourer.cs. The processor handles both cases by first checking for an explicit property:

If none exists, it uses the child text content:

With the name determined, it performs a lookup in a name-to-color mapping and applies TMP color tags:

This example shows how to add new text and elements (specifically sprites) to a line. Marked regions are flagged as a specific type, gaining both a sprite and color when processed:

The implementation in SpriteReplacmentMarkerProcessor.cs is quite straightforward. It defines format strings for TMP rich tags:

It then uses a switch statement on the marker name to fill in the format strings:

Since this adds visible elements at the start of the markup text (the sprite and [ character), the processor must offset any attributes within that markup:

This shifts attributes down by two positions to accommodate the added characters.

One of the best ways to make a game's world come alive is to have characters engage in conversations with each other, not just with the player character. The Background Chatter sample demonstrates how you can use Yarn Spinner to create and manage these ambient conversations.

Running Multiple Dialogue Runners

The Dialogue Runner is the core component that manages dialogue interactions in your scene. When a node runs, the Dialogue Runner sends lines and options to its Dialogue Presenters.

The Line View and Option View presenters in the built-in prefab are designed to be modal - they take center stage, assuming they have the player's full attention. During these conversations, the player is typically not moving around or performing other actions.

Background conversations, however, are non-modal: they happen while the player continues to explore and interact with the world. The player doesn't participate in these conversations, which proceed independently.

The most effective approach for implementing background conversations in Yarn Spinner is to create separate Dialogue Runners for each conversation. This approach offers several advantages:

• Each background Dialogue Runner can have dedicated Dialogue Presenters designed specifically for ambient conversations

• Background Dialogue Runners operate independently from the main "primary" Dialogue Runner

• You can manage multiple simultaneous background conversations as needed

All Dialogue Runners in your scene can share the same Yarn Project and Variable Storage, maintaining a consistent dialogue state.

Line Presenters for background conversations have different requirements than those used for primary player interactions. These presenters should:

• Make it clear that dialogue is taking place

• Remain unobtrusive enough to avoid interfering with the player's focus

• Usually avoid presenting options, since background conversations don't assume active player participation

Since your game might feature multiple simultaneous conversations, we recommend creating one Dialogue Runner for each conversation in your scene, allowing them to run in parallel.

The BackgroundChatter sample demonstrates how to create an environment where the player can move freely while hearing ambient conversations in the background.

To play the sample, open the BackgroundChatter/Main.unity scene and press play. Use the WASD keys to move around and the Space key to initiate conversations with characters.

The sample features a sequence of background conversations, each demonstrating different aspects of this system. Explanation characters (identifiable by their ties and coffee cups) stand near each demonstration. Speaking with them provides details about what each conversation demonstrates.

In this sample, each background conversation is represented by a "Chatter Group" - a spherical volume in the game world that can trigger a specific dialogue node when the player enters it. Each Chatter Group contains:

• A Canvas with custom Line Presenters

• Text elements that float above speaking characters

• Player position tracking that cancels dialogue when the player leaves the volume

The Chatter Group Manager runs each Chatter Group on a timer, so that while the player remains within a group's volume, that group can potentially initiate dialogue.

The basic background conversation demonstrates a simple exchange between two characters. This conversation runs normally and cannot be interrupted by player actions.

The procedural conversation demonstrates using two line groups to create a dynamic back-and-forth between characters. The first line group contains only questions, while the second contains generic replies that work with any question. This approach allows you to create numerous possible conversation combinations with minimal writing effort.

The interruptable conversation demonstrates how players can interrupt characters engaged in a background conversation. While these characters participate in their ambient dialogue, they remain interactable. When the player initiates interaction, the background conversation pauses to prevent overlap with the primary dialogue. After the player's conversation concludes, the background conversation resumes.

This example shows how players can participate in what begins as a background conversation. When the player approaches the character, a conversation starts with the player as a participant. If the player leaves the Chatter Group's volume, the conversation ends and triggers an additional dialogue node. This allows the player character to deliver a parting line rather than abruptly ending the conversation.

This example demonstrates how background conversations can access variable storage and other Yarn Spinner features. When the player passes by these characters repeatedly, they progress through different parts of an ongoing conversation. This continuity is achieved by using a variable that updates each time the conversation runs.

The marketplace scene showcases background conversations in a more gameplay-oriented scenario. As you explore this area, you'll encounter various types of background conversations demonstrated elsewhere in the sample.

Yarn Spinner 3 introduced storylets, a powerful new way to select which content should be presented to players.

Storylets allow you to break your narrative into modular chunks, with a saliency strategy determining which chunk should run next based on game state and other factors.

Yarn Spinner provides two different approaches to storylets, Node Groups and Line Groups, along with several Saliency strategies to fit your specific needs.

This guide focuses on getting you comfortable with the basics of storylets in Yarn Spinner.

What we'll be covering

• Writing node group storylets

• Writing line group storylets

• Calling salient content

• Interacting with generated variable storage systems

Our Basic Storylets and Saliency Sample demonstrates various things you can do with storylets in Yarn Spinner:

• Content for three in-game days (Monday, Tuesday, and Wednesday)

• Two time periods each day (morning and evening)

• A time advancement mechanic in the center of the scene

• Several characters showcasing different approaches to storylets

The time advancer controls what day and time the NPCs respond to. Each time you press the button, time advances one step through the sequence:

• Monday morning → Monday evening → Tuesday morning → and so on.

• When reaching Wednesday evening, it wraps back to Monday morning

The implementation is straightforward: when you collide with the trigger, it calls the AdvanceTime() method and updates the plinth label via UpdateLabel().

Both methods work by reading and modifying Yarn variables ($day and $time) through a generated variable storage class.

Yarn Spinner allows you to generate a variable storage class that provides convenient wrappers around your declared variables. The system automatically regenerates this file whenever you change your Yarn files or project settings.

This creates two properties on the class—Day and Time—which you can access directly in your code. The Yarn Spinner-generated code:

• Handles all standard variable storage lookup operations

• Performs type checking automatically

• Significantly reduces the amount of code you need to write

• Generates enums matching the types defined in the Setup node

Each NPC in the scene demonstrates a different aspect of storylets through their DialogueInteractible component.

This component determines which node runs when the player interacts with the character.

The component pulls available nodes directly from the attached Yarn project. When triggered, it simply tells the DialogueRunner to run the selected node—just like if you wrote <<jump npc_name>> in your Yarn Spinner Script.

Each NPC runs a single entry node, and the storylets system handles the rest. But how do storylets actually work in practice?

While storylet implementation depends heavily on your specific narrative needs, our sample focuses on a common use case: NPCs making contextual comments based on the current day and time.

This example functions as a "barks" demo—short, reactive dialogue lines—which provides an excellent introduction to storylets and salient content. Each NPC demonstrates a different approach to storylets, all defined in the BasicSaliency.yarn file.

George demonstrates the simplest approach using .

Each line in a block that starts with => represents one potential candidate for selection in that line group. Yarn Spinner chooses only a single line to present each time the line group is reached.

George's dialogue includes:

• Two generic lines with no conditions (can run anytime)

• Three conditional lines that filter based on the current day

• One line with nested content that runs if that line is selected

For example, the line => another Monday, I hate Mondays <<if $day == .Monday>> will only be shown if the current day is Monday.

Liz demonstrates with the "always" condition.

A node group consists of multiple nodes sharing the same title. When selecting which node to run, Yarn Spinner examines the when headers to determine what should be shown.

Liz's nodes all use the when: always header, indicating they're always valid choices. This special header is particularly useful for fallback content.

One of Liz's nodes uses another special header, when: once, which tells Yarn Spinner this node should only be shown once. After being selected, it will never appear again—perfect for character introductions or one-time events.

Barry also uses node groups, but with conditional expressions in the when headers.

Each of Barry's nodes checks the time of day using expressions like when: $time == .Morning or when: $time == .Evening. This means that every time you talk to Barry, half of his potential dialogue nodes are filtered out based on the current time.

This approach lets you easily filter nodes to present only content appropriate to the current game state.

Alice demonstrates the most specific approach with multiple when conditions.

Each of her nodes contains multiple when clauses, creating highly specific combinations of day and time conditions. This gives Alice the most contextually appropriate responses but requires the most content creation.

This highlights an important tradeoff: greater specificity requires more storylets. However, this is also a strength of the system. You can:

• Use fallback storylets (like Liz's) for situations that don't need specific responses

• Omit storylets for combinations where characters have nothing important to say

• Create a more precisely woven narrative landscape with less effort than traditional approaches

Most NPCs in our sample use node groups, meaning their nodes share the same title. While this would normally cause an error in Yarn Spinner, it's intentional with storylets.

Any nodes with the same name become part of the same node group. When that group is requested to run, Yarn Spinner selects one node to present.

Important requirements for node groups:

1. Each node in the group must share the same title

2. Every node must have at least one when header to be recognized as part of a group

3. If you don't have specific conditions, use when: always as a fallback

Learn more about .

With multiple potential storylets available, how does Yarn Spinner decide which one to show?

This is handled by the saliency strategy, which selects the most appropriate content while resolving ambiguity.

The default strategy (used in this sample) is "Random Best Least Recently Seen," which:

1. Removes any storylets with failing conditions

2. Counts the conditions on each viable storylet to determine its "complexity"

3. Selects the storylet with the highest complexity (most conditions)

4. If multiple storylets tie for complexity, deprioritizes any that have been recently seen

This approach typically provides the best experience in most narrative situations, balancing specificity with variety. Yarn Spinner includes other built-in strategies, and you can create custom strategies for precise control over content selection.

Storylets provide a flexible and powerful way to organize narrative content in Yarn Spinner. By breaking your story into modular chunks and using saliency strategies to select the most appropriate content, you can create dynamic, responsive narratives that adapt to your game state.

Whether you're implementing character barks, branching dialogues, or more complex narrative systems, storylets offer a streamlined approach to creating engaging, reactive stories in your games.

This sample demonstrates how to create a custom dialogue presenter where dialogue options include a timeout bar. When options are presented, the timeout bar gradually shrinks. If the player doesn't select an option before the timer expires, the system automatically selects one for them.

The sample supports three variations of this functionality:

• A hidden option that gets selected when time runs out

• A visible option designated as the default that gets selected when time runs out

• The currently highlighted option gets selected when time runs out

For simplicity, this guide focuses on implementing the first approach. To explore the other methods, check out the full sample.

• Custom Dialogue Presenters

• Using Metadata to control views

• The nightmare hellscape that is Unity UI

If you want to see a finished version of this go to PATH TO SAMPLE.

If you haven't already install Yarn Spinner link to install guide. Once installed we will start by building out a basic scene.

1. Make a new scene in Unity.

2. From Samples/Shared Assets/Prefabs drag the Basic Arena into the scene

3. From Samples/Shared Assets/Prefabs add a Camera Rig into the scene

Replace the contents of the Alice Yarn script with the following:

This script contains a single node with three options. Only the first two will be visible to the player. The third option (marked with the #fallback metadata) will be hidden but selected automatically if the timer expires before the player makes a choice.

1. Select the Camera Rig and in the inspector drag the Player into the target field

2. Select Alice and in the Inspector set the Dialogue field to use the new Timeout Dialogues project

3. Select Alice and in the Inspector select the Alice node in the dropdown

4. Select Alice and in the Dialogue Runner field drag in the Dialogue System object from the hierarchy

At this point, you can talk to Alice and go through the dialogue, but the timeout functionality isn't implemented yet. Now we'll create our custom presenter by building a UI bar that shrinks over time, then develop a custom dialogue presenter that uses it.

First, we'll create the UI elements for our timer by modifying the existing canvas from the Dialogue System prefab.

1. Right click on the Dialogue System in the hierarchy and choose Prefab -> Unpack Completely This will disconnect this from being a prefab but will otherwise leave it in the state we want.

2. Expand the Dialogue System out in the hierarchy so we can see all the individual components we are interested in the children and grandchildren of the Option View gameobject.

3. Select the Last Line game object and delete it. While we could handle also showing the last line it would just add more logic to our view while not actually showing off the main feature of this sample. So instead we'll just drop it.

This bar will shrink as the time to select an option runs out.

Our UI work is now complete. Next, we'll write the code to make the bar shrink over time.

1. Create a new monobehaviour script and name it TimeoutBar.cs

2. Open up the new file and replace the imports with the following:

1. Add the following fields to the class:

These fields represent the bar UI element and its original size, which we'll use to reset it between option sets.

1. Replace the Start method with the following:

When Unity initializes the component, we store the default bar size in originalSize for later reference.

1. Add the following new method:

This method resets the bar to its original size. There are several ways to accomplish this, but using SetSizeWithCurrentAnchors is straightforward and lets Unity handle the rectangle's final dimensions.

1. Add the following new method:

This method gradually shrinks the bar over the specified duration. It first verifies that the bar exists, then enters a loop that continues until either the duration elapses or cancellation is requested. Each iteration updates the bar size using linear interpolation from its current size toward zero. After the loop, we ensure the bar is fully shrunk regardless of how it exited the loop.

1. Add that class as a component to our bar

2. Drag the bar gameobject into the Bar field in the TimeoutBar inspector and now the bar is done.

To see a complete version of this check out path to the file in the samples.

Now we'll create the custom dialogue presenter subclass. Since this involves substantial code, we'll approach it in sections.

1. Create a new presenter subclass Assets -> Create -> Yarn Spinner -> Create -> Dialogue View Scriptand name it TimeoutOptionsView. This creates a stubbed out subclass with all the necessary methods for a custom view.

2. Replace the imports with the following:

1. Add the following fields to the class:

These fields reference the UI elements we need to manage: the canvas group for fade effects, the option item prefab, the timer bar, and a list to cache option items. Other than timedBar, these are similar to what you'd find in the default options presenter.

1. Add the following fields to the class:

These fields control the timing aspects: how long the player has to select an option before timeout, and the duration of fade-in and fade-out animations.

1. Add the following field to the class:

This constant identifies the option that should be selected when the timer expires. We'll use it later when examining option metadata.

1. Replace OnDialogueStartedAsync with the following:

1. Replace OnDialogueCompleteAsync with the following:

These methods are called by the dialogue runner at the beginning and end of dialogue. Both hide and disable the options UI, then return a completed task.

1. Replace RunLineAsync method with the following:

Since this presenter only handles options, we can return immediately when asked to run a normal line.

1. Replace Start with the following:

Similar to the dialogue event handlers, we initialize the UI as hidden and non-interactive.

Finally add a new internal enum to the class:

This enum identifies which timeout behavior we're using. The default is None, meaning no timeout is needed for the current option set.

Now we'll implement the RunOptionsAsync method, starting with determining which timeout option to use and validating the option group.

1. Inside the RunOptionsAsync method add the following code:

These variables will track whether we need a timeout and which option should be selected if timeout occurs.

1. Add the following code:

This code examines all the options to find any with the fallback metadata tag. If it finds one that's available, it marks that option as the hidden fallback to be selected when the timer expires. We also count how many tagged options we've seen for validation purposes.

1. Add the following code:

This validation ensures that if we're using a hidden fallback, we have exactly one option tagged as such, and we've successfully identified which option it is. If either condition fails, we log an error and tell the dialogue runner that no option was selected.

Next, we'll set up the infrastructure to handle completion and cancellation. These mechanisms will be provided to the option items later.

1. Add the following code to create our completion source:

1. Add the following code to create our cancellation source:

These sources work together to handle the two possible outcomes: the player selects an option, or the dialogue is cancelled. Now we'll implement the cancellation handling:

1. Add the following encapsulated method:

This task monitors for dialogue cancellation and ensures proper cleanup by setting a null result on the completion source if needed. This connects the two sources: if dialogue is cancelled, this function sets the completion value on selectedOptionCompletionSource.

Now we'll create and configure the option items to display to the user:

1. Add the following code to instantiate new option items as needed:

This creates just enough option item prefab instances to handle the current option group, reusing any we've already created. The CreateNewOptionView method will be implemented later.

1. Add the following code to configure the option items:

This code configures each option view with its corresponding option data, skipping any that are unavailable or marked as hidden fallbacks. It then selects the first valid option to be highlighted initially.

1. Add the following code to enable or disable the timer bar:

This activates the timer bar only if we're using a timeout option, resetting it to full size and ensuring it appears at the bottom of the option list.

Now we'll display the UI to the player:

1. Add the following code to fade in the UI:

This fades in the UI and enables user interaction once the fade is complete.

1. Add the following code to start the timeout bar if needed:

If we're using a hidden fallback option, this starts the timer that will eventually select it. The BeginDefaultSelectTimeout method will be implemented later.

1. Add the following wait code:

This suspends execution until the player selects an option, the timer expires, or dialogue is cancelled.

After a selection is made, we need to clean up and exit:

1. Add the following code:

This cancels the completion source to prevent further selections and disables UI interaction.

1. Add the following code to fade out the UI:

This fades out the UI and hides all option views, though they remain cached for future use.

1. Add the following code to return the selected option:

This returns the selected option to the dialogue runner, or indicates that no option was selected if dialogue was cancelled.

Now we need to implement the methods we've referenced but haven't defined yet:

1. Add the following new method:

This creates a new option item instance, adds it to the canvas group, positions it at the end of the list, and disables it by default.

1. Add the BeginDefaultSelectTimeout method:

This method initiates the timer bar shrinking animation. When complete (if not cancelled), it sets the designated fallback option as the selected choice.

Finally, let's hook everything up in Unity:

1. Move back over to Unity and select the Options View in the hierarchy.

2. Add the TimeoutOptionsView.cs script as a new component to the Option View gameobject.

3. Delete the Options Presenter component.

Now we need to tell the dialogue runner about our custom presenter:

1. Select the Dialogue System game object in the hierarchy.

2. Remove the old (now missing) Options Presenter from the Dialogue Views field.

3. Add the new timeout options view into it's place.

1. Take it for a spin!

Congratulations! You've created a custom options presenter that supports timed dialogue choices. When the timer expires, the system automatically selects a predefined fallback option, adding a sense of urgency to dialogue interactions.

Phone Chat

The Phone Chat sample demonstrates how to create a Dialogue Presenter that shows conversations in a scrolling view, similar to how messages on a phone look.

Lines of dialogue are shown as bubbles in the scrolling view, and are kept on screen after they're delivered, allowing the user to look up and see previous messages. Additionally, as lines appear, they're shown with a "typing" indicator.

In this tutorial, you'll build a Dialogue Presenter that looks like this:

You can find a completed version of this project as part of our Samples.

Creating the Project

We'll start by creating a new empty Unity project, and adding Yarn Spinner.

1. Open Unity Hub.

2. Click New Project, and create a new project. In this tutorial, we'll use the Universal 3D template, though the template itself doesn't really matter.

3. Follow the steps in to install Yarn Spinner in your project.

Next, we'll download the assets needed by this tutorial.

1. Download the assets for this tutorial, and import them into your project.

We're ready to start creating our scene!

Now that we've created the project, we'll begin by laying out the UI. We'll start from an empty scene, and build a canvas that will present the Phone Chat system.

1. Open the File menu, and choose New Scene. Select the Empty template.

2. Save the new scene somewhere in your project.

In our empty scene, we'll start by creating the camera that you view the scene with.

1. Create a new camera by opening the GameObject menu and choosing Camera.

2. Select the new camera, and in the Inspector, right click the Transform, and choose Reset.

Next, we'll create the canvas that the Phone Chat Presenter appears in.

1. Open the GameObject menu, and choose UI -> Canvas.

2. Select the new canvas in the Hierarchy, and find the Canvas Scaler component.

3. Set its UI Scale Mode to "Scale with Screen Size".

4. Set its Reference Resolution to 1920 by 1080.

We're now ready to start building the UI itself. The most important part of a scrolling chat view is the scroll view, so let's create that!

1. Open the GameObject menu, and choose UI -> Scroll View.

2. Select the newly created Scroll View in the Hierarchy.

3. In the Inspector, find the Transform component.

4. Set the Pos X and Pos Y values to 0,0.

Our scroll view won't need any scroll-bars, so we'll get rid of them now. We'll also set up the scroll view so that it only scrolls vertically.

1. Select the Scroll View object in the Hierarchy.

2. In the Inspector, find the Scroll Rect component.

3. Select the Horizontal Scrollbar field, and press Backspace to clear it. Do the same thing for the Vertical Scrollbar field.

4. Turn off the Horizontal checkbox, so that it doesn't scroll horizontally.

Next, we'll set up the scroll view to use our background image.

1. In the Inspector, find the Image component.

2. Change the Color property to fully opaque white.

3. Change the Source Image property to the BG-Lightmode sprite.

Because we removed the scroll bars, we'll need to make the viewport of the scroll view fill the available area:

1. Select the Viewport object in the Hierarchy.

2. In the Transform component, set the Left, Right, Top and Bottom values all to 0.

We're almost done setting up the scroll view. The next thing to do is to make the content in the scroll view appear at the bottom of the view. We'll do this by setting up the Anchors of the Content view so that it's pinned to the bottom of its parent. This means that as bubbles get added to the Content object, the content object will grow upwards (rather than downwards).

1. Select the Scroll View -> Viewport -> Content object in the Hierarchy.

2. Find the Transform component in the Inspector.

3. Set the Anchors -> Min to X: 0, Y: 0.

4. Set the Anchors -> Max to X: 1, Y: 0.

We'll now make all of the content in the Scroll View automatically laid out in a vertical list.

1. With the Content object still selected, click Add Component at the bottom of the Inspector.

2. Search for "Vertical Layout Group", and add one to the object.

3. Set the new Vertical Layout Group's Spacing to -10.

4. Set its Child Alignment to Lower Center.

This will cause the items in the list to fill the entire width of the list. The height of each of the elements will be determined by the items themselves, using a component we'll add later.

We'll now also make the content update its own total size based on its contents.

1. Click the Add Component button at the bottom of the Inspector.

2. Search for "Content Size Fitter" and add one to the object.

3. Set the Horizontal Fit of the new Content Size Fitter to Unconstrained.

4. Set the Vertical Fit to Preferred Size.

Next, we'll create the bubble itself.

The goals for the bubble are that the text fits in the available width, and it takes up as much height as it needs given that width. We also want to show a speech bubble image behind the text, and we want that image to only be as wide as the text - it shouldn't take up the full width of the chat view.

This mimics the way that conversations work in popular chat apps: the speech bubble graphic doesn't take up the full width of the row that it exists in.

1. Select the Content object in the Hierarchy.

2. Open the GameObject menu, and choose Create Empty Child.

3. Name the newly created object "Message Bubble".

Because it's a child of the Vertical Layout Group we added earlier, it will automatically take up the full width of the list. We'll also want the bubble to have the correct height, based on the amount of text it has, but because we haven't set up the text component yet, that isn't available. In the meantime, we'll manually set up the bubble to have a fixed height, and we'll replace this later.

1. Select the Message Bubble object.

2. Add a new Layout Element component to the object.

3. Check the Min Height box, and set its value to 200.

We'll now add an object that manages the width of the bubble graphic:

1. Create a new empty child game object of the Message Bubble.

2. Name the new object "Message Content".

3. Add a Layout Element component to it, and set its Min Width to 300.

4. Add a Content Size Fitter component to it, and set its Horizontal Fit to Min Size.

Next, we'll make the bubble be right-aligned inside its content, and fill the entire height of the row:

1. With the Message Content object selected, go to the Transform component.

2. Set the Anchors -> Min to X: 1, Y: 0.

3. Set the Anchors -> Max to X: 1, Y: 1.

4. Set the Pivot to X: 1, Y: 0.5.

Now we'll add the bubble background image itself. We'll add a new object, set up its anchors so that they fill the parent object, and then add the image:

1. Add a new empty child object of Message Content.

2. Name the new object "Background".

3. In the Transform, set the Anchors -> Min to X: 0, Y:0.

4. Set the Anchors -> Max to X: 1, Y:1.

Your view should now look like this:

Now we'll add the text component, which will show the text of the image. The text object's anchors will be set up so that they're pinned to all for edges of the container, making it fill up the parent object.

1. Add a new empty child object of Message Content. Name it "Text".

2. Set its Anchors -> Min to X:0, Y:0.

3. Set its Anchors -> Max to X:1, Y:1.

4. Set its Left, Top, Right, Bottom all to 0.

The bubble should now look like this:

The bubble now has the right graphics, but its size could be improved. We'll now add some code that makes the various parts of the bubble correctly sized. To get the best result, we need to think about the overall layout here:

• The Vertical Layout group is controlling the width of the Message Bubble element, and we want to make each Message Bubble control its own height.

• Inside the Message Bubble, we also want the visible bubble to be as wide as it needs to be to show the text, but no wider than that (that is, there should be a gap on the side).

To make this work, we'll create a component that calculates the required size of the text box, and use it in two places:

• The Message Bubble will use it to calculate its height (with its width being driven by the Vertical Layout Group on Content).

• The Message Content will use it to calculate its width (with its height inherited from its parent).

1. Open the Assets menu, and choose Create -> MonoBehaviour Script.

2. Name the new script "UseSizeOfText".

3. Double-click the new script to open it in your text editor.

4. Delete the contents of the file and replace it with this:

This code implements a basic layout element, which is something that the layout system can ask questions of about what size it wants to be. - we'll now add code to it to make it derive its size from the text element.

1. Add the following method to the UseSizeOfText class:

This method takes information describing the text in a TextMeshPro element, calculates the smallest size it needs to be given its constraints, and asks the layout system to rebuild the layout.

Lastly, we need the layout to update whenever the text changes. To do this, we'll make use of the event, which is called immediately before the text in a TextMeshPro component is rendered as a mesh. When this happens, it's likely that our required size has changed, so we tell the layout to update.

1. Add the following methods to UseSizeOfText:

Now that we've built a component that notifies the layout system of the necessary size of the text, we'll use it in our setup.

1. Select the Message Content object in the Hierarchy.

2. Remove the Layout Element component from it.

3. Add a new Use Size Of Text component.

The bubble will resize to fit the width of the text. We now need to make the row take the correct height.

1. Select the Message Bubble object in the Hierarchy.

2. Remove the Layout Element component from it.

3. Add a new Use Size Of Text component.

Your bubble should now look like this:

When you're using a chat app, you see a typing indicator while the person on the other end is typing. Let's set up our chat bubbles so that they can show an animation for a short duration before revealing the text, as though the messages was being "typed out".

The way that the typing animation will look will be three dots, which bounce up and down in sequence.

Our first step will be to set up an object inside the Message Bubble prefab to act as our typing indicator. This object will act as a container for the three dots, so it needs to fill the entire parent object.

1. Create a new empty game object as a child of Message Content. Name it "Typing Indicator".

2. In the Inspector for the Transform component, set its Anchor Min to X:0, Y:0.

3. Set its Anchor Max to X:1, Y:1.

4. Set its Top, Left, Right, and Bottom all to 0.

Let's now add the dots themselves!

1. Add three new empty game objects as children of Typing Indicator. Name them Dot 1, Dot 2, Dot 3.

2. Select all three of the Dot objects you just created.

3. Add an Image component to all of them.

Now that we've set up all of their common properties, we'll lay each of them out.

1. Select Dot 1, and set its Pos X to -25.

2. Select Dot 2, and set its Pos X to 0.

3. Select Dot 3, and set its Pos X to 25.

Finally, we'll set them up so that they bounce up and down while visible.

1. Open the Assets menu, and choose Create -> Animation -> Animation Clip.

2. Name the new animation clip "Typing".

3. Select the new animation clip, and in the Inspector, turn on Loop Time.

4. Drag and drop this new clip onto the Typing Indicator object.

This will create a new Animator Controller that uses this clip, and then add an Animation component to the Loading Indicator that uses the controller.

Next, we'll set up the animation itself.

1. Open the Window menu, and choose Animation -> Animation. (You may want to dock the tab in your Unity editor window, if it isn't already.)

2. Select the Loading Indicator object.

The Animator window should be showing the Typing animation. You can check by looking at the dropdown menu at the top-left of the pane.

1. In the Animator window, Click Add Property.

2. Choose Dot 1 -> Rect Transform -> Anchored Position.

3. Repeat this process for Dot 2 and Dot 3.

By default, the newly created channels will have a keyframe at frame 0, and another at frame 60.

1. Select the keyframe at frame 60 and press Ctrl-C.

2. Move the playhead to frame 30 and press Ctrl-V, to make a copy of it.

We'll now create a new keyframe that represents the high point of each dot's bounce.

1. Move the playhead to frame 15.

2. Click the Record button at the top left of the Animation pane.

3. In the Scene view, drag all three Dot objects up so that their Pos Y is 25.

4. Click the Record button again to leave recording mode.

Now that the dots are moving, we'll adjust the timing so that they bounce up in sequence - first one, then two, then three.

1. Select all of the keyframes for Dot 2 and shift them 30 frames to the right.

2. Select all of the keyframes for Dot 3 and shift them 60 frames to the right.

3. Click the Preview Play button again and watch as they bounce up in sequence.

Looking good!

We're done with our basic bubble. Let's now create prefabs for it.

1. Drag the Message Bubble object from the Hierarchy into the Project tab, creating a Prefab.

This will be our base prefab. We'll create two variants of it: one for each of our two characters.

1. Delete the Message Bubble object from the scene.

2. Select the Message Bubble prefab you just created.

3. Open the Assets menu, and choose Create -> Prefab Variant.

4. Name the new prefab Message Bubble A.

In our phone chat system, we want Message Bubble A to use a green graphic and be right-aligned, and Message Bubble B to use a blue graphic and be left-aligned. Message Bubble A is already what it needs to be, so we just need to make some changes to Message Bubble B. The only things we need to change are the anchors - Bubble A is pinned to the right side, and we'll need to adjust it so that it's pinned to the left.

1. Select the Message Content object in Bubble B.

2. Change its Anchors Min to X: 0, Y:0.

3. Change its Anchors Max to X: 0, Y:1.

4. Change its Pivot to X: 0, Y:0.5.

The bubble will now be aligned to the left of the box, but its background image is pointing the wrong way.

1. Select the Background object in Message Bubble B.

2. In the Transform component, set its Scale X to -1.

The bubble will now be facing the right way. Lastly, we'll make the bubble use a different colour image.

1. With the Background object still selected, change the Source Image in its Image component to Bubble Blue.

The two bubbles should now look like this:

We're all done with setting up these bubbles for displaying text, though we'll return to them later at the very end of this tutorial. Let's apply these changes to the prefab overrides.

1. Select the Message Bubble B object

2. In the Inspector, click Overrides, and then click Apply All.

This will apply these changes to Bubble B prefab variant (without modifying the A variant or the base prefab).

1. Delete the Message Bubble A and Message Bubble B objects from the scene.

Now that we've set up the prefabs for the line views, let's set up the UI for options. When the Dialogue Presenter needs to show options, we'll create a list of buttons that contain the text of each option.

We'll start by creating the object that will contain all of the buttons.

1. Create a new empty object under Content, and call it Options Container.

2. Add a Vertical Layout Component to it.

3. Set its Padding Top to 8, and Padding Bottom to 16.

4. Set its Spacing to 16.

This will create a new item in the scrolling list that is itself a vertical list. Now that we've built the layout for the options, let's create the button itself.

1. Create a new empty object under Options Container, and call it Option Button.

2. In the Transform component in its Inspector, set its Height to 60.

Now we'll add the image for the button. The button image itself will need to fill the entire parent, so we'll set up the anchors to do that.

1. Add a new empty object under Option Button, and call it Background.

2. Set its Anchor Min to X: 0, Y: 0

3. Set its Anchor Max to X: 1, Y: 1.

4. Set its Top and Bottom to 0, and its Left and Right to 20.

Next, the component that shows the text of the option. Again, this will fill the parent.

1. Add a new empty object under Option Button, and call it Text.

2. Set its Anchor Min to X: 0, Y: 0

3. Set its Anchor Max to X: 1, Y: 1

4. Set its Top, Bottom, Left and Right all to 0.

We'll now configure the Text component to try to fit more text on a single line, where needed.

1. Set Text Wrapping Mode to No Wrap, and set Overflow to Ellipsis.

2. Turn on Auto Size, and set its Min Size to 24, its Max to 36, and its WD% to 10.

This will cause it to condense the font slightly if it needs the space, and to shrink the font size if it still needs more space. If it still can't fit the text, it will truncate it with an ellipsis (...) rather than overflow onto a new line. With these settings, an option's text can be about 40 characters long before it truncates.

Finally, we'll add a Button component, which will do two things: it'll make the button change its sprite as the user interacts with it, and it will also (eventually) tell the Dialogue Presenter that the user has chosen this option when clicked or tapped. We'll set up the Button component to change the sprite drawn in the Background object based on the current interaction state of the button.

1. With the Option Button selected, Add a Button component.

2. Set the Transition to Sprite Swap.

3. Drag and drop the Background object into the Target Graphic field.

4. Set Highlighted Sprite to Option-Selected.

Your button should now look like this:

We're all done setting up the visuals of the button. The last step is to turn it into a prefab so that we can instantiate copies of it later!

1. Drag and drop the Option Button into the Project pane to create a prefab.

2. Delete the original Option Button object from the scene.

We're all set to start wiring this UI up to a Dialogue Presenter!

We'll start from the bottom up - we'll create scripts that manage the contents of the bubbles and the option buttons, and then create the Dialogue Presenter to work with these scripts.

Let's start with the code for the bubbles. This will be a simple script that can be told to show some text, or show a typing indicator.

1. Open the Assets menu, and choose Create -> MonoBehaviour Script.

2. Name the new script "ChatDialoguePresenterBubble".

3. Double-click the new script to open it, and replace its contents with the following code.

Now we just need to add this script to our bubbles. Because our Message Bubble A and Message Bubble B prefabs are variants, all we need to do is just add it to the base prefab, and it will appear on all of them.

1. Select the Message Bubble prefab in the Project pane.

2. Click Open at the top right of the Inspector to open the prefab for editing.

3. Add a ChatDialoguePresenterBubble component to the Message Bubble object.

4. Drag and drop the Typing Indicator into the Typing Indicator field.

Next, we'll create and set up the code for the Option Button. This script needs to both show text to the user, and also notify the rest of the system that the button has been pressed.

1. Open the Assets menu, and choose Create -> MonoBehaviour Script.

2. Name the new script "ChatDialoguePresenterOptionsButton".

3. Double-click the new script to open it, and replace its contents with the following code.

Now that the code's been written, we'll add it to the Option Button prefab.

1. Select the Option Button prefab in the Project pane.

2. Click Open at the top right of the Inspector to open the prefab for editing.

3. Add a Chat Dialogue Presenter Options Button component to the Option Button object.

4. In the Button component, add a new entry to the On Click event.

With this, our bubble and button prefabs are ready for use with the Dialogue Presenter!

We're now finally ready to create the Dialogue Presenter itself!

1. Open the Create menu, and choose Yarn Spinner -> Dialogue Presenter Script.

2. Name the new script "ChatDialoguePresenter".

3. Double click the new script to open it in your text editor.

The default Dialogue Presenter template script contains an empty implementation of all of the necessary methods needed to be a Dialogue Presenter. We'll start adding functionality to it, piece by piece.

1. Add the following variables to the ChatDialoguePresenter class.

Our code doesn't need to take any special action when dialogue starts and ends, so we'll replace them with simple methods that just return immediately.

1. Replace the OnDialogueStartedAsync and OnDialogueCompleteAsync methods with the following code:

Now it's time to start building the actual behaviour. We'll implement the RunLineAsync method, which is called when the Dialogue Runner needs to show a line of dialogue to the user. This method will look at the line, figure out which bubble prefab needs to be used, and then adds a copy of that prefab to the list and makes the bubble show the right content.

1. Replace the RunLineAsync method with the following code.

With this done, our Dialogue Presenter is able to show lines of dialogue in the bubble!

We'll now create the Dialogue Runner. Yarn Spinner comes with a simple menu item that creates a basic set of Dialogue Presenter, but because we've already built our own custom UI already, we don't need to use it. Instead, we'll create one from scratch.

1. Create a new empty object called "Dialogue Runner".

2. Add a Dialogue Runner component to the object.

3. Add a new empty game object as a child, and call it "Phone Chat Presenter".

4. Add a ChatDialoguePresenter component to Phone Chat Presenter.

While we're here, we'll also set up the prefabs that will be used for options.

1. Drag the Option Button prefab into the Options Button Prefab field.

2. Drag the Options Container object into the Options Container field.

We're ready to test! Let's create some dialogue and hook it up.

We'll start by creating a Yarn Project, and a single Yarn Script containing some sample dialogue.

1. Open the Assets menu, and choose Create -> Yarn Spinner -> Yarn Project.

2. Name the new file "Phone Chat Project".

3. Open the Assets menu, and choose Create -> Yarn Spinner -> Yarn Script.

4. Name the new file "Phone Chat".

Next, let's write some dialogue.

1. Open the Phone Chat script and replace its contents with the following:

Finally, we'll connect this project up to the Dialogue Runner we made in the previous section.

1. Select the Dialogue Runner object in the Hierarchy.

2. Drag and drop the Phone Chat Project that you just created into the Yarn Project field.

3. Turn on Start Automatically. (Leave the Start Node as 'Start'.)

The very last step is to add our Dialogue Presenter to the Dialogue Runner, so that it receives content and shows it to the user.

1. Add a new entry in the Dialogue Presenters list.

2. Drag in the Phone Chat Presenter object into the new field.

We're finally ready to see it all in action!

1. Click the Play button at the top of the Unity window. The conversation will play out!

This looks good, but there's some room for polish. The first thing to note is that all of the lines use the same bubble, and there's no way to tell who's saying what. Remember that we created two prefabs - the green one that we called 'A', and the blue one we called 'B'. Let's set it up so that lines spoken by character 'A' use our 'A' prefab, and likewise for 'B' and the 'B' prefab.

1. Select the Phone Chat Presenter in the Hierarchy.

2. In the Inspector, click the + button next to the Characters field to add an entry to the Characters dictionary.

3. Set the key of the new entry to "A", and drag the Message Bubble A prefab into the Object slot.

4. Repeat this process, creating a new entry "B" that uses the Message Bubble B prefab.

Lines from "B" will use a different-looking bubble!

We've got lines working just fine, but we don't currently have support for options. Let's fix that! We'll start by adding some actual options to our sample dialogue, and then we'll modify our Dialogue Presenter so that it knows what to do when options arrive.

1. Open the Phone Chat.yarn, and replace its contents with the following:

1. Open the ChatDialoguePresenter.cs file, and replace the RunOptionsAsync method with the following code:

One more thing before we test it out: when the user taps on an option to select it, we'll run the contents of that option as though it had been a line. (Without this, there's no record of what the player selected, which feels strange.)

1. Select the Dialogue Runner in the Hierarchy.

2. In the Dialogue Runner component's Inspector, turn on Run Selected Option As Line.

We're all set to see it in action.

1. Play the game. After the lines appear, option buttons will run!

We're all done with our Phone Chat Dialogue Presenter! Try writing some more complex conversations, swap out the sprites to create a new theme, create new bubbles, or use this code to create a scrolling log of messages that isn't phone themed!