Bevy资源加载器

用最少样板代码加载状态

此Bevy插件减少了处理游戏资源的样板代码。该包提供了可派生的AssetCollection特质，并可以自动加载实现它的结构体。资源集合包含对游戏资源的引用，并在加载后作为资源提供给您的系统。

在大多数情况下，您希望在加载状态（例如加载界面）期间加载资源集合。在此状态下，所有资源都将被加载，并观察其加载进度。只有在资源集合可以使用完全加载的资源引用构建时，集合才会被插入到Bevy的ECS中作为资源。如果您不想使用加载状态，资源集合仍然可以生成更简洁的代码和更好的可维护性（请参阅"无加载状态的使用"部分）。

主分支和最新版本支持Bevy版本0.14（请参阅版本表）

加载状态

加载状态负责管理在可配置的Bevy状态（请参阅状态技巧手册）期间的加载过程。

如果您的LoadingState已设置，您可以从配置的"下一个状态"开始您的游戏逻辑，并在您的系统中使用资源集合。加载状态保证在下一个状态开始时，您的集合中的所有引用都已完全加载。

use bevy::prelude::*;
use bevy_asset_loader::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .init_state::<MyStates>()
        .add_loading_state(
            LoadingState::new(MyStates::AssetLoading)
                .continue_to_state(MyStates::Next)
                .load_collection::<AudioAssets>(),
        )
        .add_systems(OnEnter(MyStates::Next), start_background_audio)
        .run();
}

#[derive(AssetCollection, Resource)]
struct AudioAssets {
    #[asset(path = "audio/background.ogg")]
    background: Handle<AudioSource>,
}

/// This system runs in MyStates::Next. Thus, AudioAssets is available as a resource
/// and the contained handle is done loading.
fn start_background_audio(mut commands: Commands, audio_assets: Res<AudioAssets>) {
    commands.spawn(AudioBundle {
        source: audio_assets.background.clone(),
        settings: PlaybackSettings::LOOP,
    });
}

#[derive(Clone, Eq, PartialEq, Debug, Hash, Default, States)]
enum MyStates {
    #[default]
    AssetLoading,
    Next,
}

如果我们想向刚刚添加的加载状态添加额外的资源集合，我们可以在应用的任何位置使用configure_loading_state。例如，我们可以在添加加载状态后向App添加一个PlayerPlugin。该PlayerPlugin将包含所有"玩家"相关的事物，包括其精灵。

use bevy::prelude::*;
use bevy_asset_loader::prelude::*;

struct PlayerPlugin;

impl Plugin for PlayerPlugin {
    fn build(&self, app: &mut App) {
        app
            .configure_loading_state(
                LoadingStateConfig::new(MyStates::AssetLoading)
                    .load_collection::<PlayerAssets>(),
            );
    }
}

#[derive(AssetCollection, Resource)]
struct PlayerAssets {
    #[asset(path = "images/player.png")]
    sprite: Handle<Image>,
}

#[derive(Clone, Eq, PartialEq, Debug, Hash, Default, States)]
enum MyStates {
    #[default]
    AssetLoading,
    Next,
}

编译时与运行时（动态）资源

资产配置，例如文件路径或精灵表尺寸，可以在编译时（通过派生宏属性）或运行时（见"动态资产"）给出。后者允许将资产配置作为资产来管理。这意味着您可以在资产文件中保留一个资产文件及其属性的列表。使用动态资产的主要优点是实现代码和数据更清晰的分离，从而在处理资产时减少重新编译次数。它还使游戏更易于被希望贡献而不修改代码的人接触。

为AssetCollection提供的派生宏支持多个属性。它们配置了资产的加载方式。

编译时资产

前两个代码示例显示了具有所有配置在派生宏属性中的集合的加载状态。玩家精灵的路径被硬编码为"images/player.png"。更改它需要重新编译您的应用程序。

full_collection 示例展示了资产集合可以使用派生宏属性包含的所有不同类型的字段。

动态资产

动态资产通过派生宏属性 key 进行配置，不允许有 path 或 paths 属性

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct ImageAssets {
  #[asset(key = "player")]
  player: Handle<Image>,
  #[asset(key = "tree")]
  tree: Handle<Image>,
}

示例中 player 和 tree 这两个键应在加载状态之前在 DynamicAssets 资源中手动设置（见manual_dynamic_asset 示例），或作为动态资产文件的一部分（见 dynamic_asset.rs）。上述集合的动态资产文件可能看起来像这样

({
    "player": File (
        path: "images/player.png",
    ),
    "tree": File (
        path: "images/tree.png",
    ),
})

使用类似于 File 的动态资产和加载 ron 文件需要启用 standard_dynamic_assets 功能。

默认情况下，文件扩展名为 LoadingState::set_standard_dynamic_asset_collection_file_endings。

示例 full_dynamic_collection 展示了动态资产支持的所有字段类型。请注意，将动态资产文件添加到加载状态需要 AssetServer 资源可用。在大多数情况下，这意味着您应该在配置加载状态之前添加 DefaultPlugins。

自定义动态资产

您可以定义自己的类型以作为动态资产加载。请参阅custom_dynamic_assets.rs 示例中的代码。

支持的资产字段

最简单的字段类型为 Handle<T>，并从单个文件加载。一个例子可能是音频源，但任何已注册 Bevy 的资产加载器类型的资产都可以这样使用。

字段应仅设置 path 属性。

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(path = "my-background.ogg")]
    background: Handle<AudioSource>,
}

同一集合的动态版本看起来像这样

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(key = "background")]
    background: Handle<AudioSource>,
}

({
    "background": File (
        path: "my-background.ogg",
    ),
})

以下部分将描述更多类型的资产字段，您可以通过资产集合加载它们。

纹理图集

如果您启用 2d 功能，可以在 AssetCollection 中创建纹理图集布局。有关完整示例，请参阅 atlas_from_grid.rs。

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(texture_atlas_layout(tile_size_x = 64, tile_size_y = 64, columns = 8, rows = 1, padding_x = 12, padding_y = 12, offset_x = 6, offset_y = 6))]
    layout: Handle<TextureAtlasLayout>,
    #[asset(path = "images/sprite_sheet.png")]
    sprite: Handle<Image>,
}

作为一个动态资产，这个例子变成了

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(key = "player.layout")]
    layout: Handle<TextureAtlasLayout>,
    #[asset(key = "player.image")]
    sprite: Handle<Image>,
}

({
    "player.image": File (
        path: "images/sprite_sheet.png",
    ),
    "player.layout": TextureAtlasLayout (
        tile_size_x: 100,
        tile_size_y: 64,
        columns: 8,
        rows: 1,
        padding_x: 12,
        padding_y: 12,
        offset_x: 6,
        offset_y: 6,
    ),
})

四个填充 & 偏移字段/属性是可选的，默认值为 0。

具有采样器配置的图像

资产集合支持通过派生属性配置图像资产的采样器。

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct ImageAssets {
    #[asset(path = "images/pixel_tree.png")]
    #[asset(image(sampler = linear))]
    tree_linear: Handle<Image>,

    #[asset(path = "images/pixel_tree.png")]
    #[asset(image(sampler = nearest))]
    tree_nearest: Handle<Image>,
}

相应的动态资产将是

({
    "tree_nearest": Image (
        path: "images/tree.png",
        sampler: Nearest
    ),
    "tree_linear": Image (
        path: "images/tree.png",
        sampler: Linear
    ),
})

标准材质

如果您启用功能 3d，则可以直接加载标准材质。请查看standard_material.rs 获取完整示例。

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(standard_material)]
    #[asset(path = "images/player.png")]
    player: Handle<StandardMaterial>,
}

这也可以作为动态资产支持

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(key = "image.player")]
    player: Handle<StandardMaterial>,
}

({
    "image.player": StandardMaterial (
        path: "images/player.png",
    ),
})

集合

文件夹

此资产字段类型不支持在Web构建中。有关在Web兼容方式中加载文件集合的说明，请参阅文件。

您可以将文件夹中的所有文件作为未类型化句柄的向量加载。此字段需要额外的派生宏属性 collection

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(path = "images", collection)]
    folder: Vec<UntypedHandle>,
}

就像Bevy的 load_folder 一样，此功能也将递归加载子文件夹。

如果文件夹中的所有资产都具有相同的（已知）类型，则可以通过将 typed 设置在 collection 属性中来将文件夹作为 Vec<Handle<T>> 加载。不要忘记调整结构字段类型

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(path = "images", collection(typed))]
    folder: Vec<Handle<Image>>,
}

文件夹也支持作为动态资产。路径属性由 key 属性替换

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(key = "my.images", collection(typed))]
    images: Vec<Handle<Image>>,
}

({
    "my.images": Folder (
        path: "images",
    ),
})

Web构建不支持加载文件夹。如果需要与Wasm兼容，请从路径列表中加载句柄（请参阅下一节）。

路径列表

如果要将相同类型的资产文件列表加载到 Handle<T> 的向量中，可以在属性中列出它们的路径

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(paths("images/player.png", "images/tree.png"), collection(typed))]
    files_typed: Vec<Handle<Image>>,
}

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(paths("images/player.png", "sound/background.ogg"), collection)]
    files_untyped: Vec<UntypedHandle>,
}

use bevy::prelude::*;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(key = "files_untyped", collection)]
    files_untyped: Vec<UntypedHandle>,
    #[asset(key = "files_typed", collection(typed))]
    files_typed: Vec<Handle<Image>>,
}

({
    "files_untyped": Files (
        paths: ["images/tree.png", "images/player.png"],
    ),
    "files_typed": Files (
        paths: ["images/tree.png", "images/player.png"],
    ),
})

use bevy::prelude::*;
use bevy::utils::HashMap;
use bevy_asset_loader::asset_collection::AssetCollection;

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(path = "images", collection(mapped))]
    folder: HashMap<String, UntypedHandle>,
    #[asset(paths("images/player.png", "images/tree.png"), collection(typed, mapped))]
    files_typed: HashMap<String, Handle<Image>>,
    #[asset(key = "files_untyped", collection(mapped))]
    dynamic_files_untyped: HashMap<String, UntypedHandle>,
    #[asset(key = "files_typed", collection(typed, mapped))]
    dynamic_files_typed: HashMap<String, Handle<Image>>,
}

use bevy::prelude::*;
use bevy_asset_loader::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .init_collection::<MyAssets>()
        .run();
}

#[derive(AssetCollection, Resource)]
struct MyAssets {
    #[asset(texture_atlas_layout(tile_size_x = 64, tile_size_y = 64, columns = 8, rows = 1, padding_x = 12, padding_y = 12, offset_x = 6, offset_y = 6))]
    layout: Handle<TextureAtlasLayout>,
    #[asset(path = "images/sprite_sheet.png")]
    sprite: Handle<Image>,
}