用途
当新的 Bevy 应用在 gameplay 系统出现之前,需要确定 crate、版本固定(pin)以及功能代码的存放位置时,加载本技能。下文中的文件夹名称只是布局习惯,不是引擎类型。
ECS 形态
- Crate: 使用
cargo new,并将bevy依赖固定为 0.20。 - 特性(Features):
default会拉入窗口、输入和渲染。仅当二进制应保持无头时,才关闭default-features。 - App 外壳:
App::new()、插件,然后在该App上添加系统和资源。 - 代码布局: 在普通 Rust 模块中按功能拆分。引擎不要求特定的目录树。
固定 crate 并保持开发构建可用。Bevy 默认的 debug profile 会以未优化方式编译依赖,因此 dev profile 提升依赖的 opt-level,同时游戏 crate 仍易于单步调试。
[package]
name = "game"
version = "0.1.0"
edition = "2021"
[dependencies]
bevy = "0.20"
[profile.dev]
opt-level = 1
[profile.dev.package."*"]
opt-level = 3
无头工具 crate 会去掉默认特性集,只添加该二进制实际调用的内容。
[dependencies]
bevy = { version = "0.20", default-features = false }
带窗口的游戏会接入 DefaultPlugins 和一个功能插件。GameConfig 是应用级状态,在第一个调度运行之前插入。
#[derive(Resource)]
struct GameConfig {
title: String,
}
fn boot(config: Res<GameConfig>) {
let _title = config.title.as_str();
}
pub struct GamePlugin;
impl Plugin for GamePlugin {
fn build(&self, app: &mut App) {
app.insert_resource(GameConfig {
title: "Game".to_string(),
})
.add_systems(Startup, boot);
}
}
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_plugins(GamePlugin)
.run();
}
第二个模块拥有一个功能。插件是边界。系统保留在声明其组件的模块中。
#[derive(Component)]
struct Player;
fn spawn_player(mut commands: Commands) {
commands.spawn(Player);
}
pub struct PlayerPlugin;
impl Plugin for PlayerPlugin {
fn build(&self, app: &mut App) {
app.add_systems(Startup, spawn_player);
}
}
布局选择
| 需求 | Bevy 惯用法 |
|---|---|
| 新建 crate | cargo new 加 bevy 依赖 |
| 窗口、输入、渲染 | bevy crate 上的 Cargo 特性与 profile |
| 功能拆分 | 自行选择的 Rust 模块 |
| 项目文件 | Cargo.toml 加 Rust 模块 |
范围
- 在
Cargo.toml中固定bevy = "0.20"。DefaultPlugins会引入该 crate 特性所启用的窗口、输入和音频后端。 - Workspace 成员和命名检查器属于普通 Cargo。本技能不会发明文件夹强制器。
专家知识增量
目标:Bevy 0.20+。
核心 ECS 类型:Component、Resource、Query、Commands、Startup、Update、Fixed / FixedMain(bevy::time)、.chain()、Plugin、DefaultPlugins、MinimalPlugins。消息和观察者是一个所有权槽位,其 API 见 bevy-events-messaging。除非用 .chain() 对冲突的系统排序,系统会并行运行。
谁拥有状态
| 部分 | 所有者 | 谁可以变更 | 调度 |
|---|---|---|---|
| 单个实体上的数据 | Component |
一个系统通过 Query |
Update 或 FixedMain |
| 整个应用的一个值 | Resource |
一个系统 | Startup 插入,然后读取它的调度 |
| 生成(Spawn) | Commands |
执行生成的系统 | 初始世界用 Startup;运行时生成用之后的调度 |
| 不能产生竞态的排序 | .chain() |
仅被链式连接的系统 | 同一调度 |
| 插件边界 | Plugin |
build 注册系统和资源 |
在应用运行之前 |
借用规则:两个系统若都可变查询同一组件,必须排序(.chain())或拆分,使只有一个写入。无关的系统保持并行。这是 ECS 页面的规则,不是对 system-set API 的猜测。
决策
| 如果需要 | 这样做 | 不要 |
|---|---|---|
| 每实体数据 | Component + Query |
在 World 外自由浮动的结构体 |
| 应用级配置或时钟 | Resource |
把值复制到每个实体上 |
| 稳定的模拟步长 | FixedMain 和 Fixed 时钟 |
把模拟绑定到原始帧 Update |
| 启动时生成 | 在 Startup 中使用 Commands |
从渲染系统生成 |
| 非共享状态的跨系统通知 | bevy-events-messaging 中的消息或观察者槽位 |
在本文件中发明新的事件类型 |
| 文档集合之外的 API | 先查阅官方文档 | 编造的 crate 或 API |
加载 references/ecs-ownership.md 查看所有权表。
禁止事项
- 不要在文档 URL 中固定
/0.20.0/。原因:链接保持在latest;0.20 目标在正文中说明一次即可。 - 不要从两个无序系统可变查询同一组件。原因:除非用
.chain()排序,调度会并行运行系统。 - 不要在此发明物理、导航、网络或 XR crate。原因:本技能只命名有文档记录的 Bevy crate 和模块。
- 此 crate 中不使用 scene-tree 项目类型或 autoload 单例。原因:Bevy 代码保持惯用 ECS,只使用有文档记录的 Bevy API。
- 除本技能命名的 profile 外,不发明 Cargo 特性。原因:Bevy 代码保持惯用 ECS,只使用有文档记录的 Bevy API。
- 不使用第三方 crate。原因:Bevy 代码保持惯用 ECS,只使用有文档记录的 Bevy API。
参考
bevy-master 上的库固定在 0.20 保持不变。
官方文档
- Getting started -
cargo new/cargo add bevy。 - Apps -
App::new()、World和Schedule。 - Examples -
latest分支上的示例树。
相关技能
前置
- bevy-master - 库固定以及下一步加载哪个 Bevy 技能。
互补
- bevy-ecs-composition - crate 存在之后的实体、组件和系统。
下游 / 消费者
- bevy-app-resources -
App存在之后的应用级资源。
主控
- bevy-master - Bevy 路由器。