SuperAPI AI 工具集

bevy-asset-scenes

编程与开发

查看项目

更新于 10-16 10:37

技能介绍

用途

当游戏内容来自磁盘文件,或需要用场景描述来生成实体时,可使用本技能。AssetServer 负责加载文件;bsn! 宏用于描述一个 Scene,再由 spawn_scene 或 queue_spawn_scene 将其转换为实体。

主要能力

资源加载(Assets)

  • AssetServer 是从磁盘加载资源的资源(Resource)。AssetServer::load 返回一个 Handle,并且在强句柄仍然存在时不会重新加载。
  • 已加载的数据存放在 Assets<T> 中。
  • AssetServer::is_loaded_with_dependencies 在资源及其依赖项都就绪时返回 true。LoadState 是相关页面中命名的状态类型。

句柄(Handles)

  • 强句柄采用引用计数。丢弃最后一个强句柄会移除该资源。弱句柄不会保持资源存活。
  • Assets::add 插入一个程序化资源,且不会去重。

热重载(Hot reload)

  • file_watcher Cargo 特性,以及 AssetPlugin 的 watch_for_changes_override 字段,是资源索引页中命名的开关。

场景(Scenes)

  • bevy::scene 描述一个 Scene(实体、组件、子级、资源),使用 bsn! 宏构建。
  • World::spawn_scene 与 Commands::spawn_scene 立即生成,若资源依赖未加载则报错。
  • World::queue_spawn_scene 与 Commands::queue_spawn_scene 会等待,然后在 Update 与 PostUpdate 之间的 SpawnScene 调度中生成。
  • 场景中的层级:在 bsn! 内使用 Children [ ... ]。用 -- 分隔同级实体。#Name 在该宏作用域内赋予一个 Name。

使用方式

资源选择对照

需求 做法
加载文件 AssetServer::load 返回一个 Handle
等待就绪 在状态切换前使用 is_loaded_with_dependencies
立即生成场景 仅在依赖加载完成后使用 spawn_scene
就绪后生成 使用 queue_spawn_scene(SpawnScene 位于 Update 与 PostUpdate 之间)
场景中的子级 在 bsn! 内使用 Children
更改单个实体的网格 替换存储该句柄的组件上的 Handle

磁盘上的 .bsn 文件仍领先于已发布的场景 API。请使用 bsn! 编写场景。通过销毁其根实体来释放上一个关卡,然后排队下一个场景。一旦自定义 AssetLoader 类型存在,就用 App::register_asset_loader 注册它。

依赖配置

[dependencies]
bevy = { version = "0.20", features = ["file_watcher"] }

代码示例

#[derive(Resource)]
struct PropMesh(Handle<Mesh>);

fn begin_load(mut commands: Commands, assets: Res<AssetServer>) {
    let handle: Handle<Mesh> = assets.load("models/crate.glb#Mesh0/Primitive0");
    commands.insert_resource(PropMesh(handle));
}

fn mesh_is_ready(assets: Res<AssetServer>, mesh: Option<Res<PropMesh>>) -> bool {
    match mesh {
        Some(mesh) => assets.is_loaded_with_dependencies(&mesh.0),
        None => false,
    }
}

fn store_generated_material(
    mut materials: ResMut<Assets<StandardMaterial>>,
    mut commands: Commands,
) {
    let handle = materials.add(StandardMaterial {
        base_color: Color::srgb(0.8, 0.8, 0.82),
        ..default()
    });
    commands.insert_resource(GeneratedMaterial(handle));
}

#[derive(Resource)]
struct GeneratedMaterial(Handle<StandardMaterial>);
#[derive(Component, Default, Clone)]
struct CrateProp;

#[derive(Component, Default, Clone)]
struct Lid;

#[derive(Component, Default, Clone)]
struct LevelRoot;

fn spawn_crate(mut commands: Commands) {
    commands.spawn_scene(bsn! {
        #SupplyCrate
        CrateProp
        Children [
            Lid
        ]
    });
}

fn queue_level(mut commands: Commands) {
    commands.queue_spawn_scene(bsn! {
        :"levels/yard.bsn"
        LevelRoot
    });
}

fn replace_level(mut commands: Commands, roots: Query<Entity, With<LevelRoot>>) {
    for entity in &roots {
        commands.entity(entity).despawn();
    }
    commands.queue_spawn_scene(bsn! {
        LevelRoot
    });
}

适用场景

  • 内容来自磁盘文件,需要通过 AssetServer 加载。
  • 需要等待资源句柄及其依赖就绪后再进行状态切换。
  • 需要用 bsn! 描述场景并生成实体。
  • 需要替换关卡根实体(LevelRoot):先销毁旧根,再排队新场景。

限制与注意事项

  • 目标版本为 Bevy 0.20+。
  • 不要在文档 URL 中固定 /0.20.0/,链接应保持在 latest。
  • 不要从两个无序系统中可变查询同一组件;除非用 .chain() 排序,否则调度会并行运行系统。
  • 不要在本技能中虚构物理、导航、网络或 XR crate;本技能只命名有文档记录的 Bevy crate 与模块。
  • 不要使用其他引擎的打包场景或资源加载器类型;就绪判断是 is_loaded_with_dependencies,生成是 spawn_scene 或 queue_spawn_scene。
  • 不要使用本文件未打开的场景格式,也不要使用第三方场景 crate;Bevy 代码保持惯用 ECS 并仅使用有文档记录的 Bevy API。
  • 关于自定义加载器正文的编写,本技能未提供。

官方文档

  • Assets:https://bevy.org/assets/ ,官方资源目录。AssetServer、Handle 与 Assets<T> 是加载路径;Scene、bsn!、spawn_scene、queue_spawn_scene 与 SpawnScene 是生成路径。
  • Examples:https://github.com/bevyengine/bevy/tree/latest/examples#examples ,latest 分支上的示例树。

相关技能

前置:bevy-master(状态归属)、bevy-project-foundations(Cargo 特性,包括资源监视标志)、bevy-state-machines(资源页面指向应用状态用于加载门控)。 互补:bevy-audio-systems(通过 AssetServer 加载的音频片段)、bevy-save-load(玩家存档,与场景生成分离)。 下游/消费者:bevy-camera-systems(场景可能生成的相机实体)。 主技能:bevy-master(Bevy 路由)。