bevy-master

Bevy Master：ECS 中心

适用于 Bevy 0.20+ 的 ECS 中心。从这里开始搭建 Bevy 应用，确定哪些组件、资源和系统负责管理各部分状态，并根据任务加载合适的 Bevy 技能。

库目标版本

目标版本：Bevy 0.20+（已针对 0.20.0 测试）。

ECS 中各司其职

对于每一项状态，请明确：

• 由哪个组件或资源负责管理
• 哪个系统可以修改它
• 哪条消息或哪个观察者应该监听它

调度计划取代场景树。不要添加自动加载项、信号总线或层层嵌套的 Node。

ECS 快速入门页面介绍了实体、组件（Component）、作为函数的系统、Query、Commands、Startup 和 Update，以及用于排序的 .chain()。消息、观察者、资源和应用状态分别在各自的技能中介绍。引用某个类型之前，请先查看对应文件。

路由

场景	路由
新建 Bevy 应用、划分 ECS 职责、选择要加载的技能	本中心，然后查看下方的模块目录
新建 crate、Cargo 功能、功能目录	bevy-project-foundations
将 Artifact ledger 导入 Bevy crate	gdas-reader，然后查看 bevy-rea
实体组合、组件、系统	bevy-ecs-composition
消息、事件、观察者	bevy-events-messaging
作为数据的组件和资源	bevy-data-resources
应用状态或单个实体的模式标记	bevy-state-machines
全应用资源和调度计划	bevy-app-resources
角色移动	bevy-character-movement
3D 物理	bevy-physics-3d
2D 物理	bevy-physics-2d
射线、重叠查询或物理拾取	bevy-spatial-queries
导航网格或路径数据	bevy-navigation
追逐、巡逻、重新指定目标	bevy-ai-navigation
带种子的关卡或战利品布局	bevy-procedural-generation
键盘、鼠标、游戏手柄	bevy-input-handling
2D 或 3D 摄像机实体	bevy-camera-systems
播放或控制片段	bevy-audio-systems
加载资源或生成场景	bevy-asset-scenes
玩家存档槽位	bevy-save-load
日志和帧诊断	bevy-debugging-profiling
并行处理、固定步长、句柄生命周期	bevy-performance
cargo test	bevy-testing-patterns
片段、混合图、精灵、灯光、材质、UI 或游戏类型循环	下方的模块目录

何时不应生成实体

不会参与模拟的数据可以是普通 Rust 结构体或资源。快速入门将资源视为全应用数据。分数或种子可以是在启动时插入的一个 Resource。不要把 Godot Object / RefCounted / Resource / Node 表照搬到 Bevy 中。

工作流

（a）应用脚手架。 App::new()、插件、调度和状态。插件页面介绍了 Plugin、DefaultPlugins、MinimalPlugins 和 add_plugins。bevy 0.20.0 crate 文档列出了 bevy_state 功能（“内置全局状态机”）。States、init_state 和 OnEnter 是状态 API。不要在 DefaultPlugins / MinimalPlugins 之外臆造插件列表。

（b）实体。 组件加系统。移动应使用固定时间步。bevy::time 0.20.0 文档介绍了 Fixed（“固定时间步游戏时钟”）和 run_fixed_main_schedule（FixedMain）。不要臆造这些名称之外的调度标签。

（c）数据。 组件和资源，不是 .tres 文件。

（d）性能。 ECS 页面指出，在条件允许时，系统默认并行运行，.chain() 则会强制按顺序执行。帧时间诊断和句柄生命周期见 bevy-performance。这些页面未规定任何数值预算。

示例

[package]
name = "bevy-app"
version = "0.1.0"
edition = "2021"

[dependencies]
bevy = "0.20"

新建应用会添加 DefaultPlugins、插入一个资源，并在启动时生成玩家。

#[derive(Resource)]
struct Score(u32);

#[derive(Component)]
struct Player;

fn spawn_player(mut commands: Commands) {
    commands.insert_resource(Score(0));
    commands.spawn((Player, Transform::from_xyz(0.0, 0.0, 0.0)));
}

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, spawn_player)
        .run();
}

输入会写入速度。移动会写入 Transform。它们共享 Player 数据，因此会在 FixedUpdate 中链接执行。

#[derive(Component)]
struct Velocity(Vec2);

fn read_input(
    keys: Res<ButtonInput<KeyCode>>,
    mut players: Query<&mut Velocity>,
) {
    for mut velocity in &mut players {
        let mut dir = Vec2::ZERO;
        if keys.pressed(KeyCode::KeyA) {
            dir.x -= 1.0;
        }
        if keys.pressed(KeyCode::KeyD) {
            dir.x += 1.0;
        }
        if keys.pressed(KeyCode::KeyW) {
            dir.y += 1.0;
        }
        if keys.pressed(KeyCode::KeyS) {
            dir.y -= 1.0;
        }
        velocity.0 = dir.normalize_or_zero() * 4.0;
    }
}

fn apply_velocity(
    time: Res<Time<Fixed>>,
    mut players: Query<(&Velocity, &mut Transform)>,
) {
    let dt = time.delta_secs();
    for (velocity, mut transform) in &mut players {
        transform.translation.x += velocity.0.x * dt;
        transform.translation.y += velocity.0.y * dt;
    }
}

pub struct MovementPlugin;

impl Plugin for MovementPlugin {
    fn build(&self, app: &mut App) {
        app.add_systems(FixedUpdate, (read_input, apply_velocity).chain());
    }
}

AppState 是全局状态。进入 Playing 时会运行一次生成系统。

#[derive(States, Debug, Clone, PartialEq, Eq, Hash, Default)]
enum AppState {
    #[default]
    Loading,
    Playing,
}

#[derive(Component)]
struct Player;

fn enter_playing(mut commands: Commands) {
    commands.spawn((Player, Transform::from_xyz(0.0, 0.0, 0.0)));
}

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .init_state::<AppState>()
        .add_systems(OnEnter(AppState::Playing), enter_playing)
        .run();
}

专家知识差异

目标：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()），或拆分查询，使其只有一个系统写入。无关系统保持并行。这是 ECS 页面的规则，并非对系统集 API 的猜测。

决策

如果需要	请这样做	不要这样做
每个实体的数据	Component + Query	Godot 节点脚本
应用级配置或时钟	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 和模块。

• 不要在 Bevy 代码中导入 Godot 或 gdext 类型。原因：Bevy 代码应遵循惯用的 ECS 写法，并且只使用有文档说明的 Bevy API。

• 不要将 GDScript 逐行转换。原因：Bevy 代码应遵循惯用的 ECS 写法，并且只使用有文档说明的 Bevy API。

• 不要使用此文件中未查阅过的 API。原因：Bevy 代码应遵循惯用的 ECS 写法，并且只使用有文档说明的 Bevy API。

• 不要使用 Coil 或 Ouroboros UI。原因：Bevy 代码应遵循惯用的 ECS 写法，并且只使用有文档说明的 Bevy API。

模块目录

领域技能：

• bevy-project-foundations
• gdas-reader
• bevy-rea
• bevy-ecs-composition
• bevy-events-messaging
• bevy-data-resources
• bevy-state-machines
• bevy-app-resources
• bevy-character-movement
• bevy-physics-3d
• bevy-physics-2d
• bevy-spatial-queries
• bevy-navigation
• bevy-ai-navigation
• bevy-procedural-generation
• bevy-input-handling
• bevy-camera-systems
• bevy-audio-systems
• bevy-asset-scenes
• bevy-save-load
• bevy-debugging-profiling
• bevy-performance
• bevy-testing-patterns

渲染与动画：

• bevy-2d-animation
• bevy-animation
• bevy-animation-graph
• bevy-particles
• bevy-shaders
• bevy-tilemap
• bevy-tweening
• bevy-3d-lighting
• bevy-3d-materials
• bevy-3d-world-building

游戏玩法：

• bevy-ability-system
• bevy-combat-system
• bevy-dialogue-system
• bevy-economy-system
• bevy-game-loop-collection
• bevy-game-loop-harvest
• bevy-game-loop-time-trial
• bevy-game-loop-waves
• bevy-inventory-system
• bevy-mechanic-revival
• bevy-mechanic-secrets
• bevy-quest-system
• bevy-rpg-stats
• bevy-turn-system

UI、平台、适配与模板：

• bevy-ui-layout
• bevy-ui-text
• bevy-ui-theming
• bevy-platform-desktop
• bevy-platform-web
• bevy-platform-mobile
• bevy-adapt-2d-to-3d
• bevy-adapt-3d-to-2d
• bevy-adapt-desktop-to-mobile
• bevy-adapt-mobile-to-desktop
• bevy-project-templates

类型路由：

• bevy-genre-action-rpg
• bevy-genre-fighting
• bevy-genre-platformer
• bevy-genre-shooter
• bevy-genre-shooter-fps
• bevy-genre-rts
• bevy-genre-tower-defense
• bevy-genre-metroidvania
• bevy-genre-open-world
• bevy-genre-roguelike
• bevy-genre-survival
• bevy-genre-card-game
• bevy-genre-educational
• bevy-genre-horror
• bevy-genre-puzzle
• bevy-genre-visual-novel
• bevy-genre-romance
• bevy-genre-idle-clicker
• bevy-genre-party
• bevy-genre-racing
• bevy-genre-rhythm
• bevy-genre-sandbox
• bevy-genre-simulation
• bevy-genre-sports
• bevy-genre-stealth

参考

官方文档

• bevy crate - 未指定版本的 API 索引。固定页面上的功能示例可能仍显示较旧的版本字符串。
• 资源 - 官方资源目录。
• 示例 - latest 分支上的示例目录树，而非发布标签。
• 快速入门 - 指南索引。旧版 /learn/book/ 路径于 2026-10-11 返回 404。
• 入门 - 在学习 ECS 和插件之前进行应用设置。
• ECS - 实体、组件、系统、Query、Commands、Startup、Update 和 .chain()。
• 插件 - Plugin、DefaultPlugins、MinimalPlugins 和 add_plugins。
• bevy::time - Fixed 和 run_fixed_main_schedule（FixedMain）。
• crates.io bevy - 发布版本固定来源（0.20.0，2026-10-08）。

相关技能

前置条件

• 无。此中心是 Bevy 的入口。

补充技能

• godot-master - Godot 中心。

下游 / 使用者

• bevy-project-foundations - Crate、Cargo 功能和项目布局习惯。
• bevy-ecs-composition - 组件、生成元组、查询和 .chain()。
• bevy-events-messaging - Message 读取器和 Event 观察者。
• bevy-data-resources - Component 与 Resource 的区别。
• bevy-state-machines - bevy::state 和每个实体的模式标记。
• bevy-app-resources - 应用全局资源以及 Startup / Update。
• bevy-character-movement - 固定时间步中的玩家和角色移动。
• bevy-physics-3d - 验证求解器 Crate 后的模拟 3D 刚体。
• bevy-physics-2d - 模拟 2D 刚体。
• bevy-spatial-queries - 投射和重叠检测。尚未选定求解器。
• bevy-navigation - 路径数据。
• bevy-ai-navigation - 追逐和巡逻策略。
• bevy-procedural-generation - 种子资源和生成。不涉及噪声 API。
• bevy-input-handling - ButtonInput、鼠标和游戏手柄。
• bevy-camera-systems - Camera2d 和 Camera3d。
• bevy-audio-systems - AudioPlayer 和 AudioSink。
• bevy-asset-scenes - AssetServer 和 spawn_scene。
• bevy-save-load - 玩家存档槽。场景生成不等于存档。
• bevy-debugging-profiling - LogPlugin 和诊断插件。
• bevy-performance - 并行系统、固定步长和句柄生命周期。
• bevy-testing-patterns - cargo test。不是 GdUnit。

主技能

• 此文件。不要将 Bevy 工作交给同时负责 Godot 的父级技能。

Cipher 规则仅适用于标题：运行时游戏逻辑使用 Rust；不要将 Godot 类型引入 Bevy Crate。

范围

• 资源、状态、消息和观察者各有自己的技能。只调用这些技能中提及的类型。编写状态安装方法前，请查阅 App 文档，确认方法名称。
• 入门代码片段仍显示 bevy = "0.19"，而 crates.io 上的最新版本是 0.20.0。请依据 crates.io 和 Bevy API 参考，将版本固定为 0.20.0，不要参考过时的代码片段。
• Bevy API 参考的 0.20.0 页面中，功能示例仍有一处显示 version = "0.18"。该示例不是要固定的版本。