bevyengine/bevy

Assets

How files become Bevy types: the asset server, loaders, sources, hot reload, and the offline processor.

The big picture

graph LR
    Disk[(disk)] -->|AssetReader| Source[AssetSource]
    Source -->|bytes| Loader[AssetLoader]
    Loader -->|asset value| Assets["Assets<T>"]
    Server[AssetServer] -->|load| Source
    User -->|"load(path)"| Server
    User -->|read| Assets
    Watch[file watcher] -->|change| Source
    Source -->|AssetEvent::Modified| Assets

The pieces:

AssetServer — the resource that holds the load queue and reference counts.
AssetReader / AssetWriter — pluggable I/O backends (filesystem, embedded, network).
AssetSource — a named pair of reader/writer. The default source is "file://" rooted at the runtime asset directory.
AssetLoader — bytes → Asset. One per format.
Assets<T> — typed storage of every loaded asset of type T.
Handle<T> — reference-counted handle to an asset, either weak or strong.
Hot reload — the file watcher emits AssetEvent::Modified; loaders re-run.
Asset processor — optional offline pipeline that bakes source assets into runtime form.

The implementation lives in bevy_asset.

Load flow

sequenceDiagram
    participant U as user system
    participant S as AssetServer
    participant T as IoTaskPool
    participant R as AssetReader
    participant L as AssetLoader
    participant A as Assets<T>

    U->>S: load("models/foo.gltf")
    S-->>U: Handle<Scene> (pending)
    S->>T: spawn task
    T->>R: read bytes
    R-->>T: bytes
    T->>L: from_reader
    L-->>T: Asset value
    T->>A: insert(handle, asset)
    A-->>U: AssetEvent::Added

load is non-blocking. The handle is returned synchronously; the asset is filled in later. Systems can poll Assets::get, listen to AssetEvent, or use AssetServer::load_state(handle).

Pluggable sources

A source is registered by name. The default "file://" source loads from disk. Other built-in options:

Embedded — embedded:// source. Bundles bytes into the binary at compile time via the embedded_asset! macro. Used heavily for shaders.
Memory — memory://. Programmatic in-memory bytes.
Custom — register your own AssetSource (HTTP, WebSocket, blob storage, …) via App::register_asset_source.

Each loader can pick where it loads dependencies from by parsing the source name in the path.

Per-format loaders

The standard loaders, each gated by a feature flag:

Format	Loader crate	Feature
PNG, JPEG, BMP, GIF, TGA, TIFF, WebP, EXR, HDR	`bevy_image`	`png`, `jpeg`, `bmp`, `gif`, `tga`, `tiff`, `webp`, `exr`, `hdr`
KTX2 + Basis Universal	`bevy_image`	`ktx2`, `basis-universal`
WAV, OGG, MP3, FLAC, AAC	`bevy_audio`	`wav`, `vorbis`, `mp3`, `flac`, `aac`
TTF, OTF	`bevy_text`	`default_font`
WGSL, SPIR-V, GLSL	`bevy_shader`	always
glTF 2.0	`bevy_gltf`	`bevy_gltf`
`.scn.ron`, `.bsn`	`bevy_world_serialization`	`bevy_scene`

When the file_watcher feature is on, the asset server watches the asset directories with notify. File changes generate AssetEvent::Modified events which trigger loaders to rerun. The handle remains the same; the value behind it is replaced atomically.

This is why most Bevy systems read assets via Assets::get(&handle) instead of caching values: the system automatically picks up reloaded assets.

The asset processor

When AssetMode::Processed is selected (and the asset_processor feature is on), bevy_asset runs an offline transformation step:

graph LR
    SourceAsset[("source asset (foo.png)")] -->|read| Loader1[AssetLoader]
    Loader1 -->|asset| Transformer
    Transformer -->|transformed asset| Saver
    Saver -->|bytes| Imported["imported_assets/foo.png"]
    Imported -->|read at runtime| Loader2[AssetLoader]

Recipes are registered via AssetTransformer (transform a loaded asset) and AssetSaver (serialize the result). The processor watches the source directory, runs the recipe, and writes both the processed bytes and a .meta file to the imported-assets directory. At runtime the loader reads the imported form, skipping the source.

Used most often for:

Compressed textures (BCn / ASTC / ETC2 via Basis).
Mesh optimization (vertex cache reordering, optional meshlet pre-computation).
Shader pre-processing.

Cargo features

The crate-level rustdoc and reference/configuration detail the asset features. The most important:

file_watcher — hot reload.
embedded_watcher — hot reload for embedded:// sources during development.
asset_processor — offline transformation pipeline.
multi_threaded — parallel asset loading on the IO task pool.