Connecting to Your Game

Dialogue often has to reach into your game. A line might need to play a sound, check what the player is carrying, or remember that the player has already met someone.

Yarn Spinner gives you three ways to do that:

Commands let your Yarn Scripts tell your game to do something, like play a sound or move a character.
Functions let your Yarn Scripts ask your game for a value, like how many coins the player has.
Variables store values that both your Yarn Scripts and your game can read and change, like whether the player has met Rosa.

You can connect all three from Blueprints or from C++.

flowchart LR
  yarn["Your Yarn Script"]
  subgraph game["Your game"]
    direction TB
    audio["Audio player"]
    clock["Lighthouse clock"]
    inventory["Inventory"]
  end
  storage[("Variable Storage")]
  yarn -->|"#60;#60;play_sound door_creak#62;#62;"| audio
  yarn -->|"days_since_lamp_lit()"| clock
  clock -.->|"12"| yarn
  yarn <-->|"$has_key<br>$met_rosa"| storage
  inventory -->|"sets $has_key"| storage

The example node below, talking to a game. The Command plays a sound, the Function asks a clock for a number, and the inventory and the Yarn Script share variables through the Variable Storage.

This node uses all three:

title: Lighthouse
---
<<declare $lamp_days = 0>>
<<play_sound door_creak>>
<<set $lamp_days to days_since_lamp_lit()>>
Rosa: The lamp's been out for {$lamp_days} days.
<<if $has_key>>
    Rosa: You found the key! Let's go up.
<<endif>>
<<set $met_rosa to true>>
===

Line 4 A Command. Your game decides what play_sound does, here playing a sound called door_creak. The dialogue can wait for it to finish. See Commands.

Lines 5–6 A Function. Your game works out the number of days, and it’s stored in $lamp_days and shown in the line. See Functions.

Lines 7–9 Checking a variable. Your game might set $has_key when the player picks up the key. See Variables and Storage.

Line 10 Setting a variable. Your game can read $met_rosa later, for example to change what Rosa says next time.

A Command, a Function and two variables in one node.

Variables hold the state you save and load, so a player can leave a conversation and later pick it up where they left it.

In this section

Commands: calling your game code from Yarn, and making dialogue wait until it’s done.
Functions: getting values from your game to use in lines and conditions.
Putting It Together: a small Actor that uses Commands and Functions together.
Variables and Storage: reading and changing Yarn variables from Blueprints and C++, and saving and loading them.
Smart Variables: variables that are worked out from other variables each time they’re read.
Saliency and Storylets: how the Dialogue Runner picks one line or node when several could run.
Custom Saliency Strategies: writing your own way to pick content from node groups and line groups.
Async and Cancellation: waiting in Commands and Presenters without breaking skipping or pausing.

Get started Commands Calling your game code from Yarn, and making dialogue wait until it's done.