Commands work very similar to Yarn functions, but use a different syntax and are able to modify the game world. As a consequence of their similarity, registering custom commands is very similar to registering custom functions.

Command Registration

Just as with Yarn functions, registration happens when creating a DialogueRunner. Let's again modify the example from the Quick Start:

fn spawn_dialogue_runner(mut commands: Commands, project: Res<YarnProject>) {
    let mut dialogue_runner = project.create_dialogue_runner();
    // Add our custom command to the dialogue runner
    dialogue_runner
        .commands_mut()
        .add_command("print_addition", print_addition);
    dialogue_runner.start_node("Start");
    commands.spawn(dialogue_runner);
}

fn print_addition(In((a, b)): In<(f32, f32)>) {
    print!("{a} + {b} = {c}", c = a + b)
}

We call the command like this:

title: Start
---
Let's print the addition of 1 and 3 in the console:
<<print_addition 1 3>>
===

You will have seen one crucial difference to Yarn functions immediately. The parameters are not passed in directly to the Rust function, but are wrapped in an In struct. This is because Rust functions that are registered as commands are always valid Bevy systems. The In parameter just tells the function which values come from the Yarn file, but we can additionally query the Bevy world as we want:

fn spawn_dialogue_runner(mut commands: Commands, project: Res<YarnProject>) {
    let mut dialogue_runner = project.create_dialogue_runner();
    // Add our custom command to the dialogue runner
    dialogue_runner
        .commands_mut()
        .add_command("insert_resource", insert_resource);
    dialogue_runner.start_node("Start");
    commands.spawn(dialogue_runner);
}

#[derive(Resource)]
struct Person {
    name: String,
    age: f32,
}

fn insert_resource(In((name, age)): In<(String, f32)>, mut commands: Commands) {
    commands.insert_resource(Person { name, age });
}

which we call like this:

title: Start
---
Let's insert a resource into the Bevy world:
<<insert_resource "Bob" 42>>
===

Return Types and Long Running Commands

In contrast to functions, commands cannot have any Yarn facing return types. The Rust functions however can use a return value to indicate that Yarn Spinner should wait a while before continuing the dialogue. This is useful for times when you want to change something in the world before the dialogue goes on, e.g. move the camera to another speaker. To do this, simply return a type implementing TaskFinishedIndicator, for example Arc<AtomicBool>. This way, you can keep a copy of the Arc and change its content to true whenever your transition is over.

For a practical example, check out how we implement a fade out at the end of the demo.

As mentioned in the chapter Functions, Yarn can access user-defined functions. A collection of functions is called a library and can be accessed through a DialogueRunner.

Function Registration

For an easy example, let's modify the code used in the Quick Start to provide a simple pow function to Yarn:

fn spawn_dialogue_runner(mut commands: Commands, project: Res<YarnProject>) {
    let mut dialogue_runner = project.create_dialogue_runner();
    // Add our custom function to the dialogue runner
    dialogue_runner.library_mut().add_function("pow", pow);
    dialogue_runner.start_node("Start");
    commands.spawn(dialogue_runner);
}

fn pow(base: f32, exponent: f32) -> f32 {
    base.powf(exponent)
}

The following snippet is of special importance:

dialogue_runner.library_mut().add_function("pow", pow);

The first parameter of add_function() is the name of the function as seen by Yarn, "pow" in this case. The second parameter is the Rust function that will be called in the background. Here, we reference the function definition of fn pow(...), but you could also register a lambda.

This pow function can now be called from the Yarn file like this:

title: Start
---
Two to the power of three is {pow(2,3)}
===

Which will result in the following output:

Allowed Signatures

Custom functions need to follow some rules. Don't worry, they're pretty lax.

• Their parameter and output types need to be primitive types or String

• Parameters are allowed to be references

• Parameters can have the special type YarnValue, which stands for any input type. Additionally, functions are assumed to have no side effects. You can read the full list of requirements in the docs for YarnFn.

Here are some examples of valid functions:

fn add(a: f32, b: f32) -> f32 {
    a + b
}

fn concat(a: &str, b: &str) -> String {
    format!("{a}{b}")
}

fn greet(name: &str, age: usize) -> String {
    format!("Hello {name}, you are {age} years old!")
}

fn format_anything(value: YarnValue) -> String {
    format!("Got the following value: {value}")
}

If you need functions that have side effects, e.g. for manipulating the game world, use custom commands instead.

Size constraints

Registered Rust functions can have a maximum of 16 parameters. If you need more, you can wrap parameters in tuples:

fn add((a, b): (f32, f32)) -> f32 {
    a + b
}

Tuples are treated as separate parameters when calling the function from Yarn:

title: Start
---
Two plus three is {add(2, 3)}
===

Since tuples can be nested, you can use have potentially infinite parameters.

• You can define your own commands, which allow the scripts you write in Yarn Spinner to control parts of the game that you've built.

• Functions are units of code that Yarn scripts can call to receive a value. In addition to the built-in functions that come with Yarn Spinner, you can create your own.