bevy-assets

Bevy 0.19 — 资源

何时使用此技能

• 加载模型、纹理、音频文件或场景。
• 数据加载就绪后，从 Assets<T> 中读取已加载的数据。
• 响应加载进度（AssetEvent::Added / Modified）。
• 生成 glTF 场景、等待 WorldInstanceReady、读取名称/附加数据，或妥善管理实例的所有权和销毁。
• 在开发期间启用热重载。
• 编写自己的加载器 → 参见 bevy-custom-assets。

标准模式

use bevy::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins.set(AssetPlugin {
            // Hot-reload on file change — dev-only.
            watch_for_changes_override: Some(true),
            ..default()
        }))
        .init_resource::<MyHandles>()
        .add_systems(Startup, load_handles)
        .add_systems(Update, react_to_loads)
        .run();
}

#[derive(Resource, Default)]
struct MyHandles {
    hero: Handle<WorldAsset>,
    bricks: Handle<Image>,
}

fn load_handles(asset_server: Res<AssetServer>, mut handles: ResMut<MyHandles>) {
    // GLTF scenes are addressed by sub-asset label.
    handles.hero = asset_server.load("models/hero.glb#Scene0");
    handles.bricks = asset_server.load("textures/bricks.png");
}

fn react_to_loads(
    mut ev: MessageReader<AssetEvent<Image>>,
    images: Res<Assets<Image>>,
) {
    for event in ev.read() {
        if let AssetEvent::LoadedWithDependencies { id } = event {
            if let Some(img) = images.get(*id) {
                info!("image loaded: {}x{}", img.width(), img.height());
            }
        }
    }
}

资源路径

use bevy::asset::AssetPath;

// `LoadContext::path()` returns `AssetPath`, not `&Path`.
// Build paths explicitly when generating handles inside a custom loader:
let path = AssetPath::from("textures/bricks.png");
let path_with_label = AssetPath::from("models/hero.glb").with_label("Scene0");
let _ = path;
let _ = path_with_label;

资源就绪检查

use bevy::prelude::*;

# fn _check(
asset_server: Res<AssetServer>,
handles: Res<MyHandles>,
# ) {
use bevy::asset::LoadState;

if asset_server.load_state(&handles.hero) == LoadState::Loaded {
    // Safe to spawn WorldAssetRoot(handles.hero.clone()).
}
# }
# #[derive(Resource)] struct MyHandles { hero: Handle<WorldAsset> }

Bevy 0.19 注意事项

• LoadContext::path() 返回 AssetPath，而不是 &Path。原先调用 ctx.path().to_string_lossy() 的代码需要改用 ctx.path().path().to_string_lossy()，或直接使用 AssetPath API。
• SeekableReader 在 0.18 中新增。需要随机访问底层文件的加载器可以这样调用：if let Ok(s) = reader.seekable() { /* s: &mut dyn SeekableReader */ }。
• 在 0.19 中，每个自定义 Reader 都要实现 seekable()。 如果它也实现了 AsyncSeek，则返回 Ok(self)；否则返回 Err(ReaderNotSeekableError)。AsyncSeekForward 已移除。
• 在 0.19 中，高级加载使用构建器。 对于设置、守卫、无类型加载或批准覆盖，优先使用 AssetServer::load_builder()；多个专用的 load_* 变体已弃用。
• AssetPath::resolve 现在接收 &AssetPath。 如果子路径起始为文本，请使用 resolve_str/resolve_embed_str。
• AssetSourceBuilder::new(...) 取代了 AssetSource::build().with_reader(...)。现有的自定义资源源需要调整结构。
• 在 0.18 中，AssetSource 通道类型为 async_channel::Sender（此前为 crossbeam_channel）。请使用 send_blocking(...)。
• 在 0.18 中，Image::reinterpret_size(size) 返回 Result。
• 子资源标签。 path.glb#Scene0、path.glb#Mesh0/Primitive0 — 它们有各自独立的句柄，可以单独加载。若忘记标签，获取到的将是根资源，而不是指定名称的资源。
• 热重载仅用于开发。 不要在发布版本中设置 watch_for_changes_override: Some(true) — 它会轮询文件系统。
• asset_server.load(...) 是非阻塞的。 调用后立即查询 Assets<T>::get 会返回 None。请等待 AssetEvent::LoadedWithDependencies，或轮询 load_state(...)。
• AssetEvent<T> 是一种 Message，因此请使用 MessageReader<AssetEvent<T>> 迭代，而不是旧的 EventReader。

另请参阅

• glTF 场景 — GltfAssetLabel、WorldAssetRoot、 实例就绪状态/所有权、名称/附加数据、元数据代理和销毁。
• bevy-custom-assets — 编写 AssetLoader 和嵌套加载构建器。
• bevy-save-load — 持久稳定 ID 和保存架构； glTF 名称/实体 ID 并非持久化契约。
• bevy-migration-0-17-to-0-18 — LoadContext::path 和通道类型重命名。
• bevy-migration-0-18-to-0-19 — 加载构建器和必需的 Reader::seekable。