bevy

What this skill does

# 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.17 Breaking Changes

**If working with Bevy 0.17**, be aware of significant API changes:
- Material handles now wrapped in `MeshMaterial3d<T>` (not `Handle<T>`)
- Event system replaced with observer pattern (`commands.trigger()`, `add_observer()`)
- Color arithmetic operations removed (use component extraction)

**See `references/bevy_specific_tips.md` for complete Bevy 0.17 migration guide and examples.**

### Consult Bevy Registry Examples First

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

**Location:**
```bash
~/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/bevy-0.17.1/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.

```rust
pub struct CombatPlugin;

impl Plugin for CombatPlugin {
    fn build(&self, app: &mut App) {
        app
            .add_event::<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
- **Events** = Communication between systems
- **Resources** = Global state (use sparingly)

### Component-Driven Design

**Keep components focused:**
```rust
// ✅ 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:**
```rust
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:**
```rust
.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:**
```rust
// 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):**
```bash
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:**
```bash
cargo check
```
- Fastest way to verify compilation
- Use after every significant change

**Release (production):**
```bash
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:**
```rust
#[derive(Component)]
pub struct HealthBar;

#[derive(Component)]
pub struct ScoreDisplay;
```

**2. Setup in Startup:**
```rust
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:**
```rust
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);
    }
}
```

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<Compo