bevy

Bevy 游戏开发技能

一项专用于使用 Bevy 游戏引擎开发游戏和应用的技能，基于构建复杂 Bevy 项目的真实经验。

何时使用此技能

在以下情况下调用此技能：

• 在 Bevy 游戏或应用中实现功能
• 设计 ECS 组件架构
• 创建或调试 Bevy 系统
• 使用 Bevy 的 UI 系统
• 构建和测试 Bevy 项目
• 排查常见的 Bevy 问题
• 组织 Bevy 应用的项目结构

开始之前：Bevy 必备提示

⚠️ Bevy 0.17 中的破坏性变更

如果使用 Bevy 0.17，请注意其 API 有重大变更：

• 材质句柄现在包装在 MeshMaterial3d<T> 中（不再是 Handle<T>）
• 事件系统已替换为观察者模式（commands.trigger()、add_observer()）
• 已移除颜色算术运算（请使用分量提取）

完整的 Bevy 0.17 迁移指南和示例，请参阅 references/bevy_specific_tips.md。

首先查阅 Bevy 注册表示例

注册表示例就是你的宝典。 实现新功能前，务必先查看这些示例。

位置：

~/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/bevy-0.17.1/examples

其中包含大量涵盖 Bevy 开发各方面的示例。请查看相关示例，了解最佳实践和可行模式。

使用插件结构

将应用拆分为独立模块，并使用插件组织。这有助于提升结构清晰度，让代码更易于查找。

pub struct CombatPlugin;

impl Plugin for CombatPlugin {
    fn build(&self, app: &mut App) {
        app
            .add_event::<DamageEvent>()
            .add_systems(Update, (process_damage, check_death));
    }
}

详细的插件模式和示例，请参阅 references/bevy_specific_tips.md。

编码前先设计

纯 ECS 要求仔细进行数据建模。 在一个文件中搜索大量系统会很困难！

实现前请：

1. 设计数据模型（实体、组件、事件、系统）
2. 查看 Bevy 示例，寻找类似模式
3. 查阅文档和现有代码
4. 为功能领域创建插件

领域驱动设计指南请参阅 references/bevy_specific_tips.md。

核心开发原则

用 ECS 的思路思考

Bevy 是一个实体组件系统（ECS）引擎。始终从数据（组件）和变换（系统）的角度思考，而不是从对象和方法的角度思考。

职责分离：

• 组件 = 纯数据，不包含逻辑
• 系统 = 纯逻辑，操作组件
• 事件 = 系统之间的通信
• 资源 = 全局状态（谨慎使用）

组件驱动设计

让组件保持专注：

// ✅ GOOD: Small, focused components
#[derive(Component)]
pub struct Health { pub current: f32, pub max: f32 }

#[derive(Component)]
pub struct Armor { pub defense: f32 }

// ❌ BAD: Monolithic component
#[derive(Component)]
pub struct CombatStats {
    pub health: f32,
    pub armor: f32,
    pub strength: f32,
    // ... wastes memory for entities that only have some stats
}

通过 impl 块添加辅助方法：

impl Health {
    pub fn is_alive(&self) -> bool {
        self.current > 0.0
    }

    pub fn percentage(&self) -> f32 {
        self.current / self.max
    }
}

详细的组件模式请参阅 references/ecs_patterns.md。

系统设计与排序

根据依赖关系排列系统：

.add_systems(
    Update,
    (
        // 1. Input processing
        handle_input,

        // 2. State changes
        process_events,
        update_state,

        // 3. Derive properties from state
        calculate_derived_values,

        // 4. Visual updates
        update_materials,
        update_animations,

        // 5. UI updates (must run last)
        update_ui_displays,
    ),
)

使用变更检测进行优化：

// Only process entities where Health changed
pub fn update_health_bar(
    query: Query<(&Health, &mut HealthBar), Changed<Health>>,
) {
    for (health, mut bar) in query.iter_mut() {
        bar.width = health.percentage() * 100.0;
    }
}

详细的查询模式和系统设计请参阅 references/ecs_patterns.md。

构建与测试工作流

构建命令

开发（迭代更快）：

cargo build --features bevy/dynamic_linking

• 使用动态链接以缩短编译时间
• 速度比发布构建快 2-3 倍
• 仅在开发期间使用
• **重要：**开发构建时务必使用此方式

快速检查：

cargo check

• 验证编译是否成功的最快方式
• 每次重大改动后使用

发布（生产环境）：

cargo build --release

• 完整优化
• 用于最终测试和分发

构建管理 — 重要

不要随意删除 target 二进制文件！ Bevy 从头开始重新构建需要几分钟。

• 除非绝对必要，否则避免使用 cargo clean
• 每次清理后重新构建都会耗费宝贵的开发时间
• 注意版本、目标和 crate 依赖可能会相互混淆
• Bevy 正在积极开发中——每个项目应坚持使用同一个版本

详细的构建优化和版本管理请参阅 references/bevy_specific_tips.md。

测试工作流

1. 组件变更后： 运行 cargo check
2. 系统变更后： 先运行 cargo check，再运行 cargo build --features bevy/dynamic_linking
3. 手动测试：
   • 游戏能否启动？
   • 新功能是否正常运行？
   • 控制台日志是否显示预期输出？
   • 视觉变更是否正确显示？

验证节点——在以下里程碑让用户测试：

• 生成新实体
• 实现新机制
• 添加视觉效果
• 重大系统变更

在 Bevy 中开发 UI

Bevy 使用类似 flexbox 的布局系统。请遵循标记组件模式：

1. 创建标记组件：

#[derive(Component)]
pub struct HealthBar;

#[derive(Component)]
pub struct ScoreDisplay;

2. 在 Startup 中设置：

pub fn setup_ui(mut commands: Commands) {
    commands.spawn((
        HealthBar,
        Node {
            position_type: PositionType::Absolute,
            left: Val::Px(10.0),
            top: Val::Px(10.0),
            width: Val::Px(200.0),
            height: Val::Px(20.0),
            ..default()
        },
        BackgroundColor(Color::srgba(0.8, 0.2, 0.2, 0.9)),
    ));
}

3. 在 Update 中更新：

pub fn update_health_ui(
    health: Query<&Health, With<Player>>,
    mut ui: Query<&mut Node, With<HealthBar>>,
) {
    if let (Ok(health), Ok(mut node)) = (health.get_single(), ui.get_single_mut()) {
        node.width = Val::Px(health.percentage() * 200.0);
    }
}

有关 UI 模式的详细信息，包括定位、样式和文本更新，请参阅 references/ui_development.md。

渐进式开发策略

分阶段开发

将功能拆分为多个阶段：

阶段 1：基础——核心组件和基础系统 阶段 2：内容——添加实体并填充世界 阶段 3：润色——改进 UI 并添加视觉效果 阶段 4：高级功能——复杂机制和 AI

迭代模式

1. Plan → 2. Implement → 3. Build → 4. Test → 5. Refine
     ↑                                           ↓
     ←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←←

每个阶段都应包含：

1. 明确的成功标准（检查哪些功能正常）
2. 手动测试用例（逐步测试流程）
3. 用户验证节点（何时让用户测试）

性能优化

何时优化

原型（7-100 个实体）：

• 无需优化
• 变更检测已足够
• 专注于功能，而非性能

生产环境（100 个以上实体）：

• 使用空间分区进行邻近查询
• 批量更新材质
• 考虑对物理使用固定时间步长
• 优化前先进行性能分析

查询优化技巧

1. 使用变更检测： Query<&Component, Changed<Component>>
2. 尽早过滤： 使用 Query<&A, (With<B>, Without<C>)>，而不是在循环中进行过滤
3. 检查资源变更： 如果资源没有变更，则提前返回

应避免的常见陷阱

关键错误及其解决方案记录在 references/common_pitfalls.md 中。主要陷阱包括：

1. 忘记在 main.rs 中注册系统
2. 借用冲突（对多项修改使用 get_many_mut）
3. 对开销较大的操作不使用 Changed<T>
4. 系统顺序错误（输入 → 状态 → 派生 → 视觉 → UI）
5. 实体销毁后仍进行查询（使用 if let Ok() 模式）
6. 混淆材质和资源句柄（妥善保存句柄）

实现复杂功能前，请先查看 references/common_pitfalls.md。

使用子 Agent 实现复杂功能

实现多步骤功能时，请使用 plan-implementer 子 Agent，并遵循以下结构：

Goal: [One sentence describing end state]

Current State: [What exists now]

Requirements: [Numbered list of what to build]

Implementation Steps: [Suggested approach]

Success Criteria: [How to verify it works]

Notes: [Important context, edge cases, design principles]

示例：

Implement Health System

Goal: Implement a health system with damage, healing, and death mechanics.

Current State:
- Player entity exists
- No health tracking yet

Requirements:
1. Create Health component with current/max values
2. Create DamageEvent for dealing damage
3. Create system to process damage events
4. Add death detection when health reaches 0
5. Add visual health bar UI

Implementation Steps:
1. Create Health component in src/components/properties.rs
2. Create DamageEvent in src/events.rs
3. Create process_damage system in src/systems/combat.rs
4. Create check_death system
5. Create health bar UI in src/systems/ui/health_bar.rs
6. Register all systems in main.rs in correct order

Success Criteria:
- Player spawns with Health component
- Damage events reduce health
- Health bar updates when health changes
- Entity despawns when health reaches 0
- Code compiles without errors

项目结构参考

有关推荐的文件组织方式、模块结构和组件文件模式的详细信息，请参阅 references/project_structure.md。

参考资料

此技能包含详细的参考文档：

• references/bevy_specific_tips.md - 从此处开始： 注册表示例、插件结构、构建优化、版本管理、面向 ECS 的领域驱动设计
• references/ecs_patterns.md - 组件设计模式、查询模式和常见 ECS 设计模式（派生、状态机、阈值/触发器、事件驱动、初始化）
• references/ui_development.md - Bevy UI 层级结构、组件模式、布局技巧、定位、样式和文本更新
• references/common_pitfalls.md - 常见错误及其解决方案（系统注册、借用冲突、变更检测、系统顺序、实体查询、资源句柄）
• references/project_structure.md - 推荐的文件组织方式、模块结构、组件文件模式和变更检测

请根据需要加载这些参考资料，以辅助实现决策。

其他资源

Bevy 文档：

• Bevy 官方手册：https://bevyengine.org/learn/book/
• Bevy 示例：https://github.com/bevyengine/bevy/tree/main/examples（也可在 ~/.cargo/registry/... 中找到）
• Bevy 速查手册：https://bevy-cheatbook.github.io/
• 插件指南：https://bevy.org/learn/quick-start/getting-started/plugins/
• 系统集：https://bevy-cheatbook.github.io/programming/system-sets.html
• 设置与优化：https://bevy.org/learn/quick-start/getting-started/setup/

ECS 设计原则：

• 优先使用组合，而非继承
• 一个组件 = 一个关注点
• 系统应当是纯函数
• 使用事件解耦系统
• 编码前先设计数据模型
• 先查看注册表中的示例

---

请记住： 从数据（组件）和变换（系统）的角度思考，而不是从对象和方法的角度思考。动手实现前，务必先查阅注册表中的示例并设计数据模型。这是高效进行 Bevy 开发的关键。