用途
当游戏内容来自磁盘文件,或需要用场景描述来生成实体时,可使用本技能。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 路由)。