๐ฅCompiling Yarn Files into Yarn Projects
Learn about Yarn Projects, which group your scripts together for use in a Dialogue Runner.
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.
Settings
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.
Yarn File Sources
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 YarnFileSource
s. 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 theassets
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"))
.
Development File Generation
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 Localization 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.
Localization
The settings accessed by YarnSpinnerPlugin::with_localizatons
are important enough to warrant their own chapter. See Localization.
After the Compilation
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>()).
Once you have the YarnProject
, you can use it to spawn a DialogueRunner
which in turn can, well, run dialogues.
Last updated