NEOLearn

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.

Updated October 20, 2026

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://.

PathRead from
textures/crate.pngThe default source.
mods://textures/crate.pngThe source registered as mods.
embedded://my_crate/icons/logo.pngBytes compiled into the game.

Register an extra source#

Register sources before adding DefaultPlugins, since the asset plugin reads them when it starts:

src/main.rs
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.

src/ui/mod.rs
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:

Rust
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:

LayerWhat 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 contentThe 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.

Next steps#