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() は &Path ではなく AssetPath を返します。 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 です。 以前の EventReader ではなく、MessageReader<AssetEvent<T>> を使って反復処理してください。

関連項目

• 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。