Crate bevy_embasset

Bevy-Embasset

Embed your asset folder inside your binary.

bevy-embasset adds support for loading assets embedded into the binary.

Furthermore, it can optionally try to load assets via the default AssetPlugin first, thereby allowing the embedded assets to be used as fallbacks in case of problems.

As icing on the cake, bevy-embasset allows to register multiple other AssetServer’s, that will be used for asset paths beginning with specific configurable strings. This can be used to have some assets load from e.g. a web-service, while others are loaded from disk or embedded in the binary. It can also be used to e.g. build 1 or more sub-crates each using EmbassetIo and holding a set of assets - thereby saving compile-time as the assets don’t have to be compiled every time (An example of this, can be found in the game bevoids).

Usage

Recommended

An easy way of adding an enum with some assets, an AssetIo handling those assets, and adding the EmbassetIo that can handle all the loading/routing is:

use bevy::{prelude::*, asset::AssetPlugin};
use bevy_embasset::{EmbassetPlugin, embasset_assets};

embasset_assets!(
    pub enum GameAssets {
        #[doc = "It's possible to document each enum variant"]
        Icon = "icon.png",
        BackgroundMusic = "sounds/bg.wav"
    },
    pub struct GameAssetsIo {
        root = "../assets/"
    }
);

fn main() {
    App::new().add_plugins_with(DefaultPlugins, |group| {
        group.add_before::<AssetPlugin, _>(EmbassetPlugin::new(|io| {
            io.add_handler(GameAssetsIo::new().into());
        }))
    });
}

Note, in the above example, GameAssets and GameAssetsIo (defined by the macro) can be moved to a separate crate - saving compile time.

The defined GameAssets implements several useful standard traits: Eq, Ord, Hash, Copy. It can be iterated over by invoking GameAssets::iter(), and the number of assets is available in GameAssets::COUNT.

The path needed to load an asset through the added EmbassetPlugin is retrieved using e.g. GameAssets::Icon.path():

fn some_asset_loading_system(asset_server: &AssetServer) {
  let icon : Handle<Image> = asset_server.load(GameAssets::Icon.path());
}

Using build.rs, no identifying enum

use bevy::{prelude::*, asset::AssetPlugin};
use bevy_embasset::AddEmbassetPlugin;

```rust
use bevy::{prelude::*, asset::AssetPlugin};
use bevy_embasset::EmbassetPlugin;

fn main() {
    App::new().add_plugins_with(DefaultPlugins, |group| {
        group.add_before::<AssetPlugin, _>(EmbassetPlugin::new(add_embasset_assets))
    });
}

Generate the add_embasset_assets function from a build script (build.rs):

use std::{env, path::Path};

fn main() {
    // Do this to include all files in the asset folder:
    bevy_embasset::include_all_assets(
        &Path::new(&env::var("CARGO_MANIFEST_DIR").unwrap()).join("assets"),
    );
}

and included it in the source:

include!(concat!(env!("OUT_DIR"), "/add_embasset_assets.rs"));

For the build script, the feature build needs to be enabled in Cargo.toml:

[build-dependencies]
bevy-embasset = { version = "*", features = ["build"] }

Bevy Compatibility

bevy-embasset	Bevy
main	0.6

Macros

asset_ids

Generates an enum for easy identification of assets - though only usable with the standard bevy AssetIo.

assets

Generates an enum for asset identification, as well as a struct implementing AssetIo.

Structs

AssetIoAlternative

Defines another AssetServer that may be used for loading assets by prepending the asset path with a custom string.

EmbassetIo

Custom AssetServer, that can load assets embedded into the binary, or use other servers for handling the load.

EmbassetPlugin

Bevy plugin that will insert EmbassetIo instead of the default AssetServer added by the AssetPlugin.

Traits

AddEmbassetPlugin

Trait for easy replacement of the default AssetServer.

EnumCount

A trait for capturing the number of variants in Enum. This trait can be autoderived by strum_macros.

IntoEnumIterator

This trait designates that an Enum can be iterated over. It can be auto generated using strum_macros on your behalf.

Derive Macros

EnumCount

Add a constant usize equal to the number of variants.