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.
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#
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));
}| Rule | What 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 loader | The handle's type and the file extension decide which loader runs. Loading the same file as two types runs two loaders. |
| One load per path | Loading 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 folders | By 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 #:
// 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:
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}");
}
}| Method | Returns |
|---|---|
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#
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:
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:
(
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:
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):
| Example | What it shows |
|---|---|
asset_loading | Loading files, labels and folders, and adding assets directly. |
asset_settings | Loader settings from code and from .meta files. |
multi_asset_sync | Waiting for several assets before carrying on. |
repeated_texture | A texture that repeats instead of clamping at its edges. |
See Assets examples for the full list.