SuperAPI AI 工具集

bevy-project-foundations

编程与开发

查看项目

更新于 10-16 10:39

技能介绍

用途

当新的 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 保持不变。

官方文档

相关技能

前置

  • bevy-master - 库固定以及下一步加载哪个 Bevy 技能。

互补

下游 / 消费者

主控