Bevy Yarn Spinner

https://docs.rs/bevy_yarnspinner/0.7.0/
Admin
Bevy Yarn Spinner is a Bevy integration for Yarn Spinner, a friendly dialogue creation tool for...
Tokens:63,987
Snippets:547
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Creating a Localization instance

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/struct.Localization.html

Example of creating a Localization instance using a language string.

```rust
let localization: Localization = "de-CH".into();
```

--------------------------------

### Example Yarn script line IDs

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/struct.LineId.html

An example showing how line IDs are represented in Yarn script files.

```text
Darth Vader: I am your father! #line:123
Luke: Noooooo #line:nooooo
```

--------------------------------

### Register a system with yarn_commands

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/macro.yarn_commands.html

Example showing how to map a Yarn command name to a Bevy system.

```rust
let commands = yarn_commands! {
   "add_player" => world.register_system(add_player),
};

fn add_player(In((name, age)): In<(String, f32)>) {
    println!("Adding player {name} with age {age}");
}
```

--------------------------------

### Initialize Yarn Spinner in Bevy

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/index.html

Setup the YarnSpinnerPlugin and spawn a dialogue runner once the project is compiled.

```rust
// 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);
}
```

--------------------------------

### Start Dialogue Node

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/dialogue_runner.rs.html

Methods to initiate dialogue from a specific node. start_node will panic if already running, while try_start_node returns a Result.

```rust
pub fn start_node(&mut self, node_name: impl AsRef<str>) -> &mut Self {
        self.try_start_node(node_name)
            .unwrap_or_else(|e| panic!("{e}"))
    }
```

```rust
pub fn try_start_node(&mut self, node_name: impl AsRef<str>) -> Result<&mut Self> {
        let node_name = node_name.as_ref();
        if self.is_running {
            bail!(
                "Can't start dialogue from node {node_name}: the dialogue is currently in the middle of running. Stop the dialogue first."
            );
        }
        self.is_running = true;
        self.just_started = true;
        self.inner_mut()
            .0
            .set_node(node_name)
            .map_err(|e| anyhow!("Can't start dialogue from node {node_name}: {e}"))?;
        self.popped_line_hints = self.inner_mut().0.pop_line_hints();
        self.continue_in_next_update();
        Ok(self)
    }
```

--------------------------------

### Registering functions in YarnLibrary

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/struct.YarnLibrary.html

Examples demonstrating how to add functions to a YarnLibrary, including Bevy systems, standard Rust functions, and factory-based functions.

```rust
library.add_function("string_length", world.register_system(how_many_things));

fn how_many_things(In(thing_type): In<String>, things: Query<&Name>) -> u32 {
    let mut count = 0;
    for name in &things {
        if name.as_str() == thing_type {
            count += 1;
        }
    }
    count
}
```

```rust
library.add_function("string_length", string_length);

fn string_length(string: String) -> usize {
    string.len()
}
```

```rust
library.add_function("length_times_two", string_length_multiplied(2));

fn string_length_multiplied(factor: usize) -> yarn_fn_type! { impl Fn(String) -> usize } {
    move |s: String| s.len() * factor
}
```

--------------------------------

### get

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/struct.YarnCommands.html

Retrieves a reference to a registered command by name.

```APIDOC
### pub fn get(&self, name: &str) -> Option<&dyn UntypedYarnCommand>

Returns an optional reference to the command associated with the provided name.
```

--------------------------------

### Result::is_ok_and Method

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/type.Result.html

Example of checking if a Result is Ok and matches a predicate.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.is_ok_and(|x| x > 1), true);

let x: Result<u32, &str> = Ok(0);
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<u32, &str> = Err("hey");
assert_eq!(x.is_ok_and(|x| x > 1), false);

let x: Result<String, &str> = Ok("ownership".to_string());
assert_eq!(x.as_ref().is_ok_and(|x| x.len() > 1), true);
println!("still alive {:?}", x);
```

--------------------------------

### Result::is_ok Method

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/type.Result.html

Example of checking if a Result is Ok.

```rust
let x: Result<i32, &str> = Ok(-3);
assert_eq!(x.is_ok(), true);

let x: Result<i32, &str> = Err("Some error message");
assert_eq!(x.is_ok(), false);
```

--------------------------------

### Start a Yarn Spinner dialogue node

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/lib.rs.html

Initiate dialogue execution at a specific node within a Yarn project.

```rust
    // Start the dialog at the node with the title "Start"
    dialogue_runner.start_node("Start");
    commands.spawn(dialogue_runner);
}
```

--------------------------------

### Call a Bevy system from Yarn Spinner

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/trait.YarnFn.html

Example of invoking a registered Bevy system within a Yarn script.

```yarn
<<set $name to "Bob">>
Narrator: {give_summary_from_bevy($name)}
```

--------------------------------

### Initialize and Manage StringsFileTextProvider

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/line_provider/text_provider/strings_file_text_provider.rs.html

Methods for creating a provider from a YarnProject and managing language state.

```rust
pub fn from_yarn_project(yarn_project: &YarnProject) -> Self {
        Self {
            asset_server: yarn_project.asset_server.clone(),
            localizations: yarn_project.localizations.clone(),
            language: None,
            base_string_table: yarn_project.compilation.string_table.clone(),
            strings_file_handle: None,
            translation_string_table: None,
            event_cursor: Default::default(),
        }
    }
    fn set_language_invalidating_translation(&mut self, language: impl Into<Option<Language>>) {
        self.language = language.into();
        self.translation_string_table = None;
        self.strings_file_handle = None;
    }

    fn is_base_language(&self) -> bool {
        self.language.is_none()
            || self.language.as_ref()
                == self
                    .localizations
                    .as_ref()
                    .map(|localizations| &localizations.base_localization.language)
    }
```

--------------------------------

### Result::flatten Method

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/type.Result.html

Examples of flattening nested Result types.

```rust
let x: Result<Result<&'static str, u32>, u32> = Ok(Ok("hello"));
assert_eq!(Ok("hello"), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Ok(Err(6));
assert_eq!(Err(6), x.flatten());

let x: Result<Result<&'static str, u32>, u32> = Err(6);
assert_eq!(Err(6), x.flatten());
```

```rust
let x: Result<Result<Result<&'static str, u32>, u32>, u32> = Ok(Ok(Ok("hello")));
assert_eq!(Ok(Ok("hello")), x.flatten());
assert_eq!(Ok("hello"), x.flatten().flatten());
```

--------------------------------

### Result::transpose Method

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/type.Result.html

Example of transposing a Result of an Option into an Option of a Result.

```rust
#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);
```

--------------------------------

### try_start_node

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/dialogue_runner.rs.html

A fallible version of start_node.

```APIDOC
## try_start_node(node_name: impl AsRef<str>)

### Description
Attempts to start the dialogue at the given node. Returns an error if the dialogue is already running.

### Parameters
- **node_name** (impl AsRef<str>) - Required - The name of the node to start.
```

--------------------------------

### Result Usage in Main

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/type.Result.html

Example of using Result in the main function for error propagation.

```rust
use anyhow::Result;

fn main() -> Result<()> {
    let config = std::fs::read_to_string("cluster.json")?;
    let map: ClusterMap = serde_json::from_str(&config)?;
    println!("cluster info: {:#?}", map);
    Ok(())
}
```

--------------------------------

### FileExtensionAssetProvider::new()

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/default_impl/struct.FileExtensionAssetProvider.html

Initializes a new instance of FileExtensionAssetProvider with no file extensions configured.

```APIDOC
### pub fn new() -> Self

Initializes a new `FileExtensionAssetProvider` with no file extensions. Call `FileExtensionAssetProvider::with_file_extensions` to add file extensions.
```

--------------------------------

### Registering the commands plugin

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/commands.rs.html

Initializes the command-related plugins for the Bevy application.

```rust
1use bevy::prelude::*;
2pub use command_registry::YarnCommands;
3pub(crate) use command_registry::wait::update_wait;
4pub use command_wrapping::{TaskFinishedIndicator, UntypedYarnCommand, YarnCommand};
5
6mod command_registry;
7mod command_wrapping;
8mod execution;
9
10pub(crate) fn commands_plugin(app: &mut App) {
11    app.add_plugins(command_wrapping::command_wrapping_plugin)
12        .add_plugins(command_registry::command_registry_plugin)
13        .add_plugins(execution::command_execution_plugin);
14}
```

--------------------------------

### Get Text Language

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/dialogue_runner.rs.html

Returns the current language used by the TextProvider, if localizations are configured.

```rust
    #[must_use]
    pub fn text_language(&self) -> Option<Language> {
        self.inner().0.language_code().cloned()
    }
```

--------------------------------

### Result::cloned Method

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/type.Result.html

Examples of using the cloned method on Result types containing references.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let cloned = x.cloned();
assert_eq!(cloned, Ok(12));
```

--------------------------------

### start_node

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/struct.DialogueRunner.html

Initiates the execution of a specific dialogue node.

```APIDOC
### pub fn start_node(&mut self, node_name: impl AsRef<str>) -> &mut Self

Starts the dialogue at the given node. This method must be called after creation or after calling `DialogueRunner::stop` before the dialogue can be advanced.
```

--------------------------------

### Result::copied Method

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/type.Result.html

Examples of using the copied method on Result types containing references.

```rust
let val = 12;
let x: Result<&i32, i32> = Ok(&val);
assert_eq!(x, Ok(&12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

```rust
let mut val = 12;
let x: Result<&mut i32, i32> = Ok(&mut val);
assert_eq!(x, Ok(&mut 12));
let copied = x.copied();
assert_eq!(copied, Ok(12));
```

--------------------------------

### Command Registration and Execution Tests

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/commands/command_registry.rs.html

Various test cases demonstrating how to register systems with different argument types and execute them using the YarnCommands API.

```rust
#[test]
fn can_add_fn_with_empty_tuple_in_args() {
    let mut methods = YarnCommands::default();
    let mut world = World::default();
    methods.add_command("test", world.register_system(|_: In<()>| {}));
}
```

```rust
#[test]
fn can_add_fn_with_one_in_arg() {
    let mut methods = YarnCommands::default();
    let mut world = World::default();
    methods.add_command("test", world.register_system(|_: In<f32>| {}));
}
```

```rust
#[test]
#[should_panic = "It works!"]
fn can_call_fn_with_no_args() {
    let mut methods = YarnCommands::default();
    let mut world = World::default();

    #[allow(clippy::unused_unit)] // Needed for 2024 edition
    methods.add_command(
        "test",
        world.register_system(|_: In<()>| -> () { panic!("It works!") }),
    );
    let method = methods.get_mut("test").unwrap();
    method.call(vec![], &mut world);
}
```

```rust
#[test]
fn can_call_fn_with_one_arg() {
    let mut methods = YarnCommands::default();
    let mut world = World::default();

    methods.add_command(
        "test",
        world.register_system(|In(a): In<f32>| assert_eq!(1.0, a)),
    );
    let method = methods.get_mut("test").unwrap();
    method.call(to_method_params([1.0]), &mut world);
}
```

```rust
#[test]
fn can_add_multiple_fns() {
    let mut methods = YarnCommands::default();
    let mut world = World::default();

    methods.add_command("test1", world.register_system(|_: In<()>| {}));
    methods.add_command("test2", world.register_system(|_: In<f32>| {}));
}
```

```rust
#[test]
fn can_call_multiple_fns() {
    let mut methods = YarnCommands::default();
    let mut world = World::default();

    methods.add_command("test1", world.register_system(|_: In<()>| {}));
    methods.add_command(
        "test2",
        world.register_system(|In(a): In<f32>| assert_eq!(1.0, a)),
    );

    {
        let method1 = methods.get_mut("test1").unwrap();
        method1.call(vec![], &mut world);
    }
    let method2 = methods.get_mut("test2").unwrap();
    method2.call(to_method_params([1.0]), &mut world);
}
```

```rust
#[test]
fn can_mutate_world() {
    let mut methods = YarnCommands::default();
    let mut world = World::default();

    methods.add_command(
        "test",
        world.register_system(|In(a): In<f32>, mut commands: Commands| {
            commands.insert_resource(Data(a))
        }),
    );

    #[derive(Resource)]
    struct Data(f32);

    let method = methods.get_mut("test").unwrap();

    method.call(to_method_params([1.0]), &mut world);
    let data = world.resource::<Data>();
    assert_eq!(data.0, 1.0);
}
```

```rust
fn to_method_params(params: impl IntoIterator<Item = impl Into<YarnValue>>) -> Vec<YarnValue> {
    params.into_iter().map(Into::into).collect()
}
```

```rust
#[test]
fn executes_task() {
    let mut methods = YarnCommands::default();
    let mut world = World::default();

    methods.add_command(
        "test",
        world.register_system(|_: In<()>| -> Task<()> {
            let thread_pool = AsyncComputeTaskPool::get_or_init(TaskPool::new);
            thread_pool.spawn(async move { sleep(Duration::from_millis(500)) })
        }),
    );
    let method = methods.get_mut("test").unwrap();
```

--------------------------------

### Display and Debug representations

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/struct.Error.html

Examples of how Error objects are formatted using different display specifiers.

```text
Failed to read instrs from ./path/to/instrs.json
```

```text
Failed to read instrs from ./path/to/instrs.json: No such file or directory (os error 2)
```

```text
Error: Failed to read instrs from ./path/to/instrs.json

Caused by:
    No such file or directory (os error 2)
```

```text
Error: Failed to read instrs from ./path/to/instrs.json

Caused by:
    No such file or directory (os error 2)

Stack backtrace:
   0: <E as anyhow::context::ext::StdError>::ext_context
             at /git/anyhow/src/backtrace.rs:26
   1: core::result::Result<T,E>::map_err
             at /git/rustc/src/libcore/result.rs:596
   2: anyhow::context::<impl anyhow::Context<T,E> for core::result::Result<T,E>>::with_context
             at /git/anyhow/src/context.rs:58
   3: testing::main
             at src/main.rs:5
   4: std::rt::lang_start
             at /git/rustc/src/libstd/rt.rs:61
   5: main
   6: __libc_start_main
   7: _start
```

```text
Error {
    context: "Failed to read instrs from ./path/to/instrs.json",
    source: Os {
        code: 2,
        kind: NotFound,
        message: "No such file or directory",
    },
}
```

--------------------------------

### Using anyhow::Result with Type Parameters

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/type.Result.html

Demonstrates how to use anyhow::Result with one or two type parameters.

```rust
use anyhow::Result;

fn demo1() -> Result<T> {...}
           // ^ equivalent to std::result::Result<T, anyhow::Error>

fn demo2() -> Result<T, OtherError> {...}
           // ^ equivalent to std::result::Result<T, OtherError>
```

--------------------------------

### Yarn Script Command Invocation

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/struct.YarnCommands.html

Example of how a registered command is called within a Yarn script.

```yarn
<<add_player "John" 42>>
```

--------------------------------

### Schedule Configuration Methods

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/struct.YarnSpinnerSystemSet.html

Methods for configuring system sets, including ordering, run conditions, and ambiguity handling.

```APIDOC
## in_set(set: impl SystemSet) -> ScheduleConfigs<T>

### Description
Adds the current systems to the provided system set.

## before<M>(set: impl IntoSystemSet<M>) -> ScheduleConfigs<T>

### Description
Configures the systems to run before all systems in the specified set.

## after<M>(set: impl IntoSystemSet<M>) -> ScheduleConfigs<T>

### Description
Configures the systems to run after all systems in the specified set.

## run_if<M>(condition: impl SystemCondition<M>) -> ScheduleConfigs<T>

### Description
Configures the systems to run only if the provided condition evaluates to true.

## ambiguous_with<M>(set: impl IntoSystemSet<M>) -> ScheduleConfigs<T>

### Description
Suppresses warnings and errors related to system ambiguities with the specified set.

## chain() -> ScheduleConfigs<T>

### Description
Treats the collection of systems as a sequential chain.
```

--------------------------------

### Loading multiple Yarn files

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/struct.YarnSpinnerPlugin.html

Initialize the plugin with a specific list of Yarn file sources.

```rust
use bevy_yarnspinner::prelude::*;
let plugin = YarnSpinnerPlugin::with_yarn_sources([
   YarnFileSource::file("some_dialogue.yarn"),
   YarnFileSource::file("some_other_dialogue.yarn"),
]);
```

--------------------------------

### Registering a Yarn command with parameters

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/commands/command_wrapping.rs.html

Demonstrates how to register a system that accepts parameters from Yarn using the In<T> type.

```rust
# use bevy_yarnspinner::prelude::*;
# use bevy::prelude::*;
# let mut commands = YarnCommands::new();
# let mut world = bevy::prelude::World::default();
commands.add_command("add_player", world.register_system(add_player));

fn add_player(In((name, age)): In<(String, f32)>) {
    println!("Adding player {name} with age {age}");
}
```

--------------------------------

### Define a Yarn dialogue node

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/index.html

A basic Yarn script file defining a starting node.

```yarn
title: Start
---
Hello world!
===
```

--------------------------------

### Configure a system to react to YarnProject loading

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/struct.YarnProject.html

Use resource_added to trigger a system once the YarnProject resource is available in the world.

```rust
app.add_systems(Update, setup_dialogue_runners.run_if(resource_added::<YarnProject>));

fn setup_dialogue_runners(mut commands: Commands, project: Res<YarnProject>) {
   let dialogue_runner = project.create_dialogue_runner(&mut commands);
   commands.spawn(dialogue_runner);
}
```

--------------------------------

### Call a Yarn function from Yarn Spinner

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/trait.YarnFn.html

Example of invoking the registered Rust function within a Yarn script.

```yarn
<<set $name to "Bob">>
<<set $age to 42>>
<<set $is_cool to true>>
Narrator: {give_summary($name, $age, $is_cool)}
```

--------------------------------

### StringTableTextProvider::new

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/default_impl/struct.StringTableTextProvider.html

Creates a new instance of the StringTableTextProvider.

```APIDOC
## pub fn new() -> StringTableTextProvider

### Description
Creates a new `StringTableTextProvider` instance.
```

--------------------------------

### Registering a Command with Parameters

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/trait.YarnCommand.html

Demonstrates registering a command that accepts arguments from Yarn scripts using the In<(String, i32)> type.

```rust
commands.add_command("add_player", world.register_system(add_player));

fn add_player(In((name, age)): In<(String, f32)>) {
    println!("Adding player {name} with age {age}");
}
```

--------------------------------

### Configure FileExtensionAssetProvider with extensions

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/default_impl/struct.FileExtensionAssetProvider.html

Use the file_extensions macro to associate asset types with lists of file extensions during provider initialization.

```rust
use bevy::prelude::*;
use bevy_yarnspinner::file_extensions;
use bevy_yarnspinner::prelude::*;

let file_extension_provider = FileExtensionAssetProvider::new()
    .with_file_extensions(file_extensions! {
       Image: ["png", "jpg", "jpeg"],
       AudioSource: ["mp3", "ogg", "wav"],
    });
```

--------------------------------

### Loading from a specific folder

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/struct.YarnSpinnerPlugin.html

Initialize the plugin to load all Yarn files from a custom directory.

```rust
use bevy_yarnspinner::prelude::*;
let plugin = YarnSpinnerPlugin::with_yarn_source(YarnFileSource::folder("yarn_files"));
```

--------------------------------

### Project Configuration Checks

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/utils.rs.html

Utilities to check development file generation status and localization availability.

```rust
pub(crate) fn in_development(
    project: Option<Res<YarnProject>>,
    project_to_load: Option<Res<YarnProjectConfigToLoad>>,
) -> bool {
    if let Some(project) = project {
        return project.development_file_generation == DevelopmentFileGeneration::Full;
    }
    if let Some(project_to_load) = project_to_load {
        return project_to_load.development_file_generation == DevelopmentFileGeneration::Full;
    }
    false
}

pub(crate) fn has_localizations(
    project: Option<Res<YarnProject>>,
    project_to_load: Option<Res<YarnProjectConfigToLoad>>,
) -> bool {
    if let Some(project) = project {
        return project.localizations.is_some();
    }
    if let Some(project_to_load) = project_to_load {
        return matches!(project_to_load.localizations, Some(Some(_)));
    }
    false
}
```

--------------------------------

### VariableStorage Trait Definition

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/trait.VariableStorage.html

The core trait definition for variable storage, requiring methods for cloning, setting, getting, and managing variable collections.

```rust
pub trait VariableStorage:
    Debug
    + Send
    + Sync {
    // Required methods
    fn clone_shallow(&self) -> Box<dyn VariableStorage>;
    fn set(
        &mut self,
        name: String,
        value: YarnValue,
    ) -> Result<(), VariableStorageError>;
    fn get(&self, name: &str) -> Result<YarnValue, VariableStorageError>;
    fn extend(
        &mut self,
        values: HashMap<String, YarnValue>,
    ) -> Result<(), VariableStorageError>;
    fn variables(&self) -> HashMap<String, YarnValue>;
    fn clear(&mut self);
    fn as_any(&self) -> &(dyn Any + 'static);
    fn as_any_mut(&mut self) -> &mut (dyn Any + 'static);

    // Provided method
    fn contains(&self, name: &str) -> bool { ... }
}
```

--------------------------------

### LineAssets::new

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/struct.LineAssets.html

Creates a new, empty LineAssets instance.

```APIDOC
## pub fn new() -> Self

### Description
Creates a new empty `LineAssets` struct.
```

--------------------------------

### YarnFileSource Convenience Methods

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/enum.YarnFileSource.html

Convenience methods for creating YarnFileSource instances from paths.

```rust
pub fn file(path: impl Into<PathBuf>) -> Self
```

```rust
pub fn folder(path: impl Into<PathBuf>) -> Self
```

--------------------------------

### build

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/struct.DialogueRunnerBuilder.html

Constructs the DialogueRunner instance.

```APIDOC
### Method
`pub fn build(self) -> DialogueRunner`

### Description
Builds the `DialogueRunner`.
```

--------------------------------

### Implement as_any for AssetProvider

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/trait.AssetProvider.html

Standard implementation pattern for the as_any method to support polymorphism.

```rust
fn as_any(&self) -> &dyn Any {
   self
}
```

--------------------------------

### Accept Line Hints

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/dialogue_runner/runtime_interaction.rs.html

System that processes line hints by updating asset providers associated with a dialogue runner.

```rust
fn accept_line_hints(event: On<LineHints>, mut dialogue_runners: Query<&mut DialogueRunner>) {
    let mut dialogue_runner = dialogue_runners.get_mut(event.entity).unwrap();
    for asset_provider in dialogue_runner.asset_providers.values_mut() {
        asset_provider.accept_line_hints(&event.line_ids);
    }
}
```

--------------------------------

### Register StringsFile Asset Plugin

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/localization/strings_file/asset.rs.html

Initializes the StringsFile asset type and its corresponding loader within the Bevy App.

```rust
pub(crate) fn strings_file_asset_plugin(app: &mut App) {
    app.init_asset::<StringsFile>()
        .init_asset_loader::<StringsFileAssetLoader>();
}
```

--------------------------------

### YarnLibrary::new

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/struct.YarnLibrary.html

Creates a new, empty YarnLibrary instance.

```APIDOC
## pub fn new() -> Library

### Description
Creates a new empty library. Does not include the functions of `Library::standard_library`.
```

--------------------------------

### YarnFile::new

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/struct.YarnFile.html

Creates a new instance of a Yarn file using a filename and its content.

```APIDOC
## pub fn new(filename: impl Into<String>, content: impl Into<String>) -> Self

### Description
Creates a new Yarn file from a provided filename and file content.

### Parameters
- **filename** (impl Into<String>) - Required - The name of the Yarn file.
- **content** (impl Into<String>) - Required - The string content of the Yarn file.
```

--------------------------------

### YarnCommands Implementation

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/commands/command_registry.rs.html

The core implementation of the command registry, including plugin registration and the YarnCommands struct definition.

```rust
use crate::commands::UntypedYarnCommand;
use crate::commands::command_wrapping::YarnCommandWrapper;
use crate::prelude::*;
use bevy::prelude::*;
use std::borrow::Cow;
use std::collections::HashMap;
use std::time::Duration;

pub(crate) mod wait;

pub(crate) fn command_registry_plugin(app: &mut App) {
    app.add_plugins(wait::wait_command_plugin);
}

#[derive(Debug, PartialEq, Eq, Default)]
/// A registry of commands that can be called from Yarn after they have been added via [`YarnCommands::add_command`].
/// You can get access to an instance of this struct with [`DialogueRunner::commands`] and [`DialogueRunner::commands_mut`].
///
/// If a command "add_player" with the parameters "name" and "age" has been registered, it can be called from Yarn like this:
/// ```text
/// <<add_player "John" 42>>
/// ```
pub struct YarnCommands(pub(crate) InnerRegistry);

type InnerRegistry = HashMap<Cow<'static, str>, Box<dyn UntypedYarnCommand>>;

impl Extend<<InnerRegistry as IntoIterator>::Item> for YarnCommands {
    fn extend<T: IntoIterator<Item = <InnerRegistry as IntoIterator>::Item>>(&mut self, iter: T) {
        self.0.extend(iter);
    }
}

impl IntoIterator for YarnCommands {
    type Item = <InnerRegistry as IntoIterator>::Item;
    type IntoIter = <InnerRegistry as IntoIterator>::IntoIter;

    fn into_iter(self) -> Self::IntoIter {
        self.0.into_iter()
    }
}

impl YarnCommands {
    /// Instantiates a new, empty registry.
    pub fn new() -> Self {
        Self::default()
    }

    /// Adds a new method to the registry. Commands are valid Bevy systems with input and output.
    ///
    /// See the documentation of [`YarnCommand`] for more information about which methods are allowed.
    pub fn add_command<Marker, F>(
        &mut self,
        name: impl Into<Cow<'static, str>>,
        command: F,
    ) -> &mut Self
    where
        Marker: 'static,
        F: YarnCommand<Marker> + 'static + Clone,
    {
        let name = name.into();
        let wrapped = YarnCommandWrapper::from(command);
        self.0.insert(name, Box::new(wrapped));
        self
    }

    /// Iterates over all registered commands.
    pub fn iter(&self) -> impl Iterator<Item = (&str, &dyn UntypedYarnCommand)> {
        self.0
            .iter()
            .map(|(key, value)| (key.as_ref(), value.as_ref()))
    }

    /// Returns `true` if the registry contains a command with the given name.
    pub fn contains_key(&self, name: &str) -> bool {
        self.get(name).is_some()
    }

    /// Returns a reference to the command with the given name, if it exists.
    pub fn get(&self, name: &str) -> Option<&dyn UntypedYarnCommand> {
        self.0.get(name).map(|f| f.as_ref())
    }

    /// Returns a mutable reference to the command with the given name, if it exists.
    pub fn get_mut(&mut self, name: &str) -> Option<&mut dyn UntypedYarnCommand> {
        self.0.get_mut(name).map(|f| f.as_mut())
    }

    /// Iterates over all registered command names.
    pub fn names(&self) -> impl Iterator<Item = &str> {
        self.0.keys().map(|key| key.as_ref())
    }

    /// Iterates over all registered commands.
    pub fn commands(&self) -> impl Iterator<Item = &dyn UntypedYarnCommand> {
        self.0.values().map(|value| value.as_ref())
    }

    /// Returns the number of registered commands.
    pub fn len(&self) -> usize {
        self.0.len()
    }

    /// Returns `true` if the registry contains no commands.
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }

    /// Constructs an instance of [`YarnCommands`] with the builtin commands `wait` and `stop`.
    /// - `stop`: Stops the execution of the dialogue.
    /// - `wait`: Waits for the given amount of seconds before continuing the dialogue. Note that this does not block and that Bevy will continue updating as normal in the meantime.
    pub fn builtin_commands(bevy_commands: &mut Commands) -> Self {
        let mut commands = Self::default();

        commands.add_command(
            "wait",
            bevy_commands.register_system(|In(duration): In<f32>, mut wait: ResMut<Wait>| {
                wait.add(Duration::from_secs_f32(duration))
            }),
        );

        #[allow(clippy::unused_unit)] // Needed for 2024 edition
        commands.add_command(
            "stop",
            bevy_commands.register_system(|_: In<()>| -> () {
                unreachable!("The stop command is a compiler builtin and is thus not callable");
            }),
        );
```

--------------------------------

### Create Extended Standard Library

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/dialogue_runner/builder.rs.html

Initializes a YarnLibrary with additional mathematical functions like random, rounding, and increment/decrement operations.

```rust
fn create_extended_standard_library() -> YarnLibrary {
    let mut library = YarnLibrary::standard_library();
    library
        .add_function("random", || SmallRng::from_os_rng().random_range(0.0..1.0))
        .add_function("random_range", |min: f32, max: f32| {
            if let Some(min) = min.as_int()
                && let Some(max_inclusive) = max.as_int()
            {
                return SmallRng::from_os_rng().random_range(min..=max_inclusive) as f32;
            }
            SmallRng::from_os_rng().random_range(min..max)
        })
        .add_function("dice", |sides: u32| {
            if sides == 0 {
                return 1;
            }
            SmallRng::from_os_rng().random_range(1..=sides)
        })
        .add_function("round", |num: f32| num.round() as i32)
        .add_function("round_places", |num: f32, places: u32| {
            num.round_places(places)
        })
        .add_function("floor", |num: f32| num.floor() as i32)
        .add_function("ceil", |num: f32| num.ceil() as i32)
        .add_function("inc", |num: f32| {
            if let Some(num) = num.as_int() {
                num + 1
            } else {
                num.ceil() as i32
            }
        })
        .add_function("dec", |num: f32| {
            if let Some(num) = num.as_int() {
                num - 1
            } else {
                num.floor() as i32
            }
        })
        .add_function("decimal", |num: f32| num.fract())
        .add_function("int", |num: f32| num.trunc() as i32);
    library
}
```

--------------------------------

### Registering Types and Sub-plugins

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/plugin.rs.html

Methods for registering reflection types and adding necessary sub-plugins to the Bevy App.

```rust
.register_type::<DialogueEvent>()
            .register_type::<yarnspinner::runtime::Line>()
            .register_type::<yarnspinner::runtime::Diagnosis>()
            .register_type::<yarnspinner::runtime::DiagnosisSeverity>()
            .register_type::<yarnspinner::runtime::MarkupParseError>()
            .register_type::<MarkupAttribute>()
            .register_type::<MarkupValue>()
    }

    fn register_sub_plugins(&mut self) -> &mut Self {
        self.add_plugins(crate::yarn_file_asset::yarnspinner_asset_loader_plugin)
            .add_plugins(crate::localization::localization_plugin)
            .add_plugins(crate::dialogue_runner::dialogue_plugin)
            .add_plugins(crate::line_provider::line_provider_plugin)
            .add_plugins(crate::project::project_plugin)
            .add_plugins(crate::commands::commands_plugin)
            .add_plugins(crate::development_file_generation::development_file_generation_plugin)
    }
```

--------------------------------

### Configure Option Presentation

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/dialogue_runner.rs.html

Configures whether selected options should be treated as lines and displayed via PresentLine events.

```rust
pub fn run_selected_options_as_lines(
        &mut self,
        run_selected_options_as_lines: bool,
    ) -> &mut Self {
        self.run_selected_options_as_lines = run_selected_options_as_lines;
        self
    }
```

```rust
pub fn runs_selected_options_as_lines(&self) -> bool {
        self.run_selected_options_as_lines
    }
```

--------------------------------

### Configure Localization Paths

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/localization/localizations.rs.html

Use these builder methods to define the location of strings files and asset subdirectories relative to the assets folder.

```rust
/// Sets the path to the strings file for this localization inside the `assets` folder.
pub fn with_strings_file(mut self, strings_file: impl Into<PathBuf>) -> Self {
    self.strings_file = strings_file.into();
    self
}

/// Sets the path to the subdirectory containing the assets for this localization inside the `assets` folder.
pub fn with_assets_sub_folder(mut self, assets_sub_folder: impl Into<PathBuf>) -> Self {
    self.assets_sub_folder = assets_sub_folder.into();
    self
}
```

--------------------------------

### Manage Asset and Text Availability

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/dialogue_runner.rs.html

Methods to check if text and assets are fully loaded and available for the dialogue.

```rust
    #[must_use]
    pub fn update_line_availability(
        &mut self,
        loaded_untyped_assets: &Assets<LoadedUntypedAsset>,
    ) -> bool {
        self.are_texts_available() && self.update_asset_availability(loaded_untyped_assets)
    }

    #[must_use]
    fn are_texts_available(&self) -> bool {
        self.text_provider.are_lines_available()
    }

    #[must_use]
    fn update_asset_availability(
        &mut self,
        loaded_untyped_assets: &Assets<LoadedUntypedAsset>,
    ) -> bool {
        self.asset_providers
            .values_mut()
            .all(|provider| provider.update_asset_availability(loaded_untyped_assets))
    }
```

--------------------------------

### Wait Command Implementation

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/commands/command_registry/wait.rs.html

Registers the wait command system and provides a resource to track active wait periods.

```rust
//! In an ideal world, this would just be a new thread doing `sleep`.
//! Alas, Wasm forces us to do this

use crate::prelude::YarnSpinnerSystemSet;
use bevy::platform::collections::HashMap;
use bevy::prelude::*;
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
use std::time::Duration;

pub(crate) fn wait_command_plugin(app: &mut App) {
    app.init_resource::<Wait>()
        .add_systems(Update, update_wait.in_set(YarnSpinnerSystemSet));
}

#[derive(Debug, Clone, Resource, Default)]
pub(crate) struct Wait(HashMap<Duration, WaitPeriod>);

#[derive(Debug, Clone)]
pub(crate) struct WaitPeriod {
    duration: Duration,
    done: Arc<AtomicBool>,
}

impl Wait {
    pub(crate) fn add(&mut self, duration: Duration) -> Arc<AtomicBool> {
        let done = Arc::new(AtomicBool::new(false));
        self.0.insert(
            duration,
            WaitPeriod {
                duration,
                done: done.clone(),
            },
        );
        done
    }
}

pub(crate) fn update_wait(time: Res<Time>, mut wait: ResMut<Wait>) {
    for period in wait.0.values_mut() {
        if period.duration <= time.delta() {
            period.duration = Duration::from_secs(0);
            period.done.store(true, Ordering::Relaxed);
        } else {
            period.duration -= time.delta();
        }
    }
    wait.0.remove(&Duration::from_secs(0));
}
```

--------------------------------

### Text Provider Module Implementation

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/line_provider/text_provider.rs.html

The core module file defining the TextProvider trait and the plugin for managing text resources.

```rust
1use crate::UnderlyingTextProvider;
2use crate::line_provider::LineProviderSystemSet;
3use crate::prelude::*;
4use bevy::prelude::*;
5pub(crate) use shared_text_provider::SharedTextProvider;
6use std::any::Any;
7use std::collections::HashMap;
8pub use strings_file_text_provider::StringsFileTextProvider;
9
10mod shared_text_provider;
11mod strings_file_text_provider;
12
13pub(crate) fn text_provider_plugin(app: &mut App) {
14    app.add_plugins(shared_text_provider::shared_text_provider_plugin)
15        .add_plugins(strings_file_text_provider::strings_file_text_provider_plugin)
16        .add_systems(
17            Update,
18            fetch_resources
19                .in_set(LineProviderSystemSet)
20                .in_set(YarnSpinnerSystemSet),
21        );
22}
23
24/// Trait for the provider the [`DialogueRunner`]s text. By default, this is a [`StringsFileTextProvider`].
25/// You can override this with [`DialogueRunnerBuilder::with_text_provider`] if you want a custom localization strategy.
26/// For most users however, the default is fine.
27pub trait TextProvider: UnderlyingTextProvider {
28    /// Stores a string table containing the base language strings, i.e. the strings found in the Yarn files themselves.
29    fn set_base_string_table(&mut self, string_table: HashMap<LineId, StringInfo>);
30
31    /// Extends the string table set by [`TextProvider::set_base_string_table`] with additional strings.
32    fn extend_base_string_table(&mut self, string_table: HashMap<LineId, StringInfo>);
33
34    /// Stores the assets fetched by [`TextProvider::fetch_assets`].
35    /// This functionality is split into two functions because [`TextProvider::take_fetched_assets`] is mutable,
36    /// so we lose access to the [`World`] when calling it since it contains this very [`TextProvider`].
37    ///
38    fn take_fetched_assets(&mut self, asset: Box<dyn Any>);
39    /// Fetches any necessary assets. The returned value is then passed to [`TextProvider::take_fetched_assets`].
40    /// This functionality is split into two functions because [`TextProvider::take_fetched_assets`] is mutable,
41    /// so we lose access to the [`World`] when calling it since it contains this very [`TextProvider`].
42    fn fetch_assets(&self, world: &World) -> Option<Box<dyn Any + 'static>>;
43}
44
45pub(crate) fn fetch_resources(world: &mut World) {
46    let dialogue_runner_entities: Vec<_> = world
47        .query_filtered::<Entity, With<DialogueRunner>>()
48        .iter(world)
49        .collect();
50
51    for entity in dialogue_runner_entities {
52        let assets = {
53            let dialogue_runner = world.get::<DialogueRunner>(entity).unwrap();
54            dialogue_runner.text_provider.fetch_assets(world)
55        };
56        if let Some(assets) = assets {
57            let mut dialogue_runner = world.get_mut::<DialogueRunner>(entity).unwrap();
58            dialogue_runner.text_provider.take_fetched_assets(assets)
59        }
60    }
61}
```

--------------------------------

### with_text_provider

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/struct.DialogueRunnerBuilder.html

Replaces the default TextProvider with a custom implementation.

```APIDOC
### Method
`pub fn with_text_provider(self, provider: impl TextProvider + 'static) -> Self`

### Description
Replaces the `TextProvider` used by the `DialogueRunner`. By default, this is a `StringsFileTextProvider`.
```

--------------------------------

### Implement as_any_mut for AssetProvider

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/trait.AssetProvider.html

Standard implementation pattern for the as_any_mut method to support mutable polymorphism.

```rust
fn as_any_mut(&mut self) -> &mut dyn Any {
    self
}
```

--------------------------------

### Load Yarn Project System

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/project/compilation.rs.html

System that processes LoadYarnProjectEvent to initialize project configuration and file loading queues.

```rust
fn load_project(
    mut commands: Commands,
    mut events: ResMut<Messages<LoadYarnProjectEvent>>,
    is_watching_for_changes: Res<WatchingForChanges>,
    mut already_loaded: Local<bool>,
) -> SystemResult {
    for event in events.drain() {
        if *already_loaded {
            bail!(
                "Yarn project already loaded. Sending multiple LoadYarnProjectEvent is not allowed."
            );
        }
        assert!(
            !event.yarn_files.is_empty(),
            "Failed to load Yarn project in deferred mode: no Yarn files were specified. \
            Did run `LoadYarnProjectEvent::empty()` without adding any Yarn files with `LoadYarnProjectEvent::add_yarn_file` and `LoadYarnProjectEvent::add_yarn_files`? \
            If you wanted to load from the default directory instead, use `LoadYarnProjectEvent::default()`."
        );
        if event.development_file_generation == DevelopmentFileGeneration::Full
            && !is_watching_for_changes.0
        {
            warn!(
                "Development file generation mode is set to `Full`, but hot reloading is not turned on. \
                For an optimal development experience, we recommend turning on hot reloading by activating the \"file_watcher\" feature of Bevy"
            );
        }

        commands.insert_resource(YarnProjectConfigToLoad {
            localizations: Some(event.localizations),
            watching_for_changes: is_watching_for_changes.0,
            development_file_generation: event.development_file_generation,
        });
        commands.insert_resource(YarnFilesToLoad(event.yarn_files));
        *already_loaded = true;
    }
    Ok(())
}
```

--------------------------------

### StringsFileTextProvider::from_yarn_project

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/default_impl/struct.StringsFileTextProvider.html

Creates a new instance of StringsFileTextProvider from a given YarnProject.

```APIDOC
## pub fn from_yarn_project(yarn_project: &YarnProject) -> Self

### Description
Creates a new text provider from a Yarn project. This is typically handled automatically when using `YarnProject::create_dialogue_runner` or `YarnProject::build_dialogue_runner`.

### Parameters
- **yarn_project** (&YarnProject) - Required - The Yarn project instance to initialize the provider with.

### Returns
- **Self** - A new instance of `StringsFileTextProvider`.
```

--------------------------------

### try_build

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/dialogue_runner/builder.rs.html

Attempts to construct the DialogueRunner instance.

```APIDOC
### Method
`try_build(mut self) -> Result<DialogueRunner>`

### Description
Builds the DialogueRunner and returns a Result, allowing for graceful error handling.
```

--------------------------------

### Loading Assets and Handling Unsupported Languages

Source: https://docs.rs/bevy_yarnspinner/0.7.0/src/bevy_yarnspinner/line_provider/asset_provider/file_extension_asset_provider_plugin.rs.html

Handles loading assets via the asset server and panics if the requested language is not supported by localizations.

```rust
let handle = asset_server.load_untyped(asset_path);
self.loading_handles.insert(path, handle);
}
}
} else {
panic!(
"Tried to find an asset for \"{language}\", which is a language that is not supported by localizations"
);
}
}
}
}
```

--------------------------------

### Language::new

Source: https://docs.rs/bevy_yarnspinner/0.7.0/bevy_yarnspinner/prelude/struct.Language.html

Creates a new Language instance from a string. This method will panic if the provided string is not a valid IETF BCP 47 code.

```APIDOC
## Language::new(language: impl Into<String>) -> Language

### Description
Creates a new `Language` instance from a string. The input must be a valid IETF BCP 47 code.

### Parameters
- **language** (impl Into<String>) - Required - The language code string (e.g., "en-US").

### Returns
- **Language** - A new instance of the Language struct.
```
Tokens:
Raw