Bevy

Bevy Game Development Skill

A specialized skill for developing games and applications using the Bevy game engine, based on real-world experience building complex Bevy projects.

When to Use This Skill

Invoke this skill when:

• Implementing features in a Bevy game or application
• Designing component architectures for ECS
• Creating or debugging Bevy systems
• Working with Bevy's UI system
• Building and testing Bevy projects
• Troubleshooting common Bevy issues
• Organizing project structure for Bevy applications

Before You Start: Essential Bevy Tips

⚠️ Bevy 0.19 Breaking Changes

This skill targets Bevy 0.19 (0.19.0, released 2026-06-19) — the current version. For a project still on 0.18, the items below marked as 0.18-era (messages, single()) still apply; see the migration-gotchas section in references/bevy_specific_tips.md for the 0.18 → 0.19 deltas.

When working with Bevy 0.19, be aware of these API shapes:

• Material handles wrapped in MeshMaterial3d<T> (not Handle<T>); meshes in Mesh3d
• Buffered events are "messages": EventWriter→MessageWriter (.write()), EventReader→MessageReader (.read()), add_event::<T>()→add_message::<T>(), #[derive(Event)]→#[derive(Message)]
• Observers (commands.trigger(), add_observer()) are a separate reactive tool — not a replacement for buffered messages
• Queries use .single()/.single_mut() (both return Result); get_single* was removed
• TextFont.font_size is the FontSize enum: font_size: FontSize::Px(35.0)
• Assets::get_mut returns an AssetMut guard — the binding must be mut
• Color arithmetic operations removed (use component extraction)

See references/bevy_specific_tips.md for the full API reference and the "Bevy 0.18 → 0.19 migration gotchas" section.

Consult Bevy Registry Examples First

The registry examples are your bible. Always check them before implementing new features.

Location:

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

There are MANY examples covering all aspects of Bevy development. Review relevant examples to understand best practices and working patterns.

Use Plugin Structure

Break your app into discrete modules using plugins. This improves organization and makes code discoverable.

pub struct CombatPlugin;

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

See references/bevy_specific_tips.md for detailed plugin patterns and examples.

Design Before Coding

Pure ECS demands careful data modeling. It's hard to search a massive list of systems in one file!

Before implementing:

1. Design the data model (entities, components, events, systems)
2. Check Bevy examples for similar patterns
3. Review docs and existing code
4. Create a plugin for the feature domain

See references/bevy_specific_tips.md for domain-driven design guidance.

Core Development Principles

Think in ECS Terms

Bevy is an Entity Component System (ECS) engine. Always think in terms of data (components) and transformations (systems), not objects and methods.

Separation of Concerns:

• Components = Pure data, no logic
• Systems = Pure logic, operate on components
• Messages = Buffered communication between systems (formerly "events", renamed in 0.18)
• Resources = Global state (use sparingly)

Component-Driven Design

Keep components focused:

// ✅ 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
}

Add helper methods via impl blocks:

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

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

For detailed component patterns, see references/ecs_patterns.md.

System Design and Ordering

Order systems by dependencies:

.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,
    ),
)

Use change detection to optimize:

// 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;
    }
}

For detailed query patterns and system design, see references/ecs_patterns.md.

Build and Testing Workflow

Build Commands

Development (faster iteration):

cargo build --features bevy/dynamic_linking

• Uses dynamic linking for faster compile times
• 2-3x faster than release builds
• Only use during development
• CRITICAL: Always use this for development builds

Quick Check:

cargo check

• Fastest way to verify compilation
• Use after every significant change

Release (production):

cargo build --release

• Full optimization
• Use for final testing and distribution

Build Management - CRITICAL

DO NOT delete target binaries freely! Bevy takes minutes to rebuild from scratch.

• Avoid cargo clean unless absolutely necessary
• Each clean rebuild costs valuable development time
• Be mindful of versions, targets, and crate dependencies getting tangled
• Bevy is under active development - stick to one version per project

See references/bevy_specific_tips.md for detailed build optimization and version management.

Testing Workflow

1. After component changes: Run cargo check
2. After system changes: Run cargo check then cargo build --features bevy/dynamic_linking
3. Manual testing:
   • Does the game launch?
   • Do the new features work?
   • Are console logs showing expected output?
   • Do visual changes appear correctly?

Validation points - Let the user test at these milestones:

• New entity spawned
• New mechanic implemented
• Visual effects added
• Major system changes

UI Development in Bevy

Bevy uses a flexbox-like layout system. Follow the marker component pattern:

1. Create marker components:

#[derive(Component)]
pub struct HealthBar;

#[derive(Component)]
pub struct ScoreDisplay;

2. Setup in 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 in 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.single(), ui.single_mut()) {
        node.width = Val::Px(health.percentage() * 200.0);
    }
}

For detailed UI patterns including positioning, styling, and text updates, see references/ui_development.md.

Incremental Development Strategy

Phase-Based Development

Break features into phases:

Phase 1: Foundation - Core components and basic systems Phase 2: Content - Add entities and populate world Phase 3: Polish - UI improvements and visual effects Phase 4: Advanced Features - Complex mechanics and AI

Iteration Pattern

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

Each phase should have:

1. Clear success criteria (checklist of what works)
2. Manual test cases (step-by-step testing procedures)
3. User validation points (when to let user test)

Performance Optimization

When to Optimize

For prototypes (7-100 entities):

• No optimization needed
• Change detection is sufficient
• Focus on features, not performance

For production (100+ entities):

• Use spatial partitioning for proximity queries
• Batch material updates
• Consider Fixed timestep for physics
• Profile before optimizing

Query Optimization Tips

1. Use change detection: Query<&Component, Changed<Component>>
2. Filter early: Query<&A, (With<B>, Without<C>)> instead of filtering in loops
3. Check resource changes: Return early if resource hasn't changed

Common Pitfalls to Avoid

Critical mistakes and their solutions are documented in references/common_pitfalls.md. Key pitfalls include:

1. Forgetting to register systems in main.rs
2. Borrowing conflicts (use get_many_mut for multiple mutations)
3. Not using Changed<T> for expensive operations
4. Wrong system ordering (input → state → derived → visual → UI)
5. Entity queries after despawn (use if let Ok() pattern)
6. Material/asset handle confusion (store handles properly)

Review references/common_pitfalls.md before implementing complex features.

Using Subagents for Complex Features

When implementing multi-step features, use the plan-implementer subagent with this structure:

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]

Example:

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

Project Structure Reference

For details on recommended file organization, module structure, and component file patterns, see references/project_structure.md.

References

This skill includes detailed reference documentation:

• references/bevy_specific_tips.md - START HERE: Registry examples, plugin structure, build optimization, version management, domain-driven design for ECS
• references/ecs_patterns.md - Component design patterns, query patterns, and common ECS design patterns (Derivation, State Machine, Threshold/Trigger, Event-Driven, Initialization)
• references/ui_development.md - Bevy UI hierarchy, component patterns, layout tips, positioning, styling, and text updates
• references/common_pitfalls.md - Common mistakes and their solutions (system registration, borrowing conflicts, change detection, system ordering, entity queries, asset handles)
• references/project_structure.md - Recommended file organization, module structure, component file patterns, and change detection

Load these references as needed to inform implementation decisions.

Additional Resources

Bevy Documentation:

• Official Bevy Book: https://bevyengine.org/learn/book/
• Bevy Examples: https://github.com/bevyengine/bevy/tree/main/examples (also in ~/.cargo/registry/...)
• Bevy Cheat Book: https://bevy-cheatbook.github.io/
• Plugin Guide: https://bevy.org/learn/quick-start/getting-started/plugins/
• System Sets: https://bevy-cheatbook.github.io/programming/system-sets.html
• Setup & Optimization: https://bevy.org/learn/quick-start/getting-started/setup/

ECS Design Principles:

• Prefer composition over inheritance
• One component = one concern
• Systems should be pure functions
• Use messages (buffered) to decouple systems; observers for immediate reactions
• Design data model before coding
• Check registry examples first

Remember: Think in terms of data (components) and transformations (systems), not objects and methods. Always consult registry examples and design your data model before diving into implementation. This is the key to effective Bevy development.