NEOLearn

Asset processing

Process assets ahead of time into the form the game loads, with processed mode, .meta files, loaders, transformers and savers. Needs the asset_processor feature.

Updated October 20, 2026

On this page

Asset processing converts source files into the files the game loads, before the game needs them: compressing textures, baking data, stripping what the game doesn't use. The processor reads assets/, applies the processor each asset's .meta file names, and writes the results to imported_assets/Default/. In processed mode the game loads only the results.

Turn it on#

Cargo.toml
[dependencies]
neo = { workspace = true, features = ["asset_processor", "file_watcher"] }
src/main.rs
use neo::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins.set(AssetPlugin {
            mode: AssetMode::Processed,
            ..default()
        }))
        .run();
}
AssetPlugin fieldWhat it does
modeAssetMode::Unprocessed (the default) loads source files. AssetMode::Processed loads processed files.
file_pathThe source folder. Default assets.
processed_file_pathWhere processed files go and are loaded from. Default imported_assets/Default.
use_asset_processor_overrideRuns the processor at start-up (Some(true)) or not (Some(false)), whatever the feature says.

With asset_processor on, the processor runs when the app starts and processes what changed since the last run. With file_watcher as well, a source file you save is processed again and the result hot-reloads.

Without asset_processor, processed mode assumes the processor has already run and only loads from imported_assets/.

How an asset is processed#

Each source asset gets a .meta file next to it. Its asset entry says what to do:

EntryMeaning
Load(loader, settings)Load as is, with these loader settings.
Process(processor, settings)Run this processor and load its output.
IgnoreDon't process or load the file.
assets/a.cool.ron.meta
(
    meta_format_version: "1.0",
    asset: Process(
        processor: "LoadTransformAndSave<CoolTextLoader, CoolTextTransformer, CoolTextSaver>",
        settings: (
            loader_settings: (),
            transformer_settings: (
                appended: "X",
            ),
            saver_settings: (),
        ),
    ),
)

A file without a .meta uses the default processor registered for its extension, if there is one.

Build a processor#

The usual processor is LoadTransformAndSave<Loader, Transformer, Saver>:

  1. the loader reads the source into an asset;
  2. an AssetTransformer changes the asset;
  3. an AssetSaver writes it in the format the game will load, and names the loader that reads it (type OutputLoader).
src/text_processing.rs
use neo::asset::processor::LoadTransformAndSave;

impl Plugin for TextPlugin {
    fn build(&self, app: &mut App) {
        app.init_asset::<CoolText>()
            .register_asset_loader(CoolTextLoader)
            .register_asset_processor::<LoadTransformAndSave<CoolTextLoader, CoolTextTransformer, CoolTextSaver>>(
                LoadTransformAndSave::new(CoolTextTransformer, CoolTextSaver),
            )
            .set_default_asset_processor::<LoadTransformAndSave<CoolTextLoader, CoolTextTransformer, CoolTextSaver>>("cool.ron");
    }
}

A transformer takes and returns a TransformedAsset:

Rust
use neo::asset::transformer::{AssetTransformer, TransformedAsset};

impl AssetTransformer for CoolTextTransformer {
    type AssetInput = CoolText;
    type AssetOutput = CoolText;
    type Settings = CoolTextTransformerSettings;
    type Error = std::convert::Infallible;

    async fn transform<'a>(
        &'a self,
        mut asset: TransformedAsset<CoolText>,
        settings: &'a Self::Settings,
    ) -> Result<TransformedAsset<CoolText>, Self::Error> {
        asset.text = format!("{}{}", asset.text, settings.appended);
        Ok(asset)
    }
}

The full loader, transformer and saver are in the example: cargo run --example asset_processing --features "file_watcher asset_processor", from the engine core's workspace (the folder of the engine source that holds the neo crate's Cargo.toml).

Compressing textures#

The compressed_image_saver feature adds an image processor that compresses textures and generates mipmaps (BCn for desktop GPUs). compressed_image_saver_universal writes a format that is transcoded to the GPU's format at load time. Neither is on in NEO's builds.

Example: cargo run --example compressed_image_saver --features "compressed_image_saver asset_processor jpeg".

Next steps#