用途
当游戏数据应当拆分到多个小型组件与系统中,而不是由一个类型拥有全部内容时,可加载本技能。它围绕 Bevy 0.20 的 ECS 组合方式,说明实体、组件与系统之间如何分工。
主要能力
- 组件(Components):派生
Component的 Rust 结构体。示例把Person与Name拆开,使不止一种实体都能携带名字。 - 实体(Entities):在
Startup系统中通过Commands生成,可一次生成组件元组,例如commands.spawn((Person, Name(...)))。 - 系统(Systems):普通函数。
Query<&Name, With<Person>>读取同时拥有Person的实体上的名字;Query<&mut Name, With<Person>>用于写入。通过add_systems注册。 - 调度(Schedule):
Startup只运行一次,Update在其后运行。除非调用.chain(),系统会并行执行。示例把update_people排在greet_people之前,并把无关系统留在链外。 - 支持生成组件元组、用
ChildOf建立父子关系、用Changed做变更检测。
组合选择
| 需求 | Bevy 惯用法 |
|---|---|
| 一个对象上拥有多个部件 | 同一实体上挂多个 Component 结构体 |
| 行为 | 针对 Query 的系统函数 |
| 启动时生成 | Startup 系统中的 Commands |
| 有序步骤 | 对相互依赖的系统调用 .chain() |
| 父与子 | 在子实体上使用 ChildOf |
使用方式
依赖配置:
[package]
name = "ecs-composition"
version = "0.1.0"
edition = "2021"
[dependencies]
bevy = "0.20"
示例一:人物携带名字,问候在重命名之后、于同一条链中运行。
#[derive(Component)]
struct Person;
#[derive(Component)]
struct Name(String);
fn spawn_people(mut commands: Commands) {
commands.spawn((Person, Name("Ada".to_string())));
commands.spawn(Name("crate".to_string()));
}
fn update_people(mut people: Query<&mut Name, With<Person>>) {
for mut name in &mut people {
name.0.push('!');
}
}
fn greet_people(people: Query<&Name, With<Person>>) {
for name in &people {
let _label = name.0.as_str();
}
}
fn count_names(names: Query<&Name>) {
let _total = names.iter().count();
}
pub struct PeoplePlugin;
impl Plugin for PeoplePlugin {
fn build(&self, app: &mut App) {
app.add_systems(Startup, spawn_people).add_systems(
Update,
(update_people, greet_people).chain(),
);
app.add_systems(Update, count_names);
}
}
count_names 只读取 Name,留在写入它的链之外。
示例二:父、子,以及名字变化时运行的系统。
#[derive(Component)]
struct Name(String);
fn spawn_family(mut commands: Commands) {
let parent = commands.spawn(Name("parent".to_string())).id();
commands.spawn((Name("child".to_string()), ChildOf(parent)));
}
fn on_rename(renamed: Query<&Name, Changed<Name>>) {
for name in &renamed {
let _label = name.0.as_str();
}
}
pub struct FamilyPlugin;
impl Plugin for FamilyPlugin {
fn build(&self, app: &mut App) {
app.add_systems(Startup, spawn_family)
.add_systems(Update, on_rename);
}
}
状态归属
目标版本为 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 插入,随后由读取它的调度 |
| 生成 | Commands |
执行生成的系统 | 初始世界用 Startup;运行时生成用后续调度 |
| 不可竞争的顺序 | .chain() |
仅被链入的系统 | 同一调度 |
| 插件边界 | Plugin |
build 注册系统与资源 |
应用运行之前 |
借用规则:两个系统若都可变查询同一组件,必须排序(.chain())或拆分,使只有一个写入。无关系统保持并行。
决策参考
| 若需要 | 这样做 | 不要 |
|---|---|---|
| 每实体数据 | Component + Query |
用一个结构体存储每个实体的字段 |
| 应用级配置或时钟 | Resource |
把值复制到每个实体 |
| 稳定模拟步长 | FixedMain 与 Fixed 时钟 |
把模拟绑定到原始帧 Update |
| 启动生成 | Startup 中的 Commands |
从渲染系统生成 |
| 非共享状态的跨系统通知 | bevy-events-messaging 中的消息或观察者槽位 |
在本文件中新造事件类型 |
| 文档集合之外的 API | 阅读所链接的 Bevy 页面 | 编造的 crate 或 API |
限制与禁止事项
- 不要在文档 URL 中固定
/0.20.0/;链接保持在latest,0.20 目标只在正文中说明一次。 - 不要从两个未排序的系统可变查询同一组件。
- 不要在此处编造物理、导航、网络或 XR crate;本技能只命名有文档的 Bevy crate 与模块。
- 不要用单个组件存储实体的所有行为。
- 不要使用本文件未打开的
BundleAPI。 - 不要使用第三方 crate。
范围
- 元组生成、
ChildOf、Changed与.chain()均在示例中。 - 编辑器控件树不在范围内;此处的组合指实体、组件与系统。
参考
官方文档:
- Quick Start: ECS(
Component、Query、With、Commands、Startup、Update、.chain()):https://bevy.org/learn/quick-start/getting-started/ecs/ - Apps(
App持有World与Schedule):https://bevy.org/learn/quick-start/getting-started/apps/ - Examples(
latest分支示例树):https://github.com/bevyengine/bevy/tree/latest/examples#examples
相关技能:
- 前置:bevy-master(状态归属)、bevy-project-foundations(crate 与
App外壳) - 互补:bevy-data-resources(不应作为组件的应用级数据)、bevy-events-messaging(非共享组件的跨系统通知)
- 下游:bevy-character-movement(固定时间步上的移动组件与系统)
- 主路由:bevy-master