NEOLearn

Loading assets

Load files with AssetServer, refer to parts of a file with labels, check load states, load whole folders and pass settings to a loader.

Updated October 20, 2026

On this page

You load an asset by asking the AssetServer resource for it by path. load returns a Handle<T> at once and reads the file in the background, so a system never waits for the disk.

Load a file#

src/main.rs
use neo::prelude::*;

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    let image: Handle<Image> = asset_server.load("textures/crate.png");
    commands.spawn(Sprite::from_image(image));
}
RuleWhat it means
Paths are relative"textures/crate.png" is read from the asset folder, assets/ next to the game by default. Change it with AssetPlugin { file_path, .. }.
The type picks the loaderThe handle's type and the file extension decide which loader runs. Loading the same file as two types runs two loaders.
One load per pathLoading a path that is already loaded or loading returns a handle to the same asset; the file isn't read again.
Paths stay in approved foldersBy default, a path outside the asset folder or a registered source fails (AssetPlugin::unapproved_path_mode, UnapprovedPathMode::Forbid).

Labels: parts of a file#

Some files hold many assets. A glTF file has scenes, meshes, materials and animations; each is a labelled sub-asset, written after #:

Rust
// the first scene in the file
let scene = asset_server.load(GltfAssetLabel::Scene(0).from_asset("models/helmet.gltf"));
// the same, written as a string
let scene: Handle<WorldAsset> = asset_server.load("models/helmet.gltf#Scene0");
// one primitive of one mesh
let mesh: Handle<Mesh> = asset_server.load(
    GltfAssetLabel::Primitive { mesh: 0, primitive: 0 }.from_asset("models/cube.gltf"),
);

A misspelt label isn't an error at load time; the handle simply never loads. GltfAssetLabel builds the labels for you. See glTF.

Check whether it has loaded#

An asset isn't usable until it has loaded. Either look it up and skip it while it's missing (see Using assets), or ask the server:

Rust
fn check(asset_server: Res<AssetServer>, level: Res<LevelHandle>) {
    if asset_server.is_loaded_with_dependencies(&level.0) {
        info!("level ready");
    }
    if let Some(LoadState::Failed(err)) = asset_server.get_load_state(&level.0) {
        error!("level failed to load: {err}");
    }
}
MethodReturns
get_load_state(id)Option<LoadState>: NotLoaded, Loading, Loaded or Failed(error). None if the server doesn't know the asset.
is_loaded(id)true once the asset itself has loaded.
is_loaded_with_direct_dependencies(id)true once it and the assets it refers to directly have loaded.
is_loaded_with_dependencies(id)true once its whole dependency tree has loaded. A glTF scene, for example, depends on its meshes and textures.
get_dependency_load_state(id), get_recursive_dependency_load_state(id)The DependencyLoadState and RecursiveDependencyLoadState on their own.

To wait for many assets, keep their handles and check them all, or listen for AssetEvent::LoadedWithDependencies.

Example: cargo run --example multi_asset_sync.

Load a folder#

Rust
use neo::asset::LoadedFolder;

let folder: Handle<LoadedFolder> = asset_server.load_folder("textures/tiles");

The LoadedFolder asset holds a handle to every file in the folder, and finishes loading when they all have. Keep the folder handle, or the files are unloaded again.

Loader settings#

Many loaders take settings, such as an image's sampler or which parts of a glTF to keep. Pass them in code with load_builder:

Rust
use neo::image::{ImageLoaderSettings, ImageSampler};

let pixel_art: Handle<Image> = asset_server
    .load_builder()
    .with_settings(|settings: &mut ImageLoaderSettings| {
        settings.sampler = ImageSampler::nearest();
    })
    .load("sprites/hero.png");

Settings can also live in a .meta file next to the asset (hero.png.meta), written in RON:

assets/sprites/hero.png.meta
(
    meta_format_version: "1.0",
    asset: Load(
        loader: "neo_image::image_loader::ImageLoader",
        settings: (
            format: FromExtension,
            is_srgb: true,
            sampler: Descriptor (ImageSamplerDescriptor(
                address_mode_u: ClampToEdge,
                address_mode_v: ClampToEdge,
                address_mode_w: ClampToEdge,
                mag_filter: Nearest,
                min_filter: Nearest,
                mipmap_filter: Nearest,
                lod_min_clamp: 0,
                lod_max_clamp: 32.0,
                compare: None,
                anisotropy_clamp: 1,
                border_color: None,
                label: None,
            )),
            asset_usage: RenderAssetUsages("RENDER_WORLD | MAIN_WORLD"),
        ),
    ),
)

AssetPlugin::meta_check decides whether the server looks for .meta files: AssetMetaCheck::Always (the default), Paths(set) or Never.

Example: cargo run --example asset_settings.

Keep data on the CPU#

Meshes and images are uploaded to the GPU. Their RenderAssetUsages setting decides where the data is kept: RENDER_WORLD (on the GPU, needed to draw it), MAIN_WORLD (in Assets<T>, needed to read or change it in a system), or both. If you change a loaded mesh's vertices at runtime, load it with MAIN_WORLD kept:

Rust
use neo::{asset::RenderAssetUsages, gltf::GltfLoaderSettings};

let mesh: Handle<Mesh> = asset_server
    .load_builder()
    .with_settings(|s: &mut GltfLoaderSettings| s.load_meshes = RenderAssetUsages::all())
    .load(GltfAssetLabel::Primitive { mesh: 0, primitive: 0 }.from_asset("models/cube.gltf"));

Example: cargo run --example alter_mesh.

Examples#

Run them from the engine core's workspace (the folder of the engine source that holds the neo crate's Cargo.toml):

ExampleWhat it shows
asset_loadingLoading files, labels and folders, and adding assets directly.
asset_settingsLoader settings from code and from .meta files.
multi_asset_syncWaiting for several assets before carrying on.
repeated_textureA texture that repeats instead of clamping at its edges.

See Assets examples for the full list.

Next steps#