Crate bevy_yarnspinner

Bevy Yarn Spinner

This is the Bevy integration for Yarn Spinner, the friendly dialogue creation tool for Rust. It allows you to easily create dialogue systems in your game.

Usage

The three main types you will interact with are:

• YarnSpinnerPlugin: The plugin registering all systems and types.
• YarnProject: A Resource for the compiled Yarn project, which is created for you when YarnSpinnerPlugin is added.
• DialogueRunner: The Component running through the Yarn files and sending events for things you should draw on the screen. Can be created from a YarnProject.

Dialogue Views

The dialogue runner itself does not draw anything to the screen, it only tells you what content to present. Any plugin that handles the actual drawing is called a dialogue view. We provide an example dialogue view that you can use to explore the features of Yarn Spinner and get started quickly.

Specifically, a dialogue view is required to do the following things

• Handle the PresentLineEvent and draw the line to the screen.
• Handle the PresentOptionsEvent and draw the options to the screen.
• Call DialogueRunner::continue_in_next_update when the user wishes to continue the dialogue.
• Pass a user’s option selection to the right dialogue runner via DialogueRunner::select_option.

See the documentation for the events module for additional optional events that may be handled

Note that while DialogueRunners are setup in such a way that you can have multiple instances running in parallel (such as for split-screen co-op), a general-purpose dialogue view is not required to support this use-case, as every game that does this will have it’s own way of wanting to deal with this. In particular, the example dialogue view only supports a single DialogueRunner.

Demo

You can play a the Yarn Spinner for Rust Demo in your browser to see the aforementioned example dialogue view in action. Additionally, there are many examples that you can check out.

Example

The main workflow is as follows:

• Register the YarnSpinnerPlugin
• When the YarnProject Resource is added, spawn a DialogueRunner from it. The latter can nicely be done with my_system.run_if(resource_added::<YarnProject>).

The following example is adapted from the hello world example.

# assets/dialogue/hello_world.yarn
title: Start
---
Hello world!
===

// src/main.rs
use bevy::prelude::*;
use bevy_yarnspinner::prelude::*;
// Use the example dialogue view to see the dialogue in action. Requires the `bevy_yarnspinner_example_dialogue_view` crate.
// use bevy_yarnspinner_example_dialogue_view::prelude::*;

fn main() {
    let mut app = App::new();
    app.add_plugins((
        // Add the Yarn Spinner plugin.
        // As soon as this plugin is built, a Yarn project will be compiled
        // from all Yarn files found under assets/dialog/*.yarn
        YarnSpinnerPlugin::new(),
        // Initialize the bundled example UI. Requires the `bevy_yarnspinner_example_dialogue_view` crate.
        // ExampleYarnSpinnerDialogueViewPlugin::new(),
    ))
    // Setup a 2D camera so we can see the text
    .add_systems(Startup, setup_camera)
    // Spawn the dialog as soon as the Yarn project finished compiling
    .add_systems(
        Update,
        spawn_dialogue_runner.run_if(resource_added::<YarnProject>),
    )
    .run();
}

fn setup_camera(mut commands: Commands) {
    commands.spawn(Camera2d::default());
}

fn spawn_dialogue_runner(mut commands: Commands, project: Res<YarnProject>) {
    let mut dialogue_runner = project.create_dialogue_runner(&mut commands);
    // Start the dialog at the node with the title "Start"
    dialogue_runner.start_node("Start");
    commands.spawn(dialogue_runner);
}

Modules

default_impl

Default implementations for Yarn Spinner traits.

deferred_loading

Contains types needed for the deferred loading functionality, which is used when the list of Yarn files is not immediately available at startup.

events

Events that are sent by the DialogueRunner. A dialogue view is expected to at least handle PresentLineEvent and PresentOptionsEvent.

prelude

Everything you need to get starting using Yarn Spinner.

Macros

file_extensions

A convenience macro for specifying file extensions used by FileExtensionAssetProvider::with_file_extensions. The syntax is as follows:

yarn_commands

Convenience macro for creating a YarnCommands instance with the given commands.

yarn_fn_type

A macro for using YarnFn as a return type or parameter type without needing to know the implementation details of the YarnFn trait.

Structs

Compilation

The result of a compilation.

Error

The Error type, a wrapper around a dynamic error type.

InnerDialogue

Proxy for some functionality of the Dialogue used by DialogueRunner. Constructed by DialogueRunner::inner. Serves advanced use cases.

InnerDialogueMut

Mutable proxy for some functionality of the Dialogue used by DialogueRunner. Constructed by DialogueRunner::inner_mut. Serves advanced use cases.

StringInfo

Information about a string. Stored inside a string table, which is produced from the Compiler.

UnderlyingYarnCommand

A custom command found in a Yarn file within the << and >> characters.

UnderlyingYarnLine

A line of dialogue, sent from the Dialogue to the game.

YarnAnalysisContext

A structure that holds several CompiledProgramAnalysers which are used to analyse one or more compiled Yarn programs with Dialogue::analyse. To get the analysis results, call Context::finish_analysis afterwards.

Traits

TaskFinishedIndicator

Trait implemented by the return types of methods registered in the YarnCommands.

UnderlyingTextProvider

A trait for providing text to a Dialogue. The default implementation is StringTableTextProvider, which keeps the text for the base language, i.e. the language the Yarn files are written in, and the text for the currently selected translation in memory.

UntypedYarnCommand

A type-erased YarnCommand as it appears in the YarnCommands.

UntypedYarnFn

A YarnFn with the Marker type parameter erased. See its documentation for more information about what kind of functions are allowed.

Type Aliases

Result

Result<T, Error>