bevy-project-templates

用途

本技能用于在 Bevy 项目中挑选起始的 Cargo feature 集。当需要决定采用哪套 feature 组合作为项目起点时加载它；应用构建细节属于 bevy-project-foundations，本技能不附带模板仓库。目标版本为 Bevy 0.20+。

主要能力与配置档

默认 profile 启用 2d、3d、ui 与 audio 特性。若希望二进制更小，可关闭默认特性并只选一个 profile：

• 2D crate：禁用默认集，仅启用 2d
• 3D crate：替换为 3d 特性
• UI 工具：启用 ui 特性加 DefaultPlugins
• 无窗口（headless）：default-features = false 搭配 MinimalPlugins

Cargo 配置示例：

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

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

使用方式

有窗口游戏使用 DefaultPlugins，它带来窗口、输入与针对所启用特性的渲染器。

2D 起始代码生成一个摄像机：

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();
}

3D 起始代码同样生成摄像机，但使用 3D 摄像机：

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 与普通 update 系统：

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 写法：

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

ECS 所有权与调度

核心 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

禁止事项

• 不要在文档 URL 中固定 /0.20.0/。原因：链接保持指向最新版，0.20 目标只在正文中说明一次。
• 不要从两个无序系统对同一组件做可变查询。原因：调度会并行运行系统，除非用 .chain() 排序。
• 不要在此发明物理、导航、网络或 XR crate。原因：本技能只引用有文档的 Bevy crate 与模块。
• 不使用 Godot 的 project.godot 模板或导出预设。原因：Bevy 代码保持惯用 ECS 且只用有文档的 Bevy API。
• 不在 Bevy 代码中使用 Godot 类型。原因：Bevy 代码保持惯用 ECS 且只用有文档的 Bevy API。
• 不发明 API，也不把未具名第三方 crate 作为选定方案。原因：Bevy 代码保持惯用 ECS 且只用有文档的 Bevy API。

适用场景与限制

适用于：选择 Bevy 起始 Cargo feature 集、搭建 2D/3D/UI/无窗口项目骨架、确定插件组合与 ECS 所有权划分。

限制：不附带模板仓库；gitignore 与 CI 文件属于仓库而非引擎；不覆盖物理、导航、网络或 XR；不涉及 Godot 相关内容。官方页面保持无版本号的 bevy.org URL，bevy-master 上的库固定为 0.20.0。相关技能：前置为 bevy-master（中枢）与 bevy-project-foundations（Cargo 应用外壳），互补为 bevy-platform-desktop（有窗口目标）；godot-project-templates 为等效的 Godot 技能。下游消费者暂未提供。