bevyengine/bevy

bevy_asset

Asset loading, hot reloading, and the offline asset processor. The pluggable I/O layer used by every other "loadable thing" — meshes, images, glTF scenes, audio, fonts, shaders.

Purpose

bevy_asset provides:

Asset trait + Handle<T> for typed, reference-counted asset references.
AssetServer for asynchronous loading.
Assets<T> resource — typed storage of loaded assets.
AssetLoader trait — pluggable per-format readers (PNG, glTF, WAV, …).
Asset sources and readers — pluggable backends (filesystem, embedded, HTTP, custom).
Asset processing — an offline pipeline that converts source assets into baked, runtime-ready forms (compressed textures, processed meshes).
Hot reload via filesystem watching when the file_watcher feature is on.

Directory layout

crates/bevy_asset/src/
├── lib.rs                # Asset trait, AssetPlugin
├── handle.rs             # Handle<T>, StrongHandle, AssetId
├── server/               # AssetServer + load tasks
├── loader.rs             # AssetLoader trait
├── saver.rs              # AssetSaver trait
├── path/                 # AssetPath + parsing
├── id.rs                 # AssetId types
├── meta.rs               # Per-asset .meta metadata files
├── processor/            # Offline asset processor
├── transformer.rs        # Asset transformation pipeline
├── reflect.rs            # Reflection bridge
├── io/                   # Pluggable AssetReader / AssetWriter
│   ├── file/             # Filesystem backend
│   ├── embedded/         # Compiled-in bytes
│   ├── memory/           # In-memory backend
│   ├── android/, wasm/   # Platform-specific backends
│   └── source.rs         # AssetSource (named backends)
├── direct_access_ext.rs
└── …

Key abstractions

Type	File	Description
`Asset`	`crates/bevy_asset/src/lib.rs`	Trait. Marks a type as loadable.
`Handle<T>`	`crates/bevy_asset/src/handle.rs`	Reference-counted handle to an asset. Cheap to clone.
`AssetId<T>`	`crates/bevy_asset/src/id.rs`	The id without the strong reference.
`Assets<T>`	`crates/bevy_asset/src/lib.rs`	`Resource<T>` storing all loaded assets of type `T`.
`AssetServer`	`crates/bevy_asset/src/server/mod.rs`	The resource that loads, watches, and tracks assets.
`AssetLoader`	`crates/bevy_asset/src/loader.rs`	Trait: `bytes → Asset`.
`AssetSaver` / `AssetTransformer`	`crates/bevy_asset/src/{saver.rs,transformer.rs}`	Used by the asset processor.
`AssetReader` / `AssetWriter`	`crates/bevy_asset/src/io/mod.rs`	Pluggable I/O backends.
`AssetSource`	`crates/bevy_asset/src/io/source.rs`	A named bundle of readers/writers.
`AssetPath`	`crates/bevy_asset/src/path/mod.rs`	Parsed `source://path/to/file.ext#label`.

How it works

Loading

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

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

The handle is returned synchronously; the asset is filled in later. Systems wait by reading AssetEvents from the Events<AssetEvent<T>> resource or by checking assets.get(&handle) for Some.

An AssetSource is a named pair of AssetReader + optional AssetWriter. The default source is "file://" rooted at the runtime asset directory. Custom sources let you load from embedded bytes, in-memory data, or HTTP. Plugins register new sources via App::register_asset_source.

Processor mode

When the asset_processor feature is on and AssetPlugin::Processed is selected, assets go through an offline transformation step before the runtime sees them. A typical processor recipe:

Read source PNG.
Compress to BCn/ASTC.
Compute mipmaps.
Write .png.meta + processed binary to the imported-assets directory.

The runtime then loads the processed form. The processor is in crates/bevy_asset/src/processor/.

Hot reload

With file_watcher, the asset server watches the asset directories and re-emits AssetEvent::Modified when a file changes. Loaders rerun to produce updated assets and Assets<T> swaps the value behind the existing handle. Useful for materials, shaders, scenes during development.

Integration points

Depends on: bevy_app, bevy_ecs, bevy_reflect, bevy_tasks, bevy_utils, serde, notify (under file_watcher).
Depended on by: Every "loadable" subsystem — bevy_image, bevy_mesh, bevy_gltf, bevy_audio, bevy_text, bevy_shader, bevy_scene, bevy_world_serialization.

Entry points for modification

New asset format: implement AssetLoader and register with app.register_asset_loader(MyLoader).
New asset source: implement AssetReader and register with app.register_asset_source("my_source", AssetSource::build().with_reader(MyReader::new)).
New processor recipe: implement AssetSaver and AssetTransformer. Wire up via AssetProcessor::register_processor.
Custom AssetId allocation: unusual — id.rs is the place to look.