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 (pre-release, out ASAP), Yarn Spinner for Godot GDScript and Yarn Spinner for Unreal Engine (work in progress) are on /docs/ (the new docs site).

Custom Actions

The custom Commands and Functions in this sample do more than return straight away. A Function waits while the player picks an item from their inventory, and a Command walks a character across the arena, which the player can skip. The Commands and Functions take a FoodType, an enum declared in the Yarn Script.

Hungry Henry asks for an apple, an orange or a blueberry. Walk to the three piles of fruit at the back of the arena to collect some, then talk to Henry again. He shows your inventory and waits for you to choose. If you give him the right fruit, he walks off to eat it and comes back. Capsley, standing beside him, explains what’s going on.

Running it

Open samples/custom_actions/custom_actions.tscn and click Run Current Scene.

  • Walk with WASD or the arrow keys, and press E to talk to a character or take fruit from a pile.
  • Press Space or Enter to move on to the next line. Press it while Henry is walking to skip the walk.
  • When the inventory picker is showing, click a fruit, or use the arrow keys and press Enter.
  • Press Escape at any time to stop the conversation. If you’re picking an item, this cancels the pick, and you keep the fruit.

How it works

CustomActionsNode3D
BasicArena
DirectionalLight3D
GroundStaticBody3D
CameraRigNode3D
Camera3D
VariableStorageNode
YarnDialogueRunner
Hungry Henry
DialogueInteractableNode3D
CharacterAppearanceNode
MarkerNode3D
EatSoundAudioStreamPlayer
Capsley
DialogueInteractableNode3D
AppleVendorNode3D
Model
DialogueInteractableNode3D
OrangeVendorNode3D
Model
DialogueInteractableNode3D
BlueberryVendorNode3D
Model
DialogueInteractableNode3D
PlayerCharacter
CharacterAppearanceNode
UILayerCanvasLayer
LinePresenter
OptionsPresenter
InventoryLayerCanvasLayer
RootControl
InventoryDisplayPanelContainer
InventorySelectControl
custom_actions.tscn.

The script on the root node, scripts/custom_actions.gd, keeps the inventory and adds every Command and Function in _ready():

In YarnKindWhat it does
<<add_inventory_item FoodType.Apple>>CommandAdds a fruit to the inventory. The fruit piles use it.
<<remove_inventory_item FoodType.Apple>>CommandRemoves a fruit from the inventory.
<<walk_to_point_eat_and_return "Hungry Henry" Marker>>CommandWalks Henry to the Marker node, plays a bite sound, and walks him back. The player can skip it.
has_inventory_item(FoodType.Apple)FunctionWhether the inventory has any of that fruit.
has_any_inventory_items()FunctionWhether the inventory has anything in it.
inventory_count(FoodType.Apple)FunctionHow many of that fruit the inventory has.
pick_inventory_item()FunctionShows the inventory, waits for the player to choose a fruit, and returns it.
The Commands and Functions the sample adds.

Each fruit pile has a DialogueInteractable that runs one of the ItemVendor nodes in CustomActions-ItemVendors.yarn. Henry’s runs HungryHenry, and Capsley’s runs ExplanationCharacter, both in CustomActions.yarn.

The inventory panels are scripts/inventory_panel.gd, with one scenes/inventory_item.tscn for each fruit. Each item has its fruit set in the Inspector. The InventoryLayer is laid out at 1920 by 1080, and the root script scales it to fit the window.

Commands and Functions that take an enum

CustomActions.yarn declares the fruit as an enum:

<<enum FoodType>>
    <<case None = "none">>
    <<case Apple = "apple">>
    <<case Orange = "orange">>
    <<case Blueberry = "blueberry">>
<<endenum>>
The FoodType enum, in the HungryHenry node.

The Yarn Project has Generate Variables Source turned on in its import options, with the class name CustomFunctionsVariables. The generated class, dialogue/custom_functions_variables.gd, has a matching GDScript enum, CustomFunctionsVariables.FoodType. The Commands and Functions use it as their parameter type. <<add_inventory_item FoodType.Apple>> passes in CustomFunctionsVariables.FoodType.APPLE:

func _add_inventory_item(food: CustomFunctionsVariables.FoodType, count: int = 1) -> void:
	_inventory[food] = maxi(_inventory.get(food, 0) + count, 0)
	_update_inventory_panels()


func _inventory_count(food: CustomFunctionsVariables.FoodType) -> int:
	return _inventory.get(food, 0)
Commands and Functions that take a FoodType.

See Yarn enums.

A Function that waits for the player

pick_inventory_item() shows the inventory picker, and doesn’t return until the player has chosen:

func _pick_inventory_item(token: YarnCancellationToken) -> String:
	var none := CustomFunctionsVariables.FoodType.NONE
	if token.is_next_content_requested or not _has_any_inventory_items():
		return CustomFunctionsVariables._FOOD_TYPE_VALUES[none]

	var picked := YarnPromise.new()
	var on_picked := func(food: int) -> void: picked.settle(food)
	var on_cancelled := func() -> void: picked.settle(none)
	selection_panel.item_picked.connect(on_picked)
	token.next_content_requested.connect(on_cancelled)

	_is_selecting = true
	_update_inventory_panels()
	selection_panel.focus_first_item()

	var result: int = await picked.wait()

	_is_selecting = false
	_update_inventory_panels()
	selection_panel.item_picked.disconnect(on_picked)
	token.next_content_requested.disconnect(on_cancelled)
	return CustomFunctionsVariables._FOOD_TYPE_VALUES[result]
Line 1 Because the last parameter is a YarnCancellationToken, the Dialogue Runner passes one in. It isn’t written in the Yarn Script. The return type, String, tells the compiler what the Function gives back.
Lines 3–4 If there’s nothing to pick, or the dialogue has already been stopped, return "none" straight away.
Lines 6–10 A YarnPromise settles with the fruit the player clicks, or with None if the dialogue is stopped while they’re choosing.
Lines 12–14 Show the picker, and put keyboard focus on its first fruit.
Line 16 Wait here until the promise settles.
Lines 18–22 Hide the picker, stop listening, and return the fruit’s value, like "orange".
pick_inventory_item in custom_actions.gd.

A Function can’t return an enum, so it returns the fruit’s value instead. Henry’s node passes that value straight to <<remove_inventory_item>>, because a Command with an enum parameter accepts the enum’s value as well as its name:

// Pick an item from the inventory. The dialogue will pause until this is complete.
<<set $selected_food = pick_inventory_item()>>

<<if $selected_food is string($desired_food)>>
    // The player picked the desired item!

    // Remove the item from the inventory.
    <<remove_inventory_item {$selected_food}>>
Line 2 The dialogue stops here until the player has chosen a fruit.
Line 4 $desired_food is a FoodType, and $selected_food is its value as text. Compare them as text.
Line 8 $selected_food holds a value like "orange", which the Command turns into CustomFunctionsVariables.FoodType.ORANGE.
Part of the HungryHenry node in CustomActions.yarn.

A Command the player can skip

<<walk_to_point_eat_and_return>> takes a few seconds. Because its last parameter is a YarnCancellationToken, pressing Space or Enter while it’s running skips to the end:

func _walk_to_point_eat_and_return(character: SimpleCharacter, destination: Node3D, token: YarnCancellationToken) -> void:
	if character == null or destination == null:
		return
	var start_position := character.global_position
	var start_facing := character.global_basis.z

	await character.move_to(destination.global_position, token)

	if not token.is_hurry_up_requested:
		eat_sound.play()
		await token.wait_for_cancellation(1.0)

	await character.move_to(start_position, token)
	character.set_look_direction(start_facing)
	eat_sound.stop()
Line 1 "Hungry Henry" and Marker are node names. The Dialogue Runner finds the nodes and passes them in, and adds the token.
Lines 4–5 Remember where Henry started, and which way he was facing.
Line 7 Walk to the marker. move_to() takes the token too. If the player skips, Henry jumps to the end of the walk.
Lines 9–11 Play the bite sound, and wait a second, or less if the player skips.
Lines 13–15 Walk back, turn back to face the way he was, and stop the sound in case it’s still playing.
walk_to_point_eat_and_return in custom_actions.gd.

When you press Space or Enter while no line is showing, the root script’s _unhandled_input() asks the Dialogue Runner for the next content. That cancels the Command’s token. Escape calls stop_dialogue().

For more about tokens, see Async and Cancellation.

Things to try

  • Add a fourth fruit. Add a case to the FoodType enum, a new pile with its own ItemVendor node, and an item for it in both inventory panels with its fruit set in the Inspector. The generated class picks up the new case when the Yarn Project reimports.

This sample is a port of the Custom Actions sample from Yarn Spinner for Unity. It uses models by Kay Lousberg, licensed under CC0, and the sound “Crispy bite” by JoMungus.

Next step Instance Commands Characters with their own Commands, called by name from Yarn.