bevy_asset_loader

The repository includes several examples covering different use cases for asset loading in Bevy:

Asset Types & Configurations

• Texture Atlases: atlas_from_grid.rs (Loading a texture atlas from a sprite sheet)
• Images: image_asset.rs (Setting different samplers for image assets)
• Materials: standard_material.rs (Loading a standard material from a png file)
• Dynamic Assets:
  • dynamic_asset.rs (Loading dynamic assets from a .ron file)
  • custom_dynamic_assets.rs (Defining and using your own dynamic assets)
  • manual_dynamic_asset.rs (Loading an image asset from a path resolved at run time)
  • dynamic_asset_arrays.rs (Defining dynamic assets in arrays)

Collection & State Management

• Collections:
  • full_collection.rs (Complete collection with all supported non-dynamic field types)
  • full_dynamic_collection.rs (Complete collection with all supported dynamic asset field types)
  • two_collections.rs (Loading multiple asset collections)
  • asset_maps.rs (Using different types as keys in asset maps)
• States & Loading:
  • failure_state.rs (Setting up a failure state)
  • no_loading_state.rs (Using asset collections without a loading state)
  • sub_state.rs (Using a sub state)
  • finally_init_resource.rs (Inserting a FromWorld resource when all asset collections are loaded)
  • progress_tracking.rs (Setting up progress tracking using iyes_progress)

A LoadingState manages the asset loading process during a specific Bevy State. It observes the loading progress of all assets in the provided collections. Once all assets in the collections are fully loaded, the collections are inserted into Bevy's ECS as Resources, and the application transitions to the configured 'next state'. This ensures that when your game logic starts in the next state, all asset handles are ready for use.

To use a loading state:

1. Define a State enum.
2. Create a struct that implements AssetCollection and Resource.
3. Use .add_loading_state() on your App to configure the loading state, the target state to transition to, and the collections to load.

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

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .init_state::<MyStates>()
        .add_loading_state(
            LoadingState::new(MyStates::AssetLoading)
                .continue_to_state(MyStates::Next)
                .load_collection::<AudioAssets>(),
        )
        .add_systems(OnEnter(MyStates::Next), start_background_audio)
        .run();
}

#[derive(AssetCollection, Resource)]
struct AudioAssets {
    #[asset(path = "audio/background.ogg")]
    background: Handle<AudioSource>,
}

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

fn start_background_audio(mut commands: Commands, audio_assets: Res<AudioAssets>) {
    // AudioAssets is available as a resource and handles are fully loaded
    commands.spawn((AudioPlayer(audio_assets.background.clone()), PlaybackSettings::LOOP));
}

If you do not want to use Bevy states for loading, you can still use bevy_asset_loader to reduce boilerplate by deriving AssetCollection on a resource. This allows you to initialize asset collections directly on the Bevy App or World using .init_collection::<T>().

Limitations of no-loading-state collections:

• They do not support folders.
• They do not support dynamic assets.
• They do not support the image annotation.

These features require a waiting mechanism (loading states) to ensure assets are fully loaded before they are accessed.

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

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .init_collection::<MyAssets>()
        .run();
}

#[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<TextureAtlasLayout>,
    #[asset(path = "images/sprite_sheet.png")]
    sprite: Handle<Image>,
}

The bevy_asset_loader crate simplifies asset management in Bevy by automating the loading process during a specific State.

The Workflow:

1. Define Collections: You create structs representing groups of assets and derive the AssetCollection trait for them. Each field in the struct represents an asset, annotated with #[asset(path = "...")] to specify its location.
2. Configure Loading State: You use LoadingState to define which state the game starts in (e.g., GameState::Loading), which state to transition to once assets are ready (e.g., GameState::Next), and which AssetCollection structs to load.
3. Automatic Resource Insertion: Once all assets in the specified collections are loaded, the plugin automatically inserts the collections as Bevy Resources into the ECS.
4. State Transition: The plugin automatically switches the app's state to the configured 'next' state.
5. Usage: In your game systems, you can now access the loaded handles directly via Res<YourAssetCollectionStruct>.

use bevy_asset_loader::prelude easily;
use bevy::prelude easily;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(path = "textures/player.png")]
    player: Handle<Image>,
}

#[derive(States, Clone, Eq, PartialEq, Debug, Hash, Default)]
enum GameState {
    #[default]
    Loading,
    Playing,
}

fn main() {
    App::new()
        .init_state::<GameState>()
        .add_loading_state(
            LoadingState::new(GameState::Loading)
                .continue_to_state(GameState::Playing)
                .load_collection::<MyAssets>()
        )
        .run();
}