Hot reloading
Reload assets while the game runs, either automatically when their files change (the file_watcher feature) or by hand with AssetServer::reload.
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:
[dependencies]
neo = { workspace = true, features = ["file_watcher"] }With the feature on, the default asset source watches its folder. Nothing else is needed:
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).
| Feature | What it watches |
|---|---|
file_watcher | Asset folders on the file system. Also part of the dev collection. |
embedded_watcher | Embedded 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:
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:
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.