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
The script on the root node, scripts/custom_actions.gd, keeps the inventory and adds every Command and Function in _ready():
| In Yarn | Kind | What it does |
|---|---|---|
<<add_inventory_item FoodType.Apple>> | Command | Adds a fruit to the inventory. The fruit piles use it. |
<<remove_inventory_item FoodType.Apple>> | Command | Removes a fruit from the inventory. |
<<walk_to_point_eat_and_return "Hungry Henry" Marker>> | Command | Walks Henry to the Marker node, plays a bite sound, and walks him back. The player can skip it. |
has_inventory_item(FoodType.Apple) | Function | Whether the inventory has any of that fruit. |
has_any_inventory_items() | Function | Whether the inventory has anything in it. |
inventory_count(FoodType.Apple) | Function | How many of that fruit the inventory has. |
pick_inventory_item() | Function | Shows the inventory, waits for the player to choose a fruit, and returns it. |
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 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)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]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."none" straight away.YarnPromise settles with the fruit the player clicks, or with None if the dialogue is stopped while they’re choosing."orange".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}>>$desired_food is a FoodType, and $selected_food is its value as text. Compare them as text.$selected_food holds a value like "orange", which the Command turns into CustomFunctionsVariables.FoodType.ORANGE.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()"Hungry Henry" and Marker are node names. The Dialogue Runner finds the nodes and passes them in, and adds the token.move_to() takes the token too. If the player skips, Henry jumps to the end of the walk.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
FoodTypeenum, a new pile with its ownItemVendornode, 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.