@jarrodmedrano/claude-skills 1.0.3 → 1.0.4

package/.claude/skills/bevy/references/ecs_patterns.md

@@ -0,0 +1,277 @@
+# Bevy ECS Patterns Reference
+
+## Component Design Patterns
+
+### Component Types
+
+**1. Data Components**
+Store game state, always derive `Component`:
+```rust
+#[derive(Component, Clone, Debug)]
+pub struct BigFive {
+    pub openness: f32,
+    pub conscientiousness: f32,
+    pub extraversion: f32,
+    pub agreeableness: f32,
+    pub neuroticism: f32,
+}
+```
+
+**2. Marker Components**
+Used for queries and categorization:
+```rust
+#[derive(Component)]
+pub struct Player;
+
+#[derive(Component)]
+pub struct NPC;
+
+#[derive(Component)]
+pub struct Burning;  // Marker: entity is on fire
+```
+
+**3. Tag Components**
+Temporary state or UI markers:
+```rust
+#[derive(Component)]
+pub struct HoveredEntity;
+
+#[derive(Component)]
+pub struct InspectedEntity;
+```
+
+### Component Best Practices
+
+**✅ DO:**
+- Keep components focused on single responsibility
+- Use `Option<T>` for components that may not always be present
+- Derive `Clone` for components that need to be copied
+- Add helper methods via `impl` blocks
+- Use archetypal patterns for common configurations
+
+```rust
+impl BigFive {
+    pub fn temperature(&self) -> f32 {
+        self.extraversion * 500.0 + 20.0
+    }
+
+    pub fn fire() -> Self {
+        Self {
+            openness: 0.8,
+            conscientiousness: -0.7,
+            extraversion: 0.9,
+            agreeableness: -0.5,
+            neuroticism: 0.7,
+        }
+    }
+}
+```
+
+**❌ DON'T:**
+- Put logic in components
+- Store references to other entities directly (use `Entity` IDs)
+- Create deeply nested component hierarchies
+- Use components as function parameters
+
+## Query Patterns
+
+**1. Basic Query**
+```rust
+fn system(query: Query<&ComponentA>) {
+    for component in query.iter() {
+        // Process each entity
+    }
+}
+```
+
+**2. Multi-Component Query**
+```rust
+fn system(query: Query<(&ComponentA, &ComponentB, &mut ComponentC)>) {
+    for (a, b, mut c) in query.iter_mut() {
+        // Read a, b; mutate c
+    }
+}
+```
+
+**3. Optional Components**
+```rust
+fn system(query: Query<(&Name, Option<&BigFive>)>) {
+    for (name, maybe_traits) in query.iter() {
+        if let Some(traits) = maybe_traits {
+            // Has BigFive
+        } else {
+            // Doesn't have BigFive
+        }
+    }
+}
+```
+
+**4. Filtered Query**
+```rust
+fn system(
+    query: Query<(&BigFive, &Name), (With<Player>, Without<NPC>)>
+) {
+    // Only entities that have Player and don't have NPC
+}
+```
+
+**5. Multiple Mutable Access**
+```rust
+fn system(
+    mut query: Query<&mut BigFive>,
+    events: EventReader<CastSpellEvent>,
+) {
+    for event in events.read() {
+        if let Ok([mut source, mut target]) =
+            query.get_many_mut([event.source, event.target])
+        {
+            // Can mutate both at once
+        }
+    }
+}
+```
+
+## Common Design Patterns
+
+### Derivation Pattern
+
+**Problem:** Some properties should be calculated from others.
+
+**Solution:**
+```rust
+// Source of truth
+#[derive(Component)]
+pub struct BigFive {
+    pub extraversion: f32,
+    // ...
+}
+
+impl BigFive {
+    pub fn temperature(&self) -> f32 {
+        self.extraversion * 500.0 + 20.0
+    }
+}
+
+// Cached derived value
+#[derive(Component)]
+pub struct Temperature {
+    pub degrees: f32,
+}
+
+// System to sync
+pub fn derive_temperature(
+    mut query: Query<(&BigFive, &mut Temperature), Changed<BigFive>>,
+) {
+    for (traits, mut temp) in query.iter_mut() {
+        temp.degrees = traits.temperature();
+    }
+}
+```
+
+### State Machine Pattern
+
+**Problem:** Entities need to change behavior based on state.
+
+**Solution:**
+```rust
+#[derive(Component)]
+pub enum NPCState {
+    Idle,
+    Patrolling,
+    Investigating,
+    Attacking,
+}
+
+pub fn npc_behavior(
+    mut query: Query<(&mut Transform, &NPCState)>,
+) {
+    for (mut transform, state) in query.iter_mut() {
+        match state {
+            NPCState::Idle => { /* ... */ }
+            NPCState::Patrolling => { /* ... */ }
+            NPCState::Investigating => { /* ... */ }
+            NPCState::Attacking => { /* ... */ }
+        }
+    }
+}
+```
+
+### Threshold/Trigger Pattern
+
+**Problem:** Need to detect when values cross boundaries.
+
+**Solution:**
+```rust
+pub fn check_thresholds(
+    mut query: Query<(Entity, &BigFive, &Name), Changed<BigFive>>,
+    mut commands: Commands,
+) {
+    for (entity, traits, name) in query.iter() {
+        // Check threshold
+        if traits.extraversion > 0.6 {
+            commands.entity(entity).insert(Burning {
+                intensity: traits.extraversion,
+            });
+            println!("{} IGNITES!", name);
+        }
+
+        // Remove if below threshold
+        if traits.extraversion <= 0.6 {
+            commands.entity(entity).remove::<Burning>();
+        }
+    }
+}
+```
+
+### Event-Driven Pattern
+
+**Problem:** Systems need to communicate without tight coupling.
+
+**Solution:**
+```rust
+// Define event
+#[derive(Event)]
+pub struct SpellCastEvent {
+    pub caster: Entity,
+    pub target: Entity,
+    pub spell_type: SpellType,
+}
+
+// Writer system
+pub fn cast_spell(
+    input: Res<ButtonInput<KeyCode>>,
+    mut events: EventWriter<SpellCastEvent>,
+) {
+    if input.just_pressed(KeyCode::Space) {
+        events.send(SpellCastEvent { /* ... */ });
+    }
+}
+
+// Reader system
+pub fn process_spells(
+    mut events: EventReader<SpellCastEvent>,
+    mut query: Query<&mut BigFive>,
+) {
+    for event in events.read() {
+        // Process spell
+    }
+}
+```
+
+### Initialization Pattern
+
+**Pattern: Initialize derived components**
+```rust
+// Entities spawned with BigFive but missing Temperature/Mass
+pub fn initialize_derived_physics(
+    mut commands: Commands,
+    query: Query<(Entity, &BigFive), (Without<Temperature>, Without<Mass>)>,
+) {
+    for (entity, traits) in query.iter() {
+        commands.entity(entity).insert((
+            Temperature { degrees: traits.temperature() },
+            Mass { kilograms: traits.mass() },
+        ));
+    }
+}
+```

package/.claude/skills/bevy/references/project_structure.md

@@ -0,0 +1,116 @@
+# Bevy Project Structure Reference
+
+## Standard Bevy Layout
+
+```
+src/
+├── main.rs                 # App setup, plugin registration, system scheduling
+├── components/
+│   ├── mod.rs
+│   ├── properties.rs      # Core data components
+│   ├── effects.rs         # State marker components
+│   ├── ui.rs             # UI marker components
+│   └── [domain].rs       # Domain-specific components
+├── systems/
+│   ├── mod.rs
+│   ├── [feature].rs      # Feature systems (one file per major feature)
+│   └── ui/
+│       ├── mod.rs
+│       └── [ui_feature].rs
+├── events.rs              # Game events and messages
+└── resources.rs           # Global resources
+```
+
+## Key Principles
+
+**1. Separation of Concerns**
+- **Components** = Pure data, no logic
+- **Systems** = Pure logic, operate on components
+- **Events** = Communication between systems
+- **Resources** = Global state (use sparingly)
+
+**2. Module Organization**
+```rust
+// Good: Grouped by feature
+src/systems/personality_physics.rs
+src/systems/thresholds.rs
+src/systems/spells.rs
+
+// Bad: Grouped by system type
+src/systems/update_systems.rs
+src/systems/query_systems.rs
+```
+
+**3. Component Files**
+Keep related components together:
+```rust
+// src/components/effects.rs
+#[derive(Component)]
+pub struct Burning { pub intensity: f32 }
+
+#[derive(Component)]
+pub struct Frozen;
+
+#[derive(Component)]
+pub struct Dissolving { pub progress: f32 }
+```
+
+## System Ordering
+
+Systems run in the order they're added. Use comments to make dependencies clear:
+
+```rust
+.add_systems(
+    Update,
+    (
+        // Input processing
+        spell_input,
+
+        // State changes (modifies data)
+        process_spell_casts,
+
+        // Derive properties from state
+        derive_physics_from_personality,
+
+        // Check for threshold crossings
+        threshold_reactions,
+
+        // Visual updates (reads state, updates rendering)
+        visual_threshold_effects,
+        update_temperature_visuals,
+
+        // UI updates (must run last)
+        update_inspect_display,
+        update_hover_tooltip,
+    ),
+)
+```
+
+## Change Detection
+
+Use `Changed<T>` to avoid unnecessary processing:
+
+```rust
+// ✅ GOOD: Only process when BigFive changes
+pub fn threshold_reactions(
+    mut query: Query<(Entity, &BigFive, &Name), Changed<BigFive>>,
+    mut commands: Commands,
+) {
+    for (entity, traits, name) in query.iter() {
+        if traits.extraversion > 0.6 {
+            commands.entity(entity).insert(Burning {
+                intensity: traits.extraversion,
+            });
+            println!("{} IGNITES!", name);
+        }
+    }
+}
+
+// ❌ BAD: Runs every frame for all entities
+pub fn threshold_reactions(
+    mut query: Query<(Entity, &BigFive, &Name)>,
+    mut commands: Commands,
+) {
+    // Wasteful!
+}
+```

package/.claude/skills/bevy/references/ui_development.md

@@ -0,0 +1,147 @@
+# Bevy UI Development Reference
+
+## Bevy UI Hierarchy
+
+Bevy UI uses a flexbox-like layout system:
+
+```rust
+commands
+    .spawn((
+        Node {
+            position_type: PositionType::Absolute,
+            left: Val::Px(10.0),
+            top: Val::Px(10.0),
+            width: Val::Px(300.0),
+            padding: UiRect::all(Val::Px(10.0)),
+            flex_direction: FlexDirection::Column,
+            ..default()
+        },
+        BackgroundColor(Color::srgba(0.1, 0.1, 0.1, 0.9)),
+    ))
+    .with_children(|parent| {
+        parent.spawn((
+            Text::new("Title"),
+            TextFont { font_size: 16.0, ..default() },
+            TextColor(Color::WHITE),
+        ));
+    });
+```
+
+## UI Component Pattern
+
+**1. Marker Components for UI Elements**
+```rust
+#[derive(Component)]
+pub struct SpellBar;
+
+#[derive(Component)]
+pub struct HoverTooltip;
+
+#[derive(Component)]
+pub struct InspectPanel;
+```
+
+**2. Setup System (Startup)**
+```rust
+pub fn setup_ui(mut commands: Commands) {
+    commands.spawn((
+        SpellBar,
+        Node { /* layout */ },
+        BackgroundColor(/* color */),
+    ))
+    .with_children(|parent| {
+        // Child elements
+    });
+}
+```
+
+**3. Update System (Update)**
+```rust
+pub fn update_ui(
+    state: Res<GameState>,
+    mut query: Query<&mut Text, With<SpellBar>>,
+) {
+    for mut text in query.iter_mut() {
+        **text = format!("State: {:?}", state);
+    }
+}
+```
+
+## UI Best Practices
+
+### Layout Tips
+
+- Use `Val::Px()` for fixed sizes
+- Use `Val::Percent()` for responsive layouts
+- Use `flex_direction: FlexDirection::Column` for vertical stacking
+- Use `flex_direction: FlexDirection::Row` for horizontal stacking
+- Use `justify_content` and `align_items` for alignment
+
+### Positioning
+
+**Absolute positioning (HUD elements):**
+```rust
+Node {
+    position_type: PositionType::Absolute,
+    left: Val::Px(10.0),
+    top: Val::Px(10.0),
+    ..default()
+}
+```
+
+**Centered element:**
+```rust
+Node {
+    position_type: PositionType::Absolute,
+    left: Val::Percent(50.0),
+    top: Val::Percent(50.0),
+    margin: UiRect {
+        left: Val::Px(-150.0),  // Half of width
+        top: Val::Px(-100.0),   // Half of height
+        ..default()
+    },
+    width: Val::Px(300.0),
+    height: Val::Px(200.0),
+    ..default()
+}
+```
+
+### Visibility Control
+
+```rust
+// Show/hide with Display
+mut node: Query<&mut Node, With<Panel>>
+
+// Hide
+node.display = Display::None;
+
+// Show
+node.display = Display::Flex;
+```
+
+### Color and Styling
+
+```rust
+// Background
+BackgroundColor(Color::srgba(0.1, 0.1, 0.1, 0.9))
+
+// Border
+BorderColor::all(Color::srgba(0.3, 0.6, 0.9, 1.0))
+
+// Highlight on selection
+*bg_color = BackgroundColor(Color::srgba(0.2, 0.4, 0.6, 1.0));
+*border_color = BorderColor::all(Color::srgba(0.3, 0.6, 0.9, 1.0));
+```
+
+### Text Updates
+
+```rust
+// Update text content
+**text = "New content".to_string();
+
+// Or with formatting
+**text = format!("Value: {:.2}", value);
+
+// Multi-line text
+**text = "Line 1\nLine 2\nLine 3".to_string();
+```