#bevy #gamedev #asset #assets

bevy_asset_loader

Bevy plugin for asset loading

7 releases (breaking)

0.6.0 Oct 1, 2021
0.5.0 Aug 8, 2021
0.4.0 Jun 26, 2021
0.3.0 Jun 26, 2021
0.1.0 May 19, 2021

#62 in Game dev

Download history 39/week @ 2021-07-05 46/week @ 2021-07-12 96/week @ 2021-07-19 33/week @ 2021-07-26 66/week @ 2021-08-02 98/week @ 2021-08-09 140/week @ 2021-08-16 76/week @ 2021-08-23 35/week @ 2021-08-30 61/week @ 2021-09-06 88/week @ 2021-09-13 44/week @ 2021-09-20 74/week @ 2021-09-27 125/week @ 2021-10-04 64/week @ 2021-10-11 26/week @ 2021-10-18

287 downloads per month

MIT/Apache

345KB
583 lines

Bevy asset loader

crates.io docs license crates.io

This Bevy plugin reduces boilerplate when loading game assets. The crate offers the AssetCollection trait and can automatically load structs that implement it. The trait can be derived.

The main branch and all current releases support Bevy version 0.5. If you like living on the edge, take a look at the bevy_main branch, which tries to stay close to Bevy's development.

How to use

The AssetLoader is constructed with two states (see the cheatbook on states). During the first state it will load the assets and check up on the loading status in every frame. When the assets are done loading, the collections will be inserted as resources, and the plugin switches to the second state.

For structs with named fields that are either asset handles or implement default, AssetCollection can be derived. You can add as many AssetCollections to the loader as you want by chaining with_collection calls. To finish the setup, call the build function with your AppBuilder.

Now you can start your game logic from the second configured state and use the asset collections as resources in your systems.

use bevy::prelude::*;
use bevy_asset_loader::{AssetLoader, AssetCollection};

fn main() {
  let mut app = App::build();
  AssetLoader::new(GameState::AssetLoading, GameState::Next)
          .with_collection::<TextureAssets>()
          .with_collection::<AudioAssets>()
          .build(&mut app);
  app.add_state(GameState::AssetLoading)
          .add_plugins(DefaultPlugins)
          .add_system_set(SystemSet::on_enter(GameState::Next).with_system(use_my_assets.system()))
          .run();
}

#[derive(AssetCollection)]
struct AudioAssets {
  #[asset(path = "walking.ogg")]
  walking: Handle<AudioSource>
}

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

fn use_my_assets(_texture_assets: Res<TextureAssets>, _audio_assets: Res<AudioAssets>) {
  // do something using the asset handles from the resources
}

#[derive(Clone, Eq, PartialEq, Debug, Hash)]
enum GameState {
  AssetLoading,
  Next,
}

See two_collections.rs for a complete example.

Initialize FromWorld resources

In situations where you would like to prepare other resources based on your loaded assets you can use AssetLoader::init_resource to initialize FromWorld resources. See init_resource.rs for an example that loads two textures and then combines their image data into a third texture.

AssetLoader::init_resource does the same as Bevy's App::init_resource, but at a different point in time. While Bevy inserts your resources at the very beginning, the AssetLoader will do so after having inserted your loaded asset collections. That means that you can use your asset collections in the FromWorld implementations.

Loading color materials

You can directly load color materials. For a complete example please take a look at color_material.rs.

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

This requires the feature sprite which is part of the default features

Loading texture atlases

You can directly load texture atlases from sprite sheets. For a complete example please take a look at atlas_from_grid.rs.

#[derive(AssetCollection)]
struct MyAssets {
    #[asset(texture_atlas(tile_size_x = 100., tile_size_y = 96., columns = 8, rows = 1, padding_x = 12., padding_y = 12.))]
    #[asset(path = "textures/sprite_sheet.png")]
    sprite: Handle<TextureAtlas>,
}

This requires the feature render which is part of the default features

Development

The integration tests cannot run with default features enabled. Because they do not insert the render plugin of Bevy, they fail due to the derive macro requiring the TextureAtlas asset collection (this is toggled with the render feature).
Use cargo test --no-default-features to run all tests.

License

Licensed under either of

at your option.

Assets in the examples might be distributed under different terms. See the readme in the bevy_asset_loader/examples directory.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~8–11MB
~218K SLoC