Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The new Yarn Spinner language features that have arrived in Yarn Spinner 3.
Learn about using line groups, which allow Yarn Spinner to choose which content to run, depending on conditions.
In Yarn Spinner 3, you can now create line groups. A line group is collection of lines that Yarn Spinner will choose from.
Line groups are collections of lines that begin with a => symbol:
When Yarn Spinner encounters a line group, it will select one of the lines in the group and run it.
Line groups are great for running ‘barks’ - collections of short lines that need to run in response to an in-game event. It can be useful to think of them like Yarn Spinner’s existing options -> syntax, but instead of the player choosing which content to run, the computer picks it for you:
You can attach conditions to lines in a line group, to ensure that they only run when it’s appropriate to do so. Conditions can be any true or false expression, and can also be combined with the once keyword to ensure that a line can only run once:
A line in a line group can also have additional lines belonging to it, which will run if the item is selected.
Learn about once statements, which let you specify content that only runs once.
In Yarn Spinner 3, you can use a once statement to run content only one time. When the script reaches a once statement, it checks to see if it’s run before. If it has, it skips over it! Magic.
once statements are great for making sure that the player never sees certain content more than once. For example, you might want a character to never introduce themselves to the player twice.
There are two main ways you can use a once statement, which we'll explore below.
<<once>> and <<endonce>>:You can also use an <<else>> clause within the <<once>> statement, which will be run if the relevant <<once>> content has already been seen:
You can also add an if to the once to run content a single time, but only when a certain condition is true. In all other cases, it will be skipped (or the else content will be run, if there is any):
<<once>> to a line, or options:If you add once (or once if) to a line, that line will only appear once, and will be skipped over every other time it’s encountered:
Similarly, if you add it to an option, that option will only be selectable once, and will be marked as unavailable after it’s been selected.
once statements are really useful when you want to show long, detailed content the first time it’s encountered, but you don’t want to show it every time. This means that players don’t need to mash the ‘skip line’ button over and over when they realise that they’re starting to see a long run of lines they’ve already seen:
once statements keep the information about whether they’ve been run or not in a variable that’s stored in your Dialogue Runner’s Variable Storage, just like any other variable. The variable isn’t directly accessible from your Yarn scripts.
Learn about saliency and saliency strategies, which let you control how line groups and node groups select which content to run.
In Yarn Spinner 3, saliency lets you control how line groups and node groups select which content to run.
When a line group or node group needs to run content, it needs to make a decision about which item in the group to choose. The method for making this decision is called a saliency strategy.
Saliency strategies are provided with the following information about each item:
How many of its conditions passed (that is, the when: clauses on a node group, or the single condition on a line group)
How many of its conditions failed
The total complexity of all of its conditions
Complexity is calculated as the total number of boolean operators (and, or, not, xor) present in a condition, plus 1 if the condition is a once condition. The always condition has a complexity of zero.
A unique key that identifies the content.
You can either use one of Yarn Spinner's built-in saliency stragegies, or create your own custom saliency strategy.
First: The first item in the group that has not failed any of its conditions is selected.
If the items of a node group are all in the same file, the ordering of the group is the order in which they appear in the file. If a node group’s nodes are split up across more than one file, the ordering of the nodes is not defined. the node that is considered ‘first’ is not defined.
Best: The items that have not failed any conditions are sorted by their total complexity score, and the first item that has the highest score is selected.
Best Least Recently Viewed: The items that have not failed any conditions are sorted by score, and then by how many times they have been selected by this strategy. If there is more than one best item remaining, the first of these is selected.
Random Best Least Recently Viewed: The items that have not failed any conditions are sorted by score, and then by how many times they have been selected by this strategy. If there is more than one best item remaining, a random one of these is selected.
A saliency strategy is given a collection of possible options, and returns either one of them that should be run, or null to indicate that none of them should run.
Your C# code can create custom saliency strategies. To do so, create a type that implements the IContentSaliencyStrategy interface, and assign it to your Dialogue object’s ContentSaliencyStrategy property.
IContentSaliencyStrategy has two required methods.
ContentSaliencyOption? QueryBestContent(IEnumerable<ContentSaliencyOption> content) determines which of a collection of options, if any, should run. It should return the best content from the available options, or null if none of them should run. This is the main method in which you write the specific logic for your custom strategy.
Calling this method does not indicate that the content has been selected; rather, it is a query to determine what should be selected. Your implementation of this method should not change any state, and should be read-only. The content returned by this method is not guaranteed to actually be run.
void ContentWasSelected(ContentSaliencyOption content) is called to indicate that a specific piece of content returned by a previous call to QueryBestContent has been selected. This method should update any appropriate state to represent this fact, such as by updating the total number of times the content has been selected.
You can use a node group to check to see if any of its items can run, This can be useful when determining whether to show if a character should be marked as ready to talk, or whether any of its nodes have a special tag (for example, if a character has important information to discuss, as opposed to more general conversation.)
Learn about using node groups, which allow Yarn Spinner to choose which content to run, depending on conditions.
In Yarn Spinner 3, you can now create node groups. A node group is collection of nodes that share the same name that Yarn Spinner will choose from.
To create a node group, you create multiple nodes that all share the same name, and ensure that each of the nodes have at least one when: header.
The when:header tells Yarn Spinner about the conditions that must be met in order to run the node:
Node groups are combined into a single node that performs the appropriate checks and then runs one of the node group’s members. You start dialogue with a node group using its name. You can also use the jump or detour statements to run a node group from somewhere else in your Yarn scripts.
You can have
Learn about detour and return, which let you temporarily move to another node, then return.
In Yarn Spinner 3, you can use a detour statement to run content from a different node, before returning to the previous node.
Here’s an example of using the detour statement.
If the player replies ‘No?’ to the guard’s question, Yarn Spinner will detour to the Guard_Backstory node and run its contents. When the end of that node is reached, Yarn Spinner will return to the Guard node, and resume from just after the detour statement.
When you detour into a node, Yarn Spinner runs the content from that node just as if you’d used a jump statement. When you reach the end of the node, or reach a return statement, Yarn Spinner will return to just after the detour statement.
You can return early from a detoured node by using the return statement. Doing so will return to just after the detourstatement, as though the end of the node had been reached.
If Yarn Spinner reaches a return statement, and it hasn’t detoured from another node, it will stop the dialogue (that is, it will behave as though you had written a stop command.)
When you detour into a node, that node can itself detour into other nodes.
If a detoured node uses a jump command to run another node, the return stack is cleared. If you detour into a node, and that node jumps to another node, Yarn Spinner won’t return to your original detour site.
Learn about using smart variables that determine their value at run-time.
In Yarn Spinner 3, smart variables let you create variables whose value is determined at run-time, rather than setting and retrieving a value from storage.
Smart variables give you a simple way to create more complex expressions, and re-use them across your project.
Smart variables can be accessed anywhere a regular variable would be used:
Learn about creating enums, which allow you to create variables that are constrained to a specific set of values.
In Yarn Spinner 3, enums let you create variables whose value is constrained to a pre-defined list of possibilities.
An enum (short for ‘enumeration’) is useful when you have a variable that needs to have a wider range of possible values than simply true or false, but needs to be more specific than a number or string.
To define an enum you must provide a name, and some cases for it. Here's a new enum called Food with the cases Apple, Orange, and Pear:
Once you've created an enum, you can use it just like any other variable:
Learn about reusing the same line in multiple places, using shadow lines.
In Yarn Spinner 3, shadow lines let you reuse the same line in multiple places, without having to create duplicate copies.
Shadow lines are copies of other lines, but don’t create a duplicate entry in the string table. This can be useful if you want to re-use an existing line in more than one place, which can be important when each line has in-game assets like voice-over recording.
Shadow lines are marked using the #shadow: hashtag. When you use the #shadow: tag, you specify the line ID of another line, which is called the source line. The source line must have an explicit #line: hashtag to identify it.
Here’s a simple example of using shadow lines:
The script contains six lines, but only 5 string table entries will be created, because the line “I should go” is shadowed.
Shadow lines are required to have the same text in the Yarn script as their source line, but are allowed to have different hashtags (in addition to the #shadow: and #line: hashtags).
Node groups are similar to in their behaviour, but give you more room to create longer passages of content. Your C# code can also check to see how many (if any) nodes can run, which is covered in the Saliency section.
To create a smart variable, using the declare statement and provide an expression, rather than a single value:
This version of the documentation () is for the current beta version of Yarn Spinner 3 (Beta 1). For Yarn Spinner 2.x, visit
