bevy_asset_loader

Bevy asset loader

Loading states with minimal boilerplate

This [Bevy][bevy] plugin reduces boilerplate for handling game assets. The crate offers the derivable AssetCollection trait and can automatically load structs that implement it. Asset collections contain handles to your game assets and are available to your systems as resources after loading.

In most cases you will want to load your asset collections during loading states (think loading screens). During such a state, all assets are loaded and their loading progress is observed. Only when asset collections can be built with fully loaded asset handles, the collections are inserted to Bevy's ECS as resources. If you do not want to use a loading state, asset collections can still result in cleaner code and improved maintainability (see the "usage without a loading state" section).

For compatibility information, take a look at the version table)

Loading states

A loading state is responsible for managing the loading process during a configurable Bevy state (see [the cheatbook on states][cheatbook-states]).

If your LoadingState is set up, you can start your game logic from the configured "next state" and use the asset collections as resources in your systems. The loading state guarantees that all handles in your collections are fully loaded by the time the next state starts.

…

If we want to add additional asset collections to the just added loading state, we can do so using configure_loading_state at any point in our application. We could, for example, add a PlayerPlugin to the App after adding the loading state. The PlayerPlugin will contain all things "player" including its sprite.

use bevy::prelude::*;
use bevy_asset_loader::prelude::*;

struct PlayerPlugin;

impl Plugin for PlayerPlugin {
    fn build(&self, app: &mut App) {
        app
            .configure_loading_state(
                LoadingStateConfig::new(MyStates::AssetLoading)
                    .load_collection::(),
            );
    }
}

#[derive(AssetCollection, Resource)]
struct PlayerAssets {
    #[asset(path = "images/player.png")]
    sprite: Handle,
}

#[derive(Clone, Eq, PartialEq, Debug, Hash, Default, States)]
enum MyStates {
    #[default]
    AssetLoading,
    Next,
}

Compile time vs. Run time (dynamic) assets

Asset configurations, like their file path or dimensions of sprite sheets, can be given at compile time (through derive macro attributes), or at run time ("Dynamic assets"). The second, allows managing asset configurations as assets. That means you can keep a list of your asset files and their properties in asset files. The main benefit of using dynamic assets is a cleaner split of code and data leading to less recompiles while working on your assets. It also makes your game more approachable for people that want to contribute without touching code.

The derive macro for AssetCollection supports multiple attributes. They configure how the asset is loaded.

Compile time assets

The two earlier code examples show a loading state with collections that have all their configuration in derive macro attributes. The path of the player sprite is hardcoded to be "images/player.png". Changing it will require recompiling your application.

The full_collection example showcases all the different kinds of fields that an asset collection can contain using only derive macro attributes.

Dynamic assets

Dynamic assets are configured through the derive macro attribute key and are not allowed to have a path or paths attribute:

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct ImageAssets {
  #[asset(key = "player")]
  player: Handle,
  #[asset(key = "tree")]
  tree: Handle,
}

The keys player and tree in the example above should either be set manually in the DynamicAssets resource prior to the loading state (see the manual_dynamic_asset example), or be part of a dynamic assets file (see dynamic_asset.rs). A dynamic assets file for the collection above might look like this:

({
    "player": File (
        path: "images/player.png",
    ),
    "tree": File (
        path: "images/tree.png",
    ),
})

Using dynamic assets like File and loading ron files requires the standard_dynamic_assets feature to be enabled.

The file ending is .assets.ron by default, but can be configured via LoadingState::set_standard_dynamic_asset_collection_file_endings.

The example full_dynamic_collection shows all supported field types for dynamic assets. Note that adding a dynamic asset file to a loading state requires the AssetServer resource to be available. In most cases that means that you should add the DefaultPlugins before configuring your loading state.

Custom dynamic assets

You can define your own types to load as dynamic assets. Take a look at the custom_dynamic_assets.rs example for some code.

Supported asset fields

The simplest field is of the type Handle and is loaded from a single file. One example might be audio sources, but any asset type that has an asset loader registered with Bevy can be used like this.

The field should only have the path attribute set.

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(path = "my-background.ogg")]
    background: Handle,
}

The dynamic version of the same collection looks like this:

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(key = "background")]
    background: Handle,
}

({
    "background": File (
        path: "my-background.ogg",
    ),
})

The following sections describe more types of asset fields that you can load through asset collections.

Texture atlases

You can create texture atlas layouts as part of an AssetCollection if you enable the feature 2d. For a complete example please take a look at atlas_from_grid.rs.

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(texture_atlas_layout(tile_size_x = 64, tile_size_y = 64, columns = 8, rows = 1, padding_x = 12, padding_y = 12, offset_x = 6, offset_y = 6))]
    layout: Handle,
    #[asset(path = "images/sprite_sheet.png")]
    sprite: Handle,
}

As a dynamic asset this example becomes:

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(key = "player.layout")]
    layout: Handle,
    #[asset(key = "player.image")]
    sprite: Handle,
}

({
    "player.image": File (
        path: "images/sprite_sheet.png",
    ),
    "player.layout": TextureAtlasLayout (
        tile_size_x: 100,
        tile_size_y: 64,
        columns: 8,
        rows: 1,
        padding_x: 12,
        padding_y: 12,
        offset_x: 6,
        offset_y: 6,
    ),
})

The four padding & offset fields/attributes are optional, and default to 0.

Images with sampler configuration

Asset collections support configuring the sampler of an image asset through a derive attribute:

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct ImageAssets {
    #[asset(path = "images/pixel_tree.png")]
    #[asset(image(sampler(filter = linear)))]
    tree_linear: Handle,

    #[asset(path = "images/pixel_tree.png")]
    #[asset(image(sampler(filter = nearest)))]
    tree_nearest: Handle,

    #[asset(path = "images/pixel_tree.png")]
    #[asset(image(sampler(filter = linear, wrap = repeat)))]
    tree_linear_repeat: Handle,
}

The corresponding dynamic asset would be

({
    "tree_nearest": Image (
        path: "images/tree.png",
        filter: Nearest,
        wrap: Clamp
    ),
    "tree_linear": Image (
        path: "images/tree.png",
        filter: Linear,
        wrap: Clamp
    ),
    "tree_linear_repeat": Image (
        path: "images/tree.png",
        filter: Linear,
        wrap: Repeat
    ),
})

Array images

You can let bevy_asset_loader configure the layers of a texture array.

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct ImageAssets {
    #[asset(path = "images/array_texture.png")]
    #[asset(image(array_texture_layers = 4))]
    array_texture: Handle,
}

The corresponding dynamic asset would be

({
    "array_texture": Image (
        path: "images/array_texture.png",
        array_texture_layers: 4
    ),
})

Standard materials

You can directly load standard materials if you enable the feature 3d. For a complete example please take a look at standard_material.rs.

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(standard_material)]
    #[asset(path = "images/player.png")]
    player: Handle,
}

This is also supported as a dynamic asset:

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(key = "image.player")]
    player: Handle,
}

({
    "image.player": StandardMaterial (
        path: "images/player.png",
    ),
})

Collections

Folders

This asset field type is not supported in web builds. See Files for a web compatible way of loading a collection of files.

You can load all files in a folder as a vector of untyped handles. This field requires the additional derive macro attribute collection:

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(path = "images", collection)]
    folder: Vec,
}

Just like Bevy's load_folder, this will also recursively load sub folders.

If all assets in the folder have the same (known) type, you can load the folder as Vec> by setting typed in the collection attribute. Don't forget to adapt the type of the struct field:

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(path = "images", collection(typed))]
    folder: Vec,
}

Folders are also supported as a dynamic asset. The path attribute is replaced by the key attribute:

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(key = "my.images", collection(typed))]
    images: Vec,
}

({
    "my.images": Folder (
        path: "images",
    ),
})

Loading folders is not supported for web builds. If you want to be compatible with Wasm, load you handles from a list of paths instead (see next section).

List of paths

If you want to load a list of asset files with the same type into a vector of Handle, you can list their paths in an attribute:

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(paths("images/player.png", "images/tree.png"), collection(typed))]
    files_typed: Vec,
}

In case you do not know their types, or they might have different types, the handles can also be untyped:

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollectio