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 つのファイルに大量のシステムを並べると、検索するのが大変です！

実装する前に：

1. データモデル（エンティティ、コンポーネント、イベント、システム）を設計する
2. 類似のパターンについて Bevy の使用例を確認する
3. ドキュメントと既存のコードを確認する
4. 機能の領域に対応するプラグインを作成する

ドメイン駆動設計の指針については、references/bevy_specific_tips.md を参照してください。

開発の基本原則

ECS の考え方で捉える

Bevy は Entity Component System（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 は避けてください
• クリーン後の再ビルドのたびに、貴重な開発時間が失われます
• バージョン、ターゲット、クレートの依存関係が絡み合わないよう注意してください
• Bevy は活発に開発されています。1 つのプロジェクトでは 1 つのバージョンに統一してください

ビルドの最適化とバージョン管理の詳細については、references/bevy_specific_tips.md を参照してください。

テストワークフロー

1. コンポーネント変更後： cargo check を実行します
2. システム変更後： cargo check を実行し、その後 cargo build --features bevy/dynamic_linking を実行します
3. 手動テスト：
   • ゲームが起動しますか？
   • 新機能は動作しますか？
   • コンソールログに想定どおりの出力が表示されていますか？
   • 視覚的な変更は正しく表示されますか？

検証ポイント - 以下のマイルストーンでユーザーにテストしてもらいます：

• 新しいエンティティがスポーンしたとき
• 新しいメカニクスが実装されたとき
• 視覚効果が追加されたとき
• 大規模なシステム変更を行ったとき

Bevy での UI 開発

Bevy はフレックスボックスに似たレイアウトシステムを使用します。マーカーコンポーネントのパターンに従ってください：

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 個以上のエンティティ）：

• 近接クエリには空間分割を使用します
• マテリアルの更新をまとめて処理します
• 物理演算には Fixed タイムステップの使用を検討します
• 最適化の前にプロファイリングを行います

クエリ最適化のヒント

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 を確認してください。

複雑な機能でのサブエージェントの使用

複数の手順からなる機能を実装する場合は、次の構成で plan-implementer サブエージェントを使用してください：

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 Cheat Book：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 設計の原則：

• 継承よりコンポジションを優先します
• 1 つのコンポーネントには 1 つの関心事を持たせます
• システムは純粋関数にします
• イベントを使ってシステム間の依存を弱めます
• コーディングの前にデータモデルを設計します
• まずレジストリのサンプルを確認します

---

覚えておいてください： オブジェクトやメソッドではなく、データ（コンポーネント）と変換（システム）の観点で考えましょう。実装に取りかかる前に、必ずレジストリのサンプルを確認し、データモデルを設計してください。これが効果的な Bevy 開発の鍵です。