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 不在本技能范围内。