NEOLearn

Custom assets and loaders

Define your own asset types with derive(Asset), load them from RON with the built-in loader, write an AssetLoader for your own file format, and give it settings.

Updated October 20, 2026

On this page

Any Rust type can be an asset. Derive Asset, register it, and it gets an Assets<T> store, handles and events like the engine's own types. To read it from a file you need a loader: the built-in RON loader for reflected types, or one you write.

Define an asset type#

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

#[derive(Asset, TypePath, Debug)]
pub struct EnemyStats {
    pub health: u32,
    pub speed: f32,
}

pub struct DataPlugin;

impl Plugin for DataPlugin {
    fn build(&self, app: &mut App) {
        app.init_asset::<EnemyStats>();
    }
}

Asset needs TypePath (or Reflect, which includes it). init_asset::<T>() adds the Assets<T> resource and the AssetEvent<T> messages.

Fields that hold handles to other assets make those assets dependencies: mark them with #[dependency], and is_loaded_with_dependencies and AssetEvent::LoadedWithDependencies wait for them too.

Rust
#[derive(Asset, TypePath)]
pub struct Level {
    pub name: String,
    #[dependency]
    pub music: Handle<AudioSource>,
}

Load reflected types from RON#

For data assets, the engine's RonLoader reads any type that derives Reflect and reflects Asset. You write no loader code:

src/main.rs
use neo::{
    asset::{common_loaders::ron::RonLoader, ReflectAsset},
    prelude::*,
};

#[derive(Asset, Reflect, Debug)]
#[reflect(Asset)]
struct Banner {
    text: String,
    color: Color,
}

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .init_asset_loader::<RonLoader>()
        .init_asset::<Banner>()
        .add_systems(Startup, setup)
        .run();
}

#[derive(Resource)]
struct BannerHandle(Handle<Banner>);

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    // the typed value is the file's "#Typed" sub-asset
    commands.insert_resource(BannerHandle(asset_server.load("data/banner.ron#Typed")));
}

The file is a map with one entry: the type's path, then its value. The full path (my_game::Banner) always works; the short name (Banner) works while it is unambiguous.

assets/data/banner.ron
{
    "my_game::Banner": (
        text: "Welcome!",
        color: Srgba((red: 1.0, green: 0.8, blue: 0.2, alpha: 1.0)),
    ),
}

The root asset of the file is a LoadedUntypedAsset; load #Typed to get your type. TypedRonLoader::<T>::new(vec!["stats.ron"]) loads one type from its own extension without the type-path wrapper, for types that implement serde's Deserialize.

Example: cargo run --example custom_asset.

Write an asset loader#

For your own file format, implement AssetLoader. It reads bytes through a Reader and returns the asset:

src/stats_loader.rs
use neo::{
    asset::{io::Reader, AssetLoader, LoadContext},
    prelude::*,
    reflect::TypePath,
};
use serde::Deserialize;
use thiserror::Error;

#[derive(Asset, TypePath, Debug, Deserialize)]
pub struct EnemyStats {
    pub health: u32,
    pub speed: f32,
}

#[derive(Default, TypePath)]
pub struct EnemyStatsLoader;

#[derive(Debug, Error)]
pub enum EnemyStatsError {
    #[error("could not read the file: {0}")]
    Io(#[from] std::io::Error),
    #[error("could not parse RON: {0}")]
    Ron(#[from] ron::error::SpannedError),
}

impl AssetLoader for EnemyStatsLoader {
    type Asset = EnemyStats;
    type Settings = ();
    type Error = EnemyStatsError;

    async fn load(
        &self,
        reader: &mut dyn Reader,
        _settings: &(),
        _load_context: &mut LoadContext<'_>,
    ) -> Result<EnemyStats, Self::Error> {
        let mut bytes = Vec::new();
        reader.read_to_end(&mut bytes).await?;
        Ok(ron::de::from_bytes(&bytes)?)
    }

    fn extensions(&self) -> &[&str] {
        &["enemy"]
    }
}

Register both the asset and the loader:

Rust
app.init_asset::<EnemyStats>()
    .init_asset_loader::<EnemyStatsLoader>();
// or, for a loader that needs values: .register_asset_loader(EnemyStatsLoader)

Then asset_server.load::<EnemyStats>("enemies/goblin.enemy") uses it.

ItemWhat it is
type AssetThe asset the loader makes.
type SettingsSettings the loader takes, from load_builder().with_settings(...) or a .meta file. They must be Default, Serialize and Deserialize; use () for none.
type ErrorThe error a failed load reports. It shows in LoadState::Failed.
load(reader, settings, load_context)Reads the bytes and builds the asset. It runs on a background thread.
extensions()The file extensions it handles, without the dot. Several loaders can share one; the handle's type decides.

The load context#

LoadContext lets a loader reach other assets while it loads:

MethodWhat it does
load_context.load(path)Starts loading another asset and returns its handle. It becomes a dependency.
load_context.load_builder().load_value::<T>(path).awaitLoads another asset now and gives you its value, to fold into this one.
load_context.add_labeled_asset(label, value)Adds a sub-asset, loadable as path#label.
load_context.path()The path being loaded.

Example: cargo run --example custom_asset_loader.

Loader settings#

Rust
#[derive(Default, Serialize, Deserialize)]
pub struct TextSettings {
    pub uppercase: bool,
}

impl AssetLoader for TextLoader {
    type Asset = Text;
    type Settings = TextSettings;
    // ...
}

// at the call site
let title: Handle<Text> = asset_server
    .load_builder()
    .with_settings(|s: &mut TextSettings| s.uppercase = true)
    .load("ui/title.txt");

Save assets#

An AssetSaver writes an asset back out in a format a loader reads. Savers are what asset processing uses; you can also call them yourself. Examples: cargo run --example asset_saving, cargo run --example asset_saving_with_subassets.

Read bytes from somewhere else#

A loader turns bytes into an asset; an AssetReader decides where the bytes come from. To read from a custom place (a pack file, a database), write an AssetReader and register it as an asset source. See Asset sources. Example: cargo run --example custom_asset_reader.

Next steps#