Pardon our dust while we move our docs here. The Godot (GDScript) docs are on this site, and the Yarn language, Unity, Godot (C#) and Unreal docs are still at docs.yarnspinner.dev.

Putting It Together

A small scene that uses Commands and Functions together, and what each part of it does.

ESC
↑↓ Navigate ↵ Open esc Close
Connecting to Your Game
1 Commands 2 Functions 3 Putting It Together 4 Variables and Storage 5 Smart Variables 6 Saliency and Storylets 7 Custom Saliency Strategies 8 Async and Cancellation
1 Commands 2 Functions 3 Putting It Together 4 Variables and Storage 5 Smart Variables 6 Saliency and Storylets 7 Custom Saliency Strategies 8 Async and Cancellation

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. It doesn’t make the dialogue wait, so Rosa’s first line appears while “creak!” is still rising.
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. It returns a signal, so 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. has_item("brass key") returns false, so Rosa hands over the key.
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, 0)
	dialogue_runner.add_function("has_item", _has_item, 1)
Lines 2–4 Three Commands, each connected to a method on this script.
Lines 5–6 Two Functions. The last argument is how many arguments each one takes.
Adding three Commands and two Functions to the Dialogue Runner.

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

func _light_lamp() -> Signal:
	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)
	return tween.finished


func _give_item(item_name: String) -> void:
	_inventory.append(item_name)
	_update_inventory()
Line 1 It returns a Signal, so the dialogue waits.
Lines 2–4 Fade the lamp to yellow and the glow in, together, over 0.8 seconds.
Line 5 The dialogue carries on once this is emitted.
Lines 8–10 It returns nothing, so 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, so its answer changes once the key has been given.
The two Functions. _log_function adds the call to the panel in the top left.

<<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) -> Signal:
	var tween := create_tween()
	tween.tween_property(self, "position", Vector2(x, y), 1.0)
	return tween.finished
Line 1 The script goes on the character’s node, which is called Rosa in the scene.
Line 4 It isn’t static, so it’s a Command on a node. 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 Return the tween’s finished signal, so the dialogue waits until the move is done.
Character.gd, attached to Rosa.

What it shows

Every Command in the scene changes something on screen. Two of them, <<move>> and <<light_lamp>>, return a signal, so the next line waits for them. <<play_sound>> and <<give_item>> return nothing, and the dialogue carries on without waiting.

Each Function returns a value the Yarn Script uses: days_since_lamp_lit() puts a number in a line, and has_item() picks which lines Rosa says. The second has_item() check gives a different answer from the first because <<give_item>> has changed the inventory it reads.

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