NEOLearn

Hot reloading

Reload assets while the game runs, either automatically when their files change (the file_watcher feature) or by hand with AssetServer::reload.

Updated October 20, 2026

On this page

Hot reloading means changing an asset file while the game runs and seeing the change without restarting. The engine reloads the asset in place: every handle keeps pointing at it, and an AssetEvent::Modified message tells your systems it changed.

Turn on the file watcher#

Add the feature to the neo dependency of a development build:

Cargo.toml
[dependencies]
neo = { workspace = true, features = ["file_watcher"] }

With the feature on, the default asset source watches its folder. Nothing else is needed:

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

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, setup)
        .run();
}

fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
    commands.spawn(WorldAssetRoot(
        asset_server.load(GltfAssetLabel::Scene(0).from_asset("models/torus/torus.gltf")),
    ));
    commands.spawn((
        DirectionalLight::default(),
        Transform::from_xyz(4.0, 5.0, 4.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(2.0, 2.0, 6.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));
}

Save torus.gltf in another program and the model changes in the running game.

Example: cargo run --example hot_asset_reloading --features file_watcher, run from the engine core's workspace (the folder of the engine source that holds the neo crate's Cargo.toml).

FeatureWhat it watches
file_watcherAsset folders on the file system. Also part of the dev collection.
embedded_watcherEmbedded assets, by watching the source files they were embedded from. See Asset sources.

AssetPlugin::watch_for_changes_override turns watching off (Some(false)) in a build that has a watcher, or asks for it (Some(true)). It can't add a watcher that isn't compiled in. asset_server.watching_for_changes() says whether the server is watching.

Reload by hand#

AssetServer::reload reads a path again and replaces the asset, with or without a watcher:

Rust
fn reload_on_f5(keys: Res<ButtonInput<KeyCode>>, asset_server: Res<AssetServer>) {
    if keys.just_pressed(KeyCode::F5) {
        asset_server.reload("levels/arena.scn.ron");
    }
}

React to a reload#

A reloaded asset sends AssetEvent::Modified. Systems that copy data out of an asset should listen for it:

Rust
fn apply_tuning(
    mut events: MessageReader<AssetEvent<Tuning>>,
    tunings: Res<Assets<Tuning>>,
    mut speed: ResMut<PlayerSpeed>,
) {
    for event in events.read() {
        if let AssetEvent::Modified { id } | AssetEvent::Added { id } = event
            && let Some(tuning) = tunings.get(*id)
        {
            speed.0 = tuning.speed;
        }
    }
}

Components that hold a handle (meshes, materials, images, world assets) pick up the new data by themselves. A spawned glTF scene or world file is spawned again from the reloaded asset.

Next steps#