 |
|
Use these instructions to import Yarn 2.x stories into the Dialogue System. If you're using Yarn 1.x, see Yarn Spinner 1.
If you're familiar with Yarn, Unity, and the Dialogue System, importing Yarn stories is fairly straightforward.
One difference to be aware of is that Yarn doesn't explicitly specify actors, but the Dialogue System does. In the Yarn Importer window, you will be able to specify how to interpret your Yarn stories to appropriately assign actors to lines of dialogue.
https://docs.yarnspinner.dev/using-yarnspinner-with-unity/installation-and-setup
The Yarn 2 Importer window looks like this:
^(.+?)\:^.+?\:\s*After setting the fields shown above, click Import to read the Yarn files and create a dialogue database.
Once you've imported your Yarn content into a dialogue database, you can use it like any other content that was generated directly in the Dialogue System.
Built-In Yarn Functions To use Yarn's built-in functions, add the YarnCustomCommands script to your Dialogue Manager GameObject. Or, if you've defined new custom functions, add your custom subclass as described in Implementing Custom Yarn Commands.
Follow the instructions on Yarn Spinner's website: https://docs.yarnspinner.dev/getting-started/upgrading-yarn-scripts
Note that the Yarn Spinner Console (ysc) updates Yarn scripts in-place (overwrites files), unless an output directory for the upgraded scripts is specified with –output-directory.
Upgrading Yarn scripts does not upgrade localized string files. Please refer to the localization documentation on Yarn’s website for the new localized strings file format:
To properly upgrade localized string files, 3 columns need to be added: language, lock, and comment.
Language contains the locale, lock is auto-updated by Yarn and can be left empty, and the optional comment can be anything you want.
The order they need to be added is as follows, old columns are enclosed in square brackets:
language,[id,text,file,node,lineNumber,]lock,comment
For example, Yarn Spinner 1 localization string table looking like this:
id,text,file,node,lineNumber, en-US,line:794945,Line 1,SomeNode.yarn,SomeNode,1 en-US,line:794946,Line 2,SomeNode.yarn,SomeNode,2
Would be upgraded like this for Yarn Spinner 2:
language,id,text,file,node,lineNumber,lock,comment en-US,line:794945,Line 1,SomeNode.yarn,SomeNode,1,,Line 1 comment en-US,line:794946,Line 2,SomeNode.yarn,SomeNode,2,,Line 2 comment
Variable Declarations While not required, it is good practice to initialize all Yarn Script variables with declare statements. Variables can be declared as one of bool, number, or string types. Below is an example Yarn script declaring a variable of each type:
title: DeclareVars
tags:
---
<<declare $var_1 = "test_string" as string>>
<<declare $var_2 = 43 as number>>
<<declare $var_3 = true as bool>>
This is var_1: {$var_1}
This is var_2: {$var_2}
This is var_3: {$var_3}Declare statements can appear anywhere in your scripts, however there should only ever be a single declare statement for each variable. It is often a good idea to create a single Yarn node that contains all variable declarations in the project.
To add Cutscene Sequences to your dialogue, use seq=sequence] tags at the end of a line.
So this is valid:
Some line [seq="Delay(5)"/]
But this is not:
Some [seq="Delay(5"/] line
Line hashtags do not show up as dialogue text, they're metadata, so this is also perfectly valid syntax that works:
Some line [seq="Delay(5)"/] #some_metadata:some_value
The [seq] markup can also be the only thing on a line, so this is valid and identical in functionality to the <<seq>> command:
[seq="Delay(5)"/]
If there's a backslash in front of the [seq] markup tag, it is ignored. So this is ignored:
\[seq="Delay(5)"/]
If your Yarn stories contain any custom commands, use these steps to implement them in Unity:
The Custom Commands File field is where this class is located. The class will always be named YarnCustomCommands. Subclass this and override its RegisterFunctions() and UnregisterFunctions() methods, making sure to call back to the base class' RegisterFunctions() and UnregisterFunctions() in your methods.
Add the script to your Dialogue Manager GameObject.
Commands are registered by associating the command name with a function that implements it. Commands in Yarn are specified like this:
where “my_command” is in the place of your command’s actual name. The next thing to do is write the method that will implement your command’s functionality. In this example, we will write a C# method that prints out all arguments passed to it, and call it MyCustomCommand.
Next enter this line in the RegisterFunctions() method of your YarnCustomCommands subclass, substituting your command name for “my_command”, and your method name for MyCustomCommand:
Finally, the command needs to be unregistered when the YarnCustomCommands classes are unloaded. Enter this line in the UnregisterFunctions() method of your YarnCustomCommands subclass, again substituting your command name for “my_command”:
Your YarnCustomCommands subclass should now look like this: