Pardon our dust! Docs for Yarn Spinner for Unity 3.2 and Yarn Spinner for Godot C# are on docs.yarnspinner.dev (the old docs site). Docs for Yarn Spinner for Unity 3.3, Yarn Spinner for Godot GDScript and Yarn Spinner for Unreal Engine (work in progress) are on /docs/ (the new docs site).

Putting It Together

Commands let your Yarn Scripts tell your game to do something. Functions let them ask your game for a value. The scene below uses both.

In the scene, Rosa hears the door, walks over to the lamp and lights it, then gives the player a key if they don’t already have one. The panel in the top left lists each Command and Function as the dialogue reaches it, with what each Function returned.

The scene running. The panel in the top left lists each Command, and each Function with the value it returned.

The Yarn Script

title: CommandsFunctionsDemo
---
<<play_sound door_creak>>
Rosa: Oh! You gave me a fright.
Rosa: The lamp's been out for {days_since_lamp_lit()} days.
<<move Rosa 640 430>>
Rosa: Let me get it going again.
<<light_lamp>>
Rosa: There. Much better.
<<if not has_item("brass key")>>
    Rosa: You'll need this to get up the stairs.
    <<give_item "brass key">>
<<endif>>
<<if has_item("brass key")>>
    Rosa: Now you've got the key. Up you go!
<<endif>>
===
Line 3 A Command. The game shows “creak!” rising from the door. Rosa’s first line appears while “creak!” is still rising, because this Command doesn’t make the dialogue wait.
Line 5 A Function inside a line. days_since_lamp_lit() returns 12, which is shown in the line.
Line 6 A Command on the node called Rosa. The dialogue waits until she has finished walking.
Line 8 A Command that also waits. The lamp fades on before Rosa’s next line.
Line 10 A Function in a condition. Rosa hands over the key because has_item("brass key") returns false.
Line 12 A Command with an argument in quotes, because it has a space in it. The key appears in the inventory.
Lines 14–16 The same Function again. This time it returns true, because the player now has the key.
The node that runs in the video.

The game code

The script on the scene’s root node adds the Commands and Functions when the scene starts:

func _ready():
	dialogue_runner.add_command("play_sound", _play_sound)
	dialogue_runner.add_command("light_lamp", _light_lamp)
	dialogue_runner.add_command("give_item", _give_item)
	dialogue_runner.add_function("days_since_lamp_lit", _days_since_lamp_lit)
	dialogue_runner.add_function("has_item", _has_item)
Lines 2–4 Three Commands, each connected to a method on this script.
Lines 5–6 Two Functions. Because they’re named methods, the Dialogue Runner reads how many arguments each takes from the method itself.
Adding three Commands and two Functions to the Dialogue Runner.

The Commands are ordinary methods. _light_lamp awaits its tween’s finished signal, which is what makes the dialogue wait for the lamp:

func _light_lamp() -> void:
	var tween := create_tween()
	tween.tween_property(lamp, "color", Color(1.0, 0.85, 0.35), 0.8)
	tween.parallel().tween_property(glow, "modulate:a", 1.0, 0.8)
	await tween.finished


func _give_item(item_name: String) -> void:
	_inventory.append(item_name)
	_update_inventory()
Line 1 <<light_lamp>> calls this. It takes no arguments.
Lines 2–4 Fade the lamp to yellow and the glow in, together, over 0.8 seconds.
Line 5 Wait for the fade. The dialogue carries on once the method returns.
Lines 8–10 There’s no await here, and the dialogue doesn’t wait for it. _update_inventory redraws the inventory.
Two of the Commands. The lamp and glow are ColorRect nodes set in the Inspector.

The Functions return a value, and the Dialogue Runner hands it back to the Yarn Script:

func _days_since_lamp_lit() -> int:
	var days := 12
	_log_function("days_since_lamp_lit()", days)
	return days


func _has_item(item_name: String) -> bool:
	var result := item_name in _inventory
	_log_function('has_item("%s")' % item_name, result)
	return result
Lines 1–4 It returns a number. _log_function writes the call to the panel in the top left.
Lines 7–10 It checks the same inventory that <<give_item>> adds to. Its answer changes once the key has been given.
The two Functions.

<<move>> isn’t added in _ready. It’s a _yarn_command_move method in the script attached to Rosa, which the Dialogue Runner finds by itself:

extends Node2D


func _yarn_command_move(x: float, y: float) -> void:
	var tween := create_tween()
	tween.tween_property(self, "position", Vector2(x, y), 1.0)
	await tween.finished
Line 1 The script goes on the character’s node, which is called Rosa in the scene.
Line 4 A Command on a node, because the method isn’t static. In Yarn, the first argument, Rosa, says which node to call it on. x and y come from the other two arguments, converted to float.
Lines 5–6 Move the node to the new position over one second.
Line 7 Wait for the tween’s finished signal, the same as _light_lamp.
Character.gd, attached to Rosa.

What it shows

Every Command in the scene changes something on screen. The next line waits for <<move>> and <<light_lamp>>, and <<play_sound>> and <<give_item>> return straight away. days_since_lamp_lit() puts a number in a line, and has_item() picks which lines Rosa says.

Next step Variables and Storage Reading and changing Yarn variables from GDScript, and saving and loading them.