SuperAPI AI 工具集

bevy-ecs-composition

编程与开发

查看项目

更新于 10-16 10:37

技能介绍

用途

当游戏数据应当拆分到多个小型组件与系统中,而不是由一个类型拥有全部内容时,可加载本技能。它围绕 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 与模块。
  • 不要用单个组件存储实体的所有行为。
  • 不要使用本文件未打开的 Bundle API。
  • 不要使用第三方 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