Yarn Spinner for Rust is the set of components and scripts that make Yarn Spinner work inside a Bevy project.

In this section, you’ll learn how to work with Yarn Spinner for Rust more in-depth.

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

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

Yarn Spinner for Rust is made up of a number of components. The most important of these are the Dialogue Runner, which loads and runs your scripts, and the Dialogue Views that show content to your player.

In this section, you'll learn about how to work with each of these.

• Our examples directory contains many small programs showcasing individual features

• The demo has its code open sourced to learn from it

• The Foxtrot template uses Yarn Spinner for Rust for its dialog. You can take a look at it to learn how Yarn Spinner is used in a more comprehensive 3D project.

We will now go through the steps to setup a new Bevy project running Yarn Spinner dialogues

Setting up the crate

Run the following in your terminal to create a new crate with the required dependencies:

cargo new yarnspinner_playground
cd yarnspinner_playground
cargo add bevy bevy_yarnspinner bevy_yarnspinner_example_dialogue_view

The dependency bevy_yarnspinner is for the Yarn Spinner Bevy plugin proper, while bevy_yarnspinner_example_dialogue_view gives us a nice default Dialogue View, so we can actually see the text we've written and have options to click on.

Adding the Yarn Files

We'll use a single Yarn file for this example. Inside the folder assets/dialogue, add a file named example.yarn with the following content:

# assets/dialogue/example.yarn
title: Start
---
Hello World!
Wow! My first ever Yarn script in Rust!

-> Gosh!
-> Incredible!
-> I'm amazed!

Anyway, time to get writing!
===

The main code

Add the following code to your src/main.rs.

Reiterating the comments in the code, let's take a look at some snippets.

This self-explanatory line initializes the plugin. When using the standard constructor with no options, Yarn files will be searched for in the directory <your game>/assets/dialogue/, where all files ending in .yarn will be compiled as soon as the game starts.

The plugin makes sure all components of Yarn Spinner work except for any actual graphics. You need to instantiate a for that:

Here we initialize the dialogue view shipped by the bevy_yarnspinner_example_dialogue_view crate. It offers some sensible defaults which you can see in the screenshots used throughout this guide. You can of course skip this and use your own dialogue view instead.

The method .run_if(resource_added::<YarnProject>() is our way of saying "run this system once as soon as our Yarn files are done compiling". Let's look at what will actually be run in that moment:

The main way of interacting with Yarn files during runtime and managing the flow of a dialog is through a . To do this, we use the resource we referenced in the run_if section above. It represents our compiled Yarn files, which we use to create a new dialog runner. We then point it to the named "Start" of our Yarn file. We use start_node for this, which will "move" the dialog runner to the provided node and start executing the dialog in the next frame, using the registered Dialogue View to actually present it on the screen. Finally, we spawn the dialog runner on an own entity into the Bevy world.

In the end, your file structure should look like this:

Run your game with cargo run and you should see the following:

Variable Storage components are responsible for storing and retrieving the values of variables in your Yarn scripts. When a Yarn script needs to get the value of a variable, it asks the Variable Storage for it; when a Yarn script sets the value of a variable, the Variable Storage is given the value.

Each game has different requirements for how variables are stored, which means that Yarn Spinner doesn't make any assumptions how the information is actually stored on disk. Instead, you can create your own custom Variable Storage script that implements the methods that Yarn Spinner needs.

If you don't connect a Variable Storage to your Dialogue Runner, it will create an In-Memory Variable Storage when the game starts, and use that.

The In-Memory Variable Storage component is a Variable Storage component that stores all variables in memory. These variables are erased when the game stops.

Every game's data storage requirements are different. For this reason, Yarn Spinner is designed to make it straightforward to create your own custom component for managing how Yarn scripts store and load variables in ways that work with the other parts of your game.

Custom Variable Storage components are implementations of the trait . To implement your own, check out the documentation. Once you have it, you can use it by calling when building your Dialogue Runner.

Yarn Spinner itself handles only the hard logic behind the dialogue flow, but it doesn't actually draw anything to the screen. This is the job of Dialogue Views. They are plugins that react to s fired by the Dialogue Runner and display them to the player.

A Dialogue Runner can have multiple Dialogue Views. For example, you might have one Dialogue View that's designed to display lines of dialogue, and another that's in charge of displaying options to the player.

Because every game's needs are different, a Dialogue View is designed to be extremely customisable, and you can create your own custom dialogue views to suit the needs of your game.

However, because there are common patterns of how games work with dialogue, Yarn Spinner for Rust comes with a pre-built Dialogue View that handles common use cases: The . You'll see it used all over our examples. To use it, you simply add its plugin after the Yarn Spinner plugin proper:

And that's it! It will display whatever comes its way to the user and handle some basic input. As an added bonus, it will send out a whenever the active speaker has changed from its point of view, in case you want to e.g. rotate your camera there. If you do such an interaction, be sure to place your code in a Bevy system set that comes after the to avoid race conditions.

The YarnProject resource represents the set of all compiled Yarn files of your game. You cannot construct it yourself. Instead, it is inserted into the Bevy world for you when the compilation is finished. You can however steer how and when this is done.

Starting the Compilation Process

Generally, you'll want your game to compile the Yarn files as soon as possible. This is why the YarnSpinnerPlugin will start doing so by default when it is added to the app.

If for some reason you do not wish to start compilation right away, you can defer this process. To do this, construct the YarnSpinnerPlugin with YarnSpinnerPlugin::deferred() when adding it. Then, whenever you are ready to start the compilation, you can send a LoadYarnProjectEvent. Its construction methods are identical to the YarnSpinnerPlugin. In fact, when not running in deferred mode, the YarnSpinnerPlugin simply relays its setting to a LoadYarnProjectEvent and sends it.

If you look through the documentation of the [YarnSpinnerPlugin], you'll notice a few methods to modify its settings. The first few deal with where our Yarn files are coming from.

By default, Yarn Spinner will look in <game directory>/assets/dialogue. Yarn Spinner can only read files from the assets directory — or its equivalent, if you have changed this default in the AssetPlugin on platforms which support it— but you can change how the assets will be looked through.

The way to specify this is via YarnFileSources. This enum tells Yarn Spinner where one or more Yarn files come from and can be added to an AssetPlugin with AssetPlugin::add_yarn_source(). The enum variants should be self explanatory, but the two most common use-cases come with their own convenience constructors:

• YarnFileSource::file(): looks for a Yarn file at a path inside under the assets directory.

• YarnFileSource::folder(): recursively looks through a given subdirectory for Yarn files.

Since the Wasm and Android builds of Bevy have restrictions on their filesystem access, they cannot use YarnFileSource::folder() and must have all their Yarn files listed explicitly with YarnFileSource::file(). As such, the default behavior provided by YarnSpinnerPlugin::new() is not suitable for these platforms. To avoid it, use the AssetPlugin::with_yarn_source() constructor instead.

As you might have guessed by now, YarnSpinnerPlugin::new() is simply a shorthand for AssetPlugin::with_yarn_source(YarnFileSource::folder("dialogue")).

YarnSpinnerPlugin::with_development_file_generation() accepts a DevelopmentFileGeneration, which tells Yarn Spinner how aggressively to generate useful files on runtime. "Useful" refers to the developer and not the user. The default is DevelopmentFileGeneration::TRY_FULL, which will be DevelopmentFileGeneration::Full on platforms which support filesystem access, i.e. all except Wasm and Android. See the documentation for the full list of effects. Suffice it to say that this is not very important when developing without localization, but becomes vital otherwise. See the chapter for more.

Since these settings are intended for development, you can use YarnSpinnerPlugin::with_development_file_generation(DevelopmentFileGeneration::None) when shipping your game to optimize the runtime costs and avoid generating files that are useless to the player.

The settings accessed by YarnSpinnerPlugin::with_localizatons are important enough to warrant their own chapter. See .

Whether you used YarnSpinnerPlugin or LoadYarnProjectEvent, as soon as the compilation finished, a YarnProject resource will be inserted into the Bevy world. You can react to its creation by guarding your systems with .run_if(resource_added::<YarnProject>()), as seen in the .

Once you have the YarnProject, you can use it to spawn a DialogueRunner which in turn can, well,

While Bevy as a whole has assets, Yarn Spinner can associate specific assets with lines. These are always localised, such as voiceovers.

Using Metadata Instead of Assets

Before we jump into assets, let's first help you out if you don't care about localization. The mechanism in place for this is line metadata, which are strings you can add to Yarn lines after a hashtag:

title: Start
---
Granny: It's hard to believe that it's over, isn't it? #smiling
Granny: Funny how we get attached to the struggle. #laughing
Granny: Promise me that you'll take care of yourself, okay? #smiling
===

A Dialogue View will be able to read the metadata "smiling", "laughing", and "smiling" again from LocalizedLine::metadata and accordingly load things like character portraits. These annotations will also be written into the "comment" field of strings files, which are explained in the chapter Localisation.

Asset Providers

Assets are fetched from the filesystem by structs implementing AssetProvider. They need to be registered when creating a DialogueRunner. For example, if you use the audio_assets feature, you can register an asset provider for audio files by modifying the code found in the Quick Start like this:

fn spawn_dialogue_runner(mut commands: Commands, project: Res<YarnProject>) {
    let mut dialogue_runner = project
        .build_dialogue_runner()
        .add_asset_provider(AudioAssetProvider::new())
        .build();
    dialogue_runner.start_node("Start");
    commands.spawn(dialogue_runner);
}

The AudioAssetProvider itself is just a specialized . As the name suggests, it serves any assets based on their extension:

The (and, by extension, the AudioAssetProvider) will search for their assets in the directory assets/dialogue/<language>/<line-id.extension>. So, for example, an AudioAssetProvider serving up a voiceover for the line with the ID 41239 while the game is set to the language "de-CH" will search for assets/dialogue/de-CH/41239.mp3.

Finally, you can implement yourself with whatever custom behavior you desire. Check out the trait's documentation for the necessary methods.

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

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

The following snippet is of special importance:

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.

work very similar to Yarn , 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 .

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

We call the command like this:

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:

which we call like this:

In contrast to

Text

How do I style text? How do I make some words bold, italic, colorful, etc.?

Yarn Spinner doesn't do text rendering, you have to use existing Bevy plugins.

How do I animate wavy text, like in Night In The Woods?

Yarn Spinner doesn't handle text rendering. You'll need a separate wavy text plugin.

How do I use Yarn Markup?

Markup lets you mark a range of text (words, phrases) in a generic way, for whatever use. You could use it to style text, add sentence markers, make clickable words, etc.

// Yarn script example of custom "wavy text" markup.
Oh, [wave]hello[/wave] there!

// After compiling, text will look like: "Oh, hello there!"
// And then the resulting markup data will look like:
// - name: "wave"
// - position: 4
// - length: 5

Note that YS only processes the text data. You must still code the actual markup effect yourself. See Markup.

Variables

How do I print the value of a variable in dialogue?

Wrap the variable (or any expression) in curly braces ({, }) to evaluate and output it. For more info, see Variables.

<<set $variableName to "a string value">>
The value of variableName is {$variableName}.
// This will appear as "The value of variableName is a string value."

How do I read / write Yarn variables from Rust?

To read Yarn variables from Rust, use VariableStorage::get(). To write Yarn variables from Rust, use VariableStorage::set()

let variable_storage = dialogue_runner.variable_storage_mut(); 
let test_variable: f32 = variable_storage.get("$testVariable")?.try_into()?;
variable_storage.set("$testVariable", (testVariable + 1).into())?;

How do I 'sync' variables between Yarn and Rust?

You could hack this with static variables. But we recommend avoiding any "sync" pattern, because then you'll have to track and maintain the same data in two different places. Programmers usually prefer a . Data should live in only one place. Variables should either live in Yarn or live in Rust, and not in both.

To save the current node, save the value of somewhere, e.g. to a .ron file. Then to restore it, call and pass in the saved node name.

To save variables, fetch them using , then use to read them all and store them again somewhere. Then to load variables, call .

For custom save systems, create your own by implementing and its methods. Study as an example.

It is not currently possible to save or restore the specific line that the dialogue is running.

To jump to a node from Yarn, use <<jump (nodeName)>>. See .

To jump to a node with Rust, just call , even if there's already dialogue running.

Jumping to a specific line in a node is currently not supported. Instead, .

Yarn Spinner automatically adds a #lastline tag to a line when the next step is a set of options. Create a that uses to check for "lastline" and perform the behavior you want.

To display anything in Yarn Spinner, use a plugin.

Create a custom dialogue view with a custom effect based on to detect the next text character and pause accordingly.

Write input code to detect clicking / tapping, then call .

This implementation will vary for every game, so we purposely do not attempt to design a one-size-fits-all generic NPC system. Here's some example pseudocode to make your own:

The math / code is a little complicated. Calculate the NPC's on-screen position, then convert this screen position to UI canvas space, and reposition the dialogue bubble.

There is no real technical limit on the number of Yarn scripts or the size of Yarn Projects. You decide how to organize your data, and every project has different needs. Some factors to consider:

• Simplicity. Putting everything into one big script file or one big project file is simpler sometimes.

• Ease of writing. Writers may prefer to think in terms of one file per scene, one file per chapter.

• Localization. 1 Yarn Project = 1 CSV spreadsheet per language. When translating, it is usually easier to work with fewer files, rather than fragmenting the translation across many files. As a workaround for games that need multiple Yarn Projects, you may prefer to create a single editor-only Yarn Project that's just for generating string files and translations. See .

Please visit the for more information. Thanks for thinking of us!

Localization is the process of translating and adapting content to a specific language, region or culture.

Yarn scripts are written in human-readable language. This is generally a single language, and (most of the time) will be written in the language that your development team primarily speaks. The language that a Yarn project is written in is called the base language.

However, if you want your dialogue to be understood by people who don't speak this language, you will need to translate it. Yarn Spinner is designed to make it easy to extract the user-facing text of your dialogue into a strings file, which can then be translated into a different language, and then loaded at run-time. You can translate your project into as many languages as you'd like, and Yarn Spinner will handle it for you automatically.

Yarn Spinner is also designed around the idea that a line of dialogue may have assets associated with it. Most commonly, this means an audio file that contains an actor performing the line, so that it can be used in your game as a voice-over. These assets are also localisable.

• Localisation

The main way to actually manipulate the state of your dialog is through a DialogueRunner. You create it from a YarnProject (see ) with either YarnProject::create_dialogue_runner() or YarnProject::build_dialogue_runner(). The first uses default configurations which should be alright for many use-cases, while the latter allows you to add or change functionality.

The actual navigation through a dialog is handled by a , which is responsible for back-and-forth interaction with the player. As such, most of the methods provided by a DialogueRunner are to be called by such a view. The one you will want to call yourself, as seen in the , is DialogueRunner::start_node, which will tell the DialogueRunner to start running from the provided