SuperAPI AI 工具集

bevy-project-templates

编程与开发

查看项目

更新于 10-16 10:40

技能介绍

Bevy project templates 是一个面向 Bevy 游戏引擎项目的技能,用于帮助开发者选择项目的起始 Cargo 特性集合。它适用于 Bevy 0.20+,目标场景是在搭建新项目、决定启用哪些 Cargo feature 时参考。

用途

当你需要为 Bevy 二进制确定一套起始特性配置时,加载本技能。应用构建的细节由 bevy-project-foundations 负责,本技能不附带模板仓库。

主要能力

配置档案(Profiles)

  • default 会启用 2d、3d、ui 和 audio。
  • 若希望二进制体积更小,可关闭默认特性,只选择其中一个 profile。

窗口化游戏

  • DefaultPlugins 会带来窗口、输入,以及你已启用特性所对应的渲染器。

无头(Headless)

  • MinimalPlugins 在没有窗口、没有渲染器的情况下调度应用,需配合 default-features = false 使用。

使用方式

2D crate 关闭默认特性集合,仅启用 2d profile。若整个二进制都是 3D 或 UI,则替换为 3d 或 ui 特性。

[package]
name = "game"
version = "0.1.0"
edition = "2021"

[dependencies]
bevy = { version = "0.20", default-features = false, features = ["2d"] }

2D 起点会生成一个相机,3D 起点同样如此,只是使用 3D 相机。二者都假定使用 DefaultPlugins。

fn setup_2d(mut commands: Commands) {
    commands.spawn(Camera2d);
}

pub struct FlatPlugin;

impl Plugin for FlatPlugin {
    fn build(&self, app: &mut App) {
        app.add_systems(Startup, setup_2d);
    }
}

fn main() {
    App::new().add_plugins((DefaultPlugins, FlatPlugin)).run();
}
fn setup_3d(mut commands: Commands) {
    commands.spawn((Camera3d::default(), Transform::from_xyz(0.0, 2.0, 6.0)));
}

pub struct ScenePlugin;

impl Plugin for ScenePlugin {
    fn build(&self, app: &mut App) {
        app.add_systems(Startup, setup_3d);
    }
}

无头工具使用 MinimalPlugins 与一个普通的更新系统。

fn tick(mut frames: ResMut<FrameCount>) {
    frames.0 += 1;
}

#[derive(Resource, Default)]
struct FrameCount(u32);

fn main() {
    App::new()
        .add_plugins(MinimalPlugins)
        .init_resource::<FrameCount>()
        .add_systems(Update, tick)
        .run();
}

对应关系表

设计 Bevy 惯用法
2D 起点 Cargo 特性 2d、DefaultPlugins、Camera2d
3D 起点 Cargo 特性 3d、DefaultPlugins、Camera3d
UI 工具 Cargo 特性 ui 加 DefaultPlugins
无头 default-features = false 与 MinimalPlugins

适用范围

Gitignore 与 CI 文件属于仓库,不属于引擎。上述特性标志与插件集合是起点。

专家知识要点

目标: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 先查官方文档 编造的 crate 或 API

加载 references/ecs-ownership.md 查看归属表。

禁止事项

  • 不要在文档 URL 中固定 /0.20.0/。原因:链接保持在 latest;0.20 目标只在正文中声明一次。
  • 不要从两个无顺序系统中可变查询同一组件。原因:除非 .chain() 排序,调度会并行运行系统。
  • 不要在此编造物理、导航、网络或 XR crate。原因:本技能只点出有文档记载的 Bevy crate 与模块。
  • 不提供 Godot 的 project.godot 模板或导出预设。原因:Bevy 代码保持惯用 ECS,只使用有文档的 Bevy API。
  • 不要在 Bevy 代码中使用 Godot 类型。原因:同上。
  • 不要使用编造的 API 或未具名的第三方 crate 作为选定方案。原因:同上。

限制

本技能只涉及特性标志与插件集合的起点选择,不附带模板仓库,也不包含 gitignore、CI 等仓库层文件。物理、导航、网络、XR 等外部 crate 不在本技能范围内。