Asset sources
Where the asset server reads bytes from - the default folder, extra named sources, assets embedded in the binary, custom readers - and how NEO games find their content.
On this page
An asset source is a place the asset server reads bytes from. Every app has a default source, the assets/ folder; you can register more, each with its own name, and choose one in a path with name://.
| Path | Read from |
|---|---|
textures/crate.png | The default source. |
mods://textures/crate.png | The source registered as mods. |
embedded://my_crate/icons/logo.png | Bytes compiled into the game. |
Register an extra source#
Register sources before adding DefaultPlugins, since the asset plugin reads them when it starts:
use neo::{
asset::{
io::{AssetSourceBuilder, AssetSourceId},
AssetPath,
},
prelude::*,
};
use std::path::Path;
fn main() {
App::new()
.register_asset_source(
"mods",
AssetSourceBuilder::platform_default("mods", None),
)
.add_plugins(DefaultPlugins)
.add_systems(Startup, setup)
.run();
}
fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
commands.spawn(Camera2d);
let path = AssetPath::from_path(Path::new("banner.png")).with_source(AssetSourceId::from("mods"));
// the same as asset_server.load("mods://banner.png")
commands.spawn(Sprite::from_image(asset_server.load(path)));
}AssetSourceBuilder::platform_default(path, processed_path) reads a folder the way the default source does on each platform: the file system on the desktop, the package on Android, HTTP in a browser. The second argument is the folder of processed files, or None.
Example: cargo run --example extra_asset_source, from the engine core's workspace (the folder of the engine source that holds the neo crate's Cargo.toml).
Embed assets in the binary#
embedded_asset! compiles a file into the program and registers it with the embedded source. It suits shaders, icons and loading-screen art that must be there before anything else loads.
use neo::{asset::embedded_asset, prelude::*};
pub struct LoadingScreenPlugin;
impl Plugin for LoadingScreenPlugin {
fn build(&self, app: &mut App) {
// embeds src/ui/spinner.png, relative to this file
embedded_asset!(app, "spinner.png");
}
}The asset's path is the crate name, then the file's path under src/: embedded://my_game/ui/spinner.png. In the same module, load_embedded_asset!(&asset_server, "spinner.png") loads it with the same relative path. A second form, embedded_asset!(app, "prefix/to/omit", "file.png"), sets which part of the path to drop, for files outside a crate's src/ (such as examples).
With the embedded_watcher feature, editing the original file reloads the embedded asset during development.
Example: cargo run --example embedded_asset.
A custom reader#
To read assets from somewhere the engine doesn't know (a pack file, a database, a network service), implement AssetReader and register it as a source:
use neo::asset::io::{AssetSourceBuilder, AssetSourceId};
app.register_asset_source(
AssetSourceId::Default,
AssetSourceBuilder::new(|| Box::new(PackReader::open("content.pak"))),
);AssetReader has four async methods: read (an asset's bytes), read_meta (its .meta file), read_directory (for load_folder) and is_directory. Registering a reader as AssetSourceId::Default replaces the default source.
Example: cargo run --example custom_asset_reader.
Assets from the web#
The http and https features add sources for loading assets from web addresses (https://example.com/image.png). They aren't on in NEO's builds. Think before turning them on: with them, anything that can choose an asset path can make your game download from any server. Example: cargo run --example web_asset --features https.
How NEO games find their content#
A NEO game doesn't hard-code an asset folder. The platform layer, neo_device, finds the game's content root: the project's folders in development, the folder inside the package once it is packaged, the bundle on iOS, the APK on Android, or the web page's assets/ in a browser.
A project made from a template reads its content in layers:
| Layer | What it holds |
|---|---|
The project's own assets/ | Your imports and any file you want to replace. Searched first, and where writes go. |
| The template's shared content | The template's models, animation library and audio, used by reference. |
An asset path resolves to the first layer that has the file. neo_device::layers::register_default_source registers the layers as the default asset source before the asset plugin starts; the gameplay kit's add_default_plugins does this for you. Packaging copies the layers into one folder, so a shipped game has a single layer.
Some loaders open a file themselves instead of going through the asset server, such as a physics asset or an audio pack. They read through neo_device::files (read, read_to_string, exists, list), never std::fs, so the same code works on the desktop, consoles and the web. In a browser those files must be preloaded; list them in the game's web-preload. See Web builds.