Bevy Engine Asset Loading: From AssetServer to Hot-Reload in Practice

The Core Problem: Assets Not Ready When You Need Them

When you call asset_server.load("texture.png"), you get an AssetHandle immediately—but the actual image data loads asynchronously. Systems that assume immediate availability will display missing textures or crash. The solution is understanding Bevy’s AssetServer resource, which manages all asset loading, deduplication, and hot-reloading through AssetHandle references.

How AssetServer Works

The AssetServer is a built-in resource that loads external files and returns lightweight AssetHandle<T> keys. These handles are cheap to copy and allow multiple entities to share the same asset without memory duplication. When the same path is loaded twice, Bevy returns the existing handle rather than re-loading the file.

Minimal Working Example

Place an image file at assets/texture.png, then use this code:

use bevy::prelude::*;

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

fn setup(
    mut commands: Commands,
    asset_server: Res,
) {
    let handle: Handle = asset_server.load("texture.png");
    commands.spawn_bundle(SpriteBundle {
        texture: handle,
        ..default()
    });
}


Checking Load State and Reacting
Because loading is asynchronous, you may need to wait before using assets. Check completion with handle.is_loaded() or poll asset_server.get_load_state(&handle). For complex initialization, react to AssetEvent events:
fn wait_for_texture(
    handle: Res>,
    asset_server: Res,
) {
    if asset_server.get_load_state(&handle) == LoadState::Loaded {
        println!("Texture ready for use");
    }
}


Hot-Reloading for Rapid Iteration
During development, modifying an asset file on disk triggers automatic reload. The AssetServer emits AssetEvent::Modified events, allowing systems to update visuals without restarting. This works only in debug builds—release builds disable file watching for performance.

Common Pitfalls and How to Avoid Them

    
Assuming immediate load: Never use an asset immediately after calling load(). Add a loading screen or check LoadState::Loaded first.
    
Storing paths instead of handles: Keep AssetHandle references, not strings. Storing paths causes duplicate loads and breaks hot-reloading.
    
Missing AssetServer: The AssetServer is added automatically by DefaultPlugins. Custom plugin setups must include it explicitly.
    
Platform path issues: Use forward slashes ("assets/texture.png") for cross-platform compatibility. Windows-style backslashes may fail on Linux/macOS.


Verifying Your Setup
Run these checks in a new Bevy 0.10 project:

    
Create assets/texture.png and add a SpriteBundle using asset_server.load("texture.png"). Verify the sprite appears.
    
While running, modify the PNG file. The sprite should update automatically, confirming hot-reload.
    
Add a system that prints asset_server.get_load_state(&handle). Confirm it transitions from Loading to Loaded.
    
Check console output for AssetEvent::Modified entries when editing files.


Limitations to Consider
Large assets can cause frame drops during initial load. Pre-load critical assets at startup or show a loading indicator. Custom asset types require registration via AssetPlugin. The AssetServer API is stable in Bevy 0.10 but may evolve in future releases—always consult current documentation for version-specific behavior.