(Unity) Advanced Yarn : conditional logic, variables, and special commands

Yarn’s website, Yarnspinner.dev contains basic information on Yarn usage. Give it a look if you have some spare time!

In the following tutorial, you will discover some unique features of the Yarn Dialogue System and editor, in addition to some new special commands allowing your dialogue scripts to control more of your game.

Yarn Variables

Sometimes we would like to “remember” a choice the player has made previously, and provide different dialogue based on this earlier choice. To do this, we use a fundamental programming concept called “variables”.

You can think of a “variable” as a little chunk of storage, where we can place a number, a true / false value, a piece of text (called a string) and more. We may then use this variable in conditional or branching expressions to do different things based on what has been stored inside of the variable.

In order to use variables, we need to make sure our DialogueRunner component has its “Variable Storage” property set up, as shown below–

If this field is “None”, we can fix this by doing the following–

In the Yarn editor, we can create and change what is “inside” a variable via the “set” command, as seen in the example (taken from the Yarn website) below–

In the example above, a variables called “$suspect_steve” has been filled with the value “1”. Note that all variable names begin with a “$” sign. We should always choose descriptive names for our variables so that we don’t forget their purpose and what they store.

Here’s another example–

You may set variables to pieces of text too, not just numbers.

Using Yarn Variables

Once a variable has a value, be it a number or a string (piece of text), we can use it in our dialogue.

As seen above, you can place a variable into a line of dialogue, surround it by curly brackets (“{“ and “}”) and the variable’s value (whatever was stored inside of it) will appear in the line of dialogue itself.

You may also use the “if” command to check the variable’s value and branch your dialogue (choose whether you want a line to execute or not). Check it out–

If the “$favorite_color” variable has a value of “blue”, then all of the lines between the “if” command and the “endif” command will run. If the “$favorite_color” variable is not set to blue, the above two lines won’t run. If we want to run some other lines instead, we can use the “else” command in conjunction with the earlier “if” command.

There are a few other of these “conditional” commands you may read about here.

Special Yarn Commands

The following commands aren’t provided by Yarn itself– they are provided by the course staff, who programmed them for your convenience. In order to get these new commands, you must copy-paste this file into the YarnCommands.cs script in your project (search for it in your project pane), and use a 2020 version of Unity.

Command : wait

Functionality : pauses the dialogue system for the amount of seconds specified. Purpose : Build dramatic / awkward tension or wait for something else to finish before continuing dialogue.

Command : change_scene

Functionality : Change the current scene to a specified scene. Purpose : vary the current location, advance to a new level, or visit a victory / game over screen.

Don’t forget– you’ll need to add any scenes you want to visit to your build settings (File -> Build Settings).

Command : restart_current_scene

Functionality : Restart the current scene. Purpose : This is great for letting a player retry whatever scene, area, or level they are in.

Don’t forget– you’ll need to add your scenes to your build settings (File -> Build Settings).

Command : play_audio_clip

Functionality : Play an audio clip placed into a “Resources” folder in your project. Purpose : Use it for sounds and voice acting.

Note that you should not place your audioclips into any sub-folders within a Resources folder.

Command : play_audio_track

Functionality : Play and loop an audio clip placed into a “Resources” folder in your project, and set a specific volume. Purpose : Use this to control background music tracks, and bring in new layers of music.

Note that you should not place your audioclips into any sub-folders within a Resources folder.

Command : camera_warp_target

Functionality : Move the main camera gameobject to a target gameobject instantly. Purpose : Use this to show your player different things and control their camera. Remember to turn off the “should_look_at_target_during_cutscene” and “should_follow_during_cutscene” checkboxes on your GameplayCamera’s follow_target_heightonly component.

Command : camera_ease_target

Functionality : Move the main camera gameobject to a target gameobject OVER TIME, via a smooth, cinematic ease. Purpose : Use this to show your player different things and control their camera. Remember to turn off the “should_look_at_target_during_cutscene” and “should_follow_during_cutscene” checkboxes on your GameplayCamera’s follow_target_heightonly component.

Command : Quit

Functionality : Quits the game. Purpose : Use this after displaying a victory or defeat message to make the game shut down. You might also consider looping the game by using the “change_scene” command to return to your first scene.

Command : activate_gameobject

Functionality : Makes a gameobject in the scene active. Purpose : Use this to make a gameobject (perhaps an arriving NPC, or a powerup, etc) appear.

Note on usage : You may specify a gameobject name like so–

But if you want to specify a nested gameobject’s name, you’ll need to include the parents’ name too (delimited by forward slashes) like so–

Command : deactivate_gameobject

Functionality : Makes a gameobject in the scene non-active (makes it disappear and stop executing logic, enforcing collisions, etc). Purpose : Use this to make a gameobject (perhaps a wall, NPC, etc) disappear based on dialogue.

Note on usage : You may specify a gameobject name like so–

But if you want to specify a nested gameobject’s name, you’ll need to include the parents’ name too (delimited by forward slashes) like so–

Command : warp_gameobject_position_rotation

Functionality : Moves and rotates a gameobject to the specified position and rotation. Purpose : Use this to make a character move during a cutscene, change their rotation, reveal something, etc.

The first parameter is the gameobject path (“npcs/worma” in this case), then three position values (x, y, z), then three rotation values (xr, yr, zr)–