AIBodh

The Impatient Programmer’s Guide to Bevy and Rust: Chapter 7 - Let There Be Enemies

2026-02-02T00:00:00+00:00

By the end of this chapter, you’ll have enemies that follow and attack your player.

Prerequisites: This is Chapter 7 of our Bevy tutorial series. Join our community for updates on new releases. Before starting, complete Chapter 1: Let There Be a Player, Chapter 2: Let There Be a World, Chapter 3: Let The Data Flow, Chapter 4: Let There Be Collisions, Chapter 5: Let There Be Pickups, and Chapter 6: Let There Be Particles, or clone the Chapter 6 code from this repository to follow along.

Before We Begin: I'm constantly working to improve this tutorial and make your learning journey enjoyable. Your feedback matters - share your frustrations, questions, or suggestions on Reddit/Discord/LinkedIn. Loved it? Let me know what worked well for you! Together, we'll make game development with Rust and Bevy more accessible for everyone.

What Makes an Enemy Different from a Player?

Your player character moves, animates, collides with objects, and attacks. Now you want enemies do almost the same things expect for decision making.

Players make decisions through keyboard input. You press ↑, the character walks up. You press Ctrl, they attack. The input system reads your keypresses and sets components like Velocity and CharacterState.

Enemies need to make the same decisions, but automatically. Instead of reading a keyboard, they read the game world. “Where is the player? Am I close enough to attack? Which direction should I face?”

Both players and enemies need to:

Move around the world
Animate based on state
Collide with walls and objects
Attack with magical powers

The only difference is who decides what to do. For players, you decide. For enemies, AI decides. But once the decision is made, the rest is identical. Hence can we re-use the code we have written for player for enemy? Let’s find out.

Thinking in Components

In Bevy’s ECS architecture, entities are just IDs. Components are the data. Systems are the logic. This separation lets us build systems that work on any entity with the right components.

Your player entity has these components:

Player (marker)
Transform (position)
Velocity (movement)
CharacterState (Idle, Walking, etc.)
Facing (direction)
AnimationController (sprite animation)
Collider (physics)

An enemy entity needs most of the same components. The key insight: systems like apply_velocity, validate_movement, and animate_characters don’t care whether an entity is a player or enemy. They just process components.

Creating the Enemy Module

Create a new folder src/enemy with the following structure:

src/
├── enemy/
│   ├── mod.rs
│   ├── components.rs
│   ├── ai.rs
│   ├── combat.rs
│   └── spawn.rs

Enemy Components

We need three components to define enemy behavior. The Enemy marker identifies which entities are enemies. The EnemyCombat component gives them attack capabilities. The AIBehavior component controls their decision-making.

Create src/enemy/components.rs:

// src/enemy/components.rs
use crate::combat::PowerType;
use bevy::prelude::*;

/// Marker component for enemy entities
#[derive(Component)]
pub struct Enemy;

/// Combat capabilities for enemies
#[derive(Component)]
pub struct EnemyCombat {
    pub power_type: PowerType,
    pub cooldown: Timer,
}

impl Default for EnemyCombat {
    fn default() -> Self {
        Self {
            power_type: PowerType::Shadow, // Graveyard reaper uses shadow magic
            cooldown: Timer::from_seconds(2.0, TimerMode::Once), // Slower than player
        }
    }
}

impl EnemyCombat {
    pub fn new(power_type: PowerType, cooldown_seconds: f32) -> Self {
        Self {
            power_type,
            cooldown: Timer::from_seconds(cooldown_seconds, TimerMode::Once),
        }
    }
}

/// AI behavior state for enemies
#[derive(Component)]
pub struct AIBehavior {
    pub attack_range: f32,
    pub detection_range: f32,
}

impl Default for AIBehavior {
    fn default() -> Self {
        Self {
            attack_range: 150.0,    // Stop and attack within this range
            detection_range: 500.0, // Start following player within this range
        }
    }
}

impl AIBehavior {
    pub fn new(attack_range: f32, detection_range: f32) -> Self {
        Self {
            attack_range,
            detection_range,
        }
    }
}

What’s happening here?

The Enemy component is just a marker. It has no data, it just tags entities as enemies so systems can query for them.

EnemyCombat stores the enemy’s attack capabilities. The power_type determines what kind of projectile they fire (Shadow magic for our graveyard reaper). The cooldown timer prevents them from attacking every frame.

AIBehavior defines two ranges. The detection_range is how far away the enemy can “see” the player. The attack_range is how close they need to be before they stop moving and start attacking.

Why use Default?

The Default trait lets us spawn enemies quickly without specifying every field. We can call EnemyCombat::default() to get sensible starting values, then customize specific enemies with EnemyCombat::new() if needed.

Making Enemies Follow You

Now for the interesting part. We need a system that makes enemies track and follow the player.

Simple, move enemies directly toward the player? But what if there’s a tree in the way? The enemy walks into the obstacle and gets stuck.

We need pathfinding, the ability to find a route around obstacles. The industry-standard solution is the A* (“A-star”) algorithm.

Understanding A* Pathfinding

A* is a pathfinding algorithm that finds the shortest path between two points on a grid. It’s used everywhere in games, robotics, GPS navigation because it’s both efficient and guaranteed to find the shortest path.

A* explores the grid by calculating a score for each cell. A cell is a single square in the grid (like a tile in your game world). Cost here refers to how expensive it is to travel somewhere.

g-cost: Actual distance traveled from start to this cell
h-cost: Heuristic - Estimated distance from this cell to goal
f-cost: Total cost - g + h (total estimated cost if we take this path)

The algorithm always explores the cell with the lowest f-cost first. This makes it “greedy” (always picking what looks best) but informed (using the heuristic to guide the search).

A* Pathfinding

The green cell is where the enemy starts, and the red cell is the player’s position. Black obstacles block the way, forcing the algorithm to navigate around them.

As A* explores, it marks cells in light blue (candidates to check next) and pink (already checked and ruled out). The dark blue cell shows what A* is currently examining, and once the path is found, it lights up in yellow.

Notice how the algorithm doesn’t waste time exploring cells that are obviously far from the goal, it intelligently prioritizes the most promising directions!

Adding the Pathfinding Crate

We’ll use the pathfinding crate for the A* algorithm.

Update your Cargo.toml:

[dependencies]
bevy = "0.18"
bevy_procedural_tilemaps = "0.2.0"
bevy_common_assets = { version = "0.15.0-rc.1", features = ["ron"] }
serde = { version = "1.0", features = ["derive"] }
rand = "0.8"
pathfinding = "4.9"  # Add this line

Now that we have the pathfinding algorithm, we need to build the infrastructure to use it. This involves three pieces:

EnemyPath Component: Stores the calculated path and tracks which waypoint the enemy is currently moving toward
CollisionMap Methods: Extends our collision system with pathfinding capabilities
AI System: Uses both to make enemies intelligently navigate to the player

Let’s build each piece step by step.

What are waypoints?

Waypoints are like breadcrumbs along a path. Instead of storing “move 3 units north, then 2 units east,” we store actual positions like [(100, 50), (150, 50), (150, 100)]. The enemy moves toward the first waypoint, and when it gets close enough (16 units), it advances to the next one. This makes pathfinding flexible—waypoints can adapt to any terrain shape.

How Waypoints Work

The enemy (green) follows each waypoint in sequence. When it gets within 16 pixels of the current waypoint, it moves to the next one. Eventually it navigates the path to reach the player (red)!

The EnemyPath Component

So let’s create an EnemyPath component that caches the waypoints, tracks the current position along the path, and manages a recalculation timer.

Update src/enemy/components.rs to add this at the end:

// src/enemy/components.rs
// Add this after the AIBehavior implementation

/// Cached path for enemy navigation
#[derive(Component, Default)]
pub struct EnemyPath {
    /// Waypoints in world coordinates
    pub waypoints: Vec<Vec2>,
    /// Current waypoint index
    pub current_index: usize,
    /// Timer for path recalculation
    pub recalc_timer: f32,
}

impl EnemyPath {
    /// Distance threshold to consider a waypoint reached
    pub const WAYPOINT_THRESHOLD: f32 = 16.0;
    /// How often to recalculate path (seconds)
    pub const RECALC_INTERVAL: f32 = 0.5;
    
    /// Get current waypoint position
    pub fn current_waypoint(&self) -> Option<Vec2> {
        self.waypoints.get(self.current_index).copied()
    }
    
    /// Advance to next waypoint, returns true if path completed
    pub fn advance(&mut self) -> bool {
        self.current_index += 1;
        self.current_index >= self.waypoints.len()
    }
    
    /// Set a new path (skips first waypoint since it's the starting position)
    pub fn set_path(&mut self, waypoints: Vec<Vec2>) {
        // Skip waypoint 0 - it's the enemy's current position
        // This prevents jitter from briefly facing backwards
        let new_waypoints = if waypoints.len() > 1 {
            waypoints[1..].to_vec()
        } else {
            waypoints
        };
        
        // If we have an existing path, check if new path is similar
        // This prevents flickering when paths are recalculated
        if let Some(current_target) = self.current_waypoint() {
            if let Some(new_first) = new_waypoints.first() {
                // If new first waypoint is close to our current target,
                // keep the current path - we're already heading the right way
                if current_target.distance(*new_first) < Self::WAYPOINT_THRESHOLD * 1.5 {
                    return;
                }
            }
        }
        
        self.waypoints = new_waypoints;
        self.current_index = 0;
    }
    
    /// Check if we have a valid path
    pub fn has_path(&self) -> bool {
        !self.waypoints.is_empty() && self.current_index < self.waypoints.len()
    }
}

Let’s break down each piece:

waypoints: Stores the path as a vector of world positions. Once we calculate a path, we cache it here.
current_index: Tracks which waypoint we’re heading toward. When we reach waypoint 0, we increment to waypoint 1, etc.
recalc_timer: Counts down from 0.5 seconds. When it hits zero, we recalculate the path (in case the player moved).
current_waypoint(): Returns the waypoint we’re currently heading toward (or None if we’ve completed the path).
advance(): Moves to the next waypoint, returns true if we’ve completed the entire path.
set_path(): Stores a new path with smart optimizations:
- Skips waypoint 0 (the enemy’s current position) to avoid jitter
- Checks if the new path is similar to the current one - if so, keeps the existing path to reduce flickering
has_path(): Returns true if we have a valid, incomplete path to follow.

Why cache paths?

Running A* every frame would slow down the game. By recalculating every 0.5 seconds, we get smooth movement with minimal performance cost.

Why have a waypoint threshold?

Due to movement speed and frame timing, an enemy might never land exactly on a waypoint. The 16-unit threshold lets us consider it “reached” when close enough.

Now that we can store paths, we need to calculate them. But who does the pathfinding? The CollisionMap!

Why does CollisionMap do pathfinding? Shouldn’t the enemy figure out its own path?

Good question! The CollisionMap already knows which tiles are walkable and which aren’t, it has all the terrain data. Rather than duplicating this knowledge in the enemy AI, we extend CollisionMap with pathfinding methods. This way:

Enemies just ask: “Give me a path to position X”
CollisionMap responds: “Here’s the list of waypoints to get there”

This keeps our code clean and follows the principle: the component with the data provides the operations on that data.

Extending CollisionMap for Pathfinding

Our collision map knows about walkable tiles, but it doesn’t know how to find a path through them. We need to:

Get valid neighboring cells (ensuring diagonal moves don’t cut corners through walls)
Find the nearest walkable tile if the target is blocked
Run A* pathfinding to calculate the optimal path

What does “don’t cut corners” mean?

Imagine two walls meeting at a corner diagonally. Without proper checks, an enemy could move diagonally through that gap, which looks like walking through walls! We prevent this by only allowing diagonal movement when both adjacent cardinal cells are also walkable.

  ┌───┬───┐
  │   │ W │  W = Wall
  ├───┼───┤  
  │ W │   │  Can't cut diagonally!
  └───┴───┘

So let’s add these three methods to CollisionMap that work together to provide intelligent pathfinding.

Open src/collision/map.rs and add these methods at the end of the impl CollisionMap block:

First, add the import at the top of src/collision/map.rs:

// src/collision/map.rs  
use pathfinding::prelude::astar;

Now add these methods at the end of the impl CollisionMap block:

// src/collision/map.rs
// Add at the end of impl CollisionMap, before the closing brace

    /// Get walkable neighboring grid cells (8 directions)
    /// Diagonal movement only allowed if both adjacent cardinals are clear
    pub fn get_neighbors(&self, pos: IVec2) -> Vec<IVec2> {
        let mut neighbors = Vec::new();
        
        // Cardinal directions (always allowed if walkable)
        let cardinals = [
            IVec2::new(0, 1), IVec2::new(0, -1), IVec2::new(-1, 0), IVec2::new(1, 0),
        ];
        
        for dir in cardinals {
            let neighbor = pos + dir;
            if self.is_walkable(neighbor.x, neighbor.y) {
                neighbors.push(neighbor);
            }
        }
        
        // Diagonal directions - only if both adjacent cardinals are clear
        // This prevents corner-cutting through diagonal walls
        let diagonals = [
            (IVec2::new(-1, 1), IVec2::new(-1, 0), IVec2::new(0, 1)),   // Up-Left
            (IVec2::new(1, 1), IVec2::new(1, 0), IVec2::new(0, 1)),     // Up-Right
            (IVec2::new(-1, -1), IVec2::new(-1, 0), IVec2::new(0, -1)), // Down-Left
            (IVec2::new(1, -1), IVec2::new(1, 0), IVec2::new(0, -1)),   // Down-Right
        ];
        
        for (diagonal, adj1, adj2) in diagonals {
            let diag_pos = pos + diagonal;
            let adj1_pos = pos + adj1;
            let adj2_pos = pos + adj2;
            
            // Only allow diagonal if destination AND both adjacent cells are walkable
            if self.is_walkable(diag_pos.x, diag_pos.y)
                && self.is_walkable(adj1_pos.x, adj1_pos.y)
                && self.is_walkable(adj2_pos.x, adj2_pos.y)
            {
                neighbors.push(diag_pos);
            }
        }
        
        neighbors
    }
    
    /// Find path using A* algorithm
    pub fn find_path(&self, start: Vec2, goal: Vec2) -> Option<Vec<Vec2>> {
        use pathfinding::prelude::astar;
        
        let start_grid = self.world_to_grid(start);
        let goal_grid = self.world_to_grid(goal);
        
        if !self.is_walkable(start_grid.x, start_grid.y) {
            return None;
        }
        
        let actual_goal = if self.is_walkable(goal_grid.x, goal_grid.y) {
            goal_grid
        } else {
            self.find_nearest_walkable(goal_grid)?
        };
        
        let result = astar(
            &start_grid,
            |pos| {
                let pos = *pos;
                self.get_neighbors(pos).into_iter().map(move |n| {
                    let cost = if (n.x - pos.x).abs() + (n.y - pos.y).abs() == 2 {
                        14u32 // Diagonal
                    } else {
                        10u32 // Cardinal
                    };
                    (n, cost)
                })
            },
            |pos| {
                let dx = (pos.x - actual_goal.x).abs();
                let dy = (pos.y - actual_goal.y).abs();
                ((dx + dy) * 10) as u32
            },
            |pos| *pos == actual_goal,
        );
        
        result.map(|(path, _cost)| {
            path.into_iter().map(|p| self.grid_to_world(p.x, p.y)).collect()
        })
    }
    
    /// Find nearest walkable cell
    pub fn find_nearest_walkable(&self, pos: IVec2) -> Option<IVec2> {
        for radius in 1i32..10 {
            for dx in -radius..=radius {
                for dy in -radius..=radius {
                    if dx.abs() == radius || dy.abs() == radius {
                        let check = IVec2::new(pos.x + dx, pos.y + dy);
                        if self.is_walkable(check.x, check.y) {
                            return Some(check);
                        }
                    }
                }
            }
        }
        None
    }

    /// Find nearest position where a circle of the given radius is fully clear.
    /// Searches expanding rings up to 20 tiles from the given world position.
    /// Returns a world-space position (tile center) or None if nothing found.
    pub fn find_nearest_clear_position(&self, world_pos: Vec2, radius: f32) -> Option<Vec2> {
        let grid_pos = self.world_to_grid(world_pos);

        for ring in 0i32..20 {
            for dx in -ring..=ring {
                for dy in -ring..=ring {
                    if ring > 0 && dx.abs() != ring && dy.abs() != ring {
                        continue; // Only check the ring perimeter
                    }
                    let candidate_grid = IVec2::new(grid_pos.x + dx, grid_pos.y + dy);
                    let candidate_world = self.grid_to_world(candidate_grid.x, candidate_grid.y);
                    if self.is_circle_clear(candidate_world, radius) {
                        return Some(candidate_world);
                    }
                }
            }
        }
        None
    }

Let’s break down the pathfinding code:

1. Neighbor Detection (get_neighbors):

First checks all 4 cardinal directions (up/down/left/right)
Then checks all 4 diagonal directions only if both adjacent cardinals are walkable
This prevents enemies from “cutting corners” through diagonal walls

2. Nearest Walkable Search (find_nearest_walkable):

Uses a spiral search pattern starting from the target
Checks increasingly larger squares until it finds a walkable tile
Returns None if nothing found within 10 tiles (player might be unreachable)

2b. Nearest Clear Position (find_nearest_clear_position):

Like find_nearest_walkable, but validates the full collider circle at each candidate, not just the tile type
Used for spawning, where we need to guarantee the entity won’t overlap any obstacle after placement
Searches up to 20 tiles and returns a world-space position ready to use

3. A* Pathfinding (find_path):

Converts world positions to grid coordinates
Validates start position; if goal is blocked, finds nearest walkable alternative
Runs A* algorithm using:
- Successors: Get neighbors with movement cost (10 for cardinal, 14 for diagonal)
- Heuristic: Manhattan distance estimate to goal
- Success: Checks if the current position is the goal
Converts resulting grid path back to world coordinates

Understanding the `astar` Function

The A* function doesn’t care if you’re navigating a dungeon, flying a spaceship, or routing a delivery truck, it just needs to know “what positions exist” (nodes) and “how expensive is it to move between them” (costs).

Hence it’s just a generic function that works with any node type N and cost type C. Node in our situation, is a position on the board where the enemy can stand (in our case, grid coordinates like (5, 3))

// Pseudo code, don't use 
pub fn astar<...>(
    start: &N,
    successors: FN,
    heuristic: FH,
    success: FS,
) -> Option<(Vec<N>, C)>

What matters are the four parameters:

start: &N - Enemy’s starting position
successors: FN - A function that answers “where can I move from here?” It helps us know from the enemy’s current tile, which adjacent tiles can it walk to and how much does each move cost?
heuristic: FH - A function that guesses distance to target or “how many tiles away is the player from here?”. It helps enemy prioritize which direction to explore first.
success: FS - A function that checks “are we there yet?”. It returns true when the enemy has reached the player’s position.

The function returns Option<(Vec, C)>:

Some((path, cost)) A list of grid positions the enemy should walk through to reach the player, plus the total cost.
None if no path exists or player is completely blocked off by obstacles, enemy can’t reach them.

Now let’s see how we provide these functions using closures:

Understanding Closures in the A* Implementation:

You might notice the astar function looks a bit odd, it takes closures (anonymous functions) as arguments. This is a powerful Rust pattern called higher-order functions.

// Pseudo code, don't use
let result = astar(
    &start_grid,              // Starting position
    |pos| { /* closure 1 */ },  // How to get neighbors and costs
    |pos| { /* closure 2 */ },  // How to estimate distance to goal
    |pos| { /* closure 3 */ },  // How to check if we reached the goal
);

Why closures? The pathfinding crate’s astar function is generic - it works for ANY type of pathfinding problem (chess moves, graph traversal, tile grids, etc.). By accepting closures, it lets YOU define:

What counts as a “neighbor” (straight lines only? diagonals too? teleportation?)
What the movement costs are (flat terrain? hills?)
How to estimate distance (Manhattan? Euclidean?)
What the goal condition is

How do closures capture data?

Notice that the closures reference self and actual_goal , variables from the outer scope. Rust closures can “capture” these variables:

// Pseudo code don't use
|pos| {
    let pos = *pos;
    self.get_neighbors(pos)  // Uses 'self' from outer scope!
        .into_iter()
        .map(move |n| {
            // Calculate cost based on movement type
            let cost = if (n.x - pos.x).abs() + (n.y - pos.y).abs() == 2 {
                14u32  // Diagonal movement
            } else {
                10u32  // Cardinal movement
            };
            (n, cost)
    })
 }

What’s the move keyword?

In the inner closure (the one with .map(move |n| ...)), the move keyword forces the closure to take ownership of the captured variable pos. Without move, the closure would borrow pos, but since we’re returning this closure from .map(), it needs to own its data. Think of it like: “This closure is leaving home, so it needs to pack its own copy of pos.”

How does borrowing work with self.get_neighbors?

Great question! When the closure captures self, it’s actually borrowing it:

The outer closure borrows self immutably (just reading from it)
self.get_neighbors(pos) only needs to read the collision map data
The astar function promises to only call the closure while we’re in the find_path method
No ownership is transferred, so no borrowing rules are broken!

The borrowing is temporary and safe because:

We’re not trying to modify self (immutable borrow is fine)
The closure only exists during the astar call, not after
Rust’s borrow checker verifies this at compile time

This closure is essentially a custom function that says: “For any position, here’s how to find its neighbors and the cost to reach them.”

The AI System with Pathfinding

Now we can implement AI that uses pathfinding.

We need enemies to intelligently pursue the player by:

Detecting when the player is in range
Using pathfinding to navigate around obstacles
Stopping to attack when close enough
Handling edge cases (player too far, pathfinding fails, etc.)
Preventing jitter and oscillation with smart state transitions

Build an AI system that manages three behavior states (idle, following, attacking) with smooth transitions between them.

Create src/enemy/ai.rs:

// src/enemy/ai.rs
use super::components::{AIBehavior, Enemy, EnemyPath};
use crate::characters::{
    config::CharacterEntry,
    facing::Facing,
    input::Player,
    physics::{Velocity, calculate_velocity},
    state::CharacterState,
};
use crate::collision::CollisionMap;
use bevy::prelude::*;

/// AI system that makes enemies follow the player using A* pathfinding
pub fn enemy_follow_player(
    time: Res<Time>,
    collision_map: Option<Res<CollisionMap>>,
    mut enemy_query: Query<
        (
            &Transform,
            &mut CharacterState,
            &mut Velocity,
            &mut Facing,
            &CharacterEntry,
            &AIBehavior,
            &mut EnemyPath,
        ),
        With<Enemy>,
    >,
    player_query: Query<&Transform, With<Player>>,
) {
    let Ok(player_transform) = player_query.single() else {
        return;
    };
    
    let Some(collision_map) = collision_map else {
        return;
    };

    let player_pos = player_transform.translation.truncate();
    let delta = time.delta_secs();

    for (enemy_transform, mut state, mut velocity, mut facing, character, ai, mut path) in
        enemy_query.iter_mut()
    {
        let enemy_pos = enemy_transform.translation.truncate();
        let to_player = player_pos - enemy_pos;
        let distance = to_player.length();

        // Outside detection range - go idle
        if distance > ai.detection_range {
            if *state != CharacterState::Idle {
                *state = CharacterState::Idle;
            }
            *velocity = Velocity::ZERO;
            continue;
        }

        // Within attack range - stop and attack
        // Use hysteresis: different threshold for staying vs entering attack mode
        // This prevents oscillation at the boundary
        let attack_threshold = if *state == CharacterState::Idle {
            ai.attack_range + 20.0 // Stay in attack mode even if player moves slightly away
        } else {
            ai.attack_range // Enter attack mode at normal range
        };
        
        if distance <= attack_threshold {
            if *state != CharacterState::Idle {
                *state = CharacterState::Idle;
            }
            *velocity = Velocity::ZERO;
            
            // Face the player while attacking
            let direction = to_player.normalize_or_zero();
            if direction != Vec2::ZERO {
                let new_facing = Facing::from_velocity(direction);
                if *facing != new_facing {
                    *facing = new_facing;
                }
            }
            continue;
        }

        // Need to move toward player - use pathfinding
        path.recalc_timer -= delta;
        
        // Recalculate path if we don't have one
        if !path.has_path() {
            if let Some(waypoints) = collision_map.find_path(enemy_pos, player_pos) {
                path.set_path(waypoints);
                path.recalc_timer = EnemyPath::RECALC_INTERVAL;
            }
        } else if path.recalc_timer <= 0.0 {
            // Periodically update existing path  
            path.recalc_timer = EnemyPath::RECALC_INTERVAL;
            
            if let Some(waypoints) = collision_map.find_path(enemy_pos, player_pos) {
                path.set_path(waypoints);
            }
        }

        // Follow current waypoint
        if let Some(waypoint) = path.current_waypoint() {
            let to_waypoint = waypoint - enemy_pos;
            let waypoint_distance = to_waypoint.length();
            
            // Check if we reached the waypoint
            if waypoint_distance < EnemyPath::WAYPOINT_THRESHOLD {
                path.advance();
            }
            
            // Recalculate direction for current waypoint (might have advanced)
            if let Some(current_wp) = path.current_waypoint() {
                let to_waypoint = current_wp - enemy_pos;
                let direction = to_waypoint.normalize_or_zero();
            
            // Update state
            if *state != CharacterState::Walking {
                *state = CharacterState::Walking;
            }
            
            // Update facing
            if direction != Vec2::ZERO {
                let new_facing = Facing::from_velocity(direction);
                if *facing != new_facing {
                    *facing = new_facing;
                }
            }
                
                // Calculate velocity toward waypoint
                *velocity = calculate_velocity(*state, direction, character);
            }
        } else {
            // No path available - fallback to direct movement
            let direction = to_player.normalize_or_zero();
            
            if *state != CharacterState::Walking {
                *state = CharacterState::Walking;
            }
            
            if direction != Vec2::ZERO {
                let new_facing = Facing::from_velocity(direction);
                if *facing != new_facing {
                    *facing = new_facing;
                }
            }
            
            *velocity = calculate_velocity(*state, direction, character);
        }
    }
}

How does this work?

The query fetches all enemies with their path component. We also get the CollisionMap resource and player’s position.

For each enemy, we check three ranges:

Too far (beyond detection range): Go idle
In attack range: Stop moving, face player
Between ranges: Use pathfinding to approach

Attack range hysteresis: We use different thresholds for entering vs staying in attack mode:

Enter attack: distance <= attack_range (150)
Stay attacking: distance <= attack_range + 20 (170)

This prevents oscillation, a buggy behavior where the enemy rapidly flickers between states. Imagine the player is exactly 150 units away (the attack range). The enemy enters attack mode, but as soon as it stops moving, the distance might increase to 151 units, triggering follow mode again. This causes the enemy to jitter back and forth between “attack” and “follow” dozens of times per second! By adding a buffer zone, the enemy must move further away (170 units) before switching back to following.

Path management: We separate path creation from path updates:

No path → Create immediately and reset timer
Have path, timer expired → Update periodically (every 0.5s)

This prevents the path from resetting mid-frame when enemies complete waypoints.

Path similarity check: Before replacing an existing path, we check if the new path’s first waypoint is close to our current target. If so, we keep the existing path since we’re already heading the right direction. This reduces flickering during periodic updates.

Skipping the first waypoint: A* includes the starting position as waypoint 0. If we don’t skip it, enemies briefly face backward (toward their own position) before turning to the actual destination. By skipping waypoint 0 in set_path(), enemies immediately move toward the first real destination.

Waypoint advancement: When we reach a waypoint, we call advance() and immediately recalculate the direction for the NEW current waypoint in the same frame. This prevents jitter from skipping frames between waypoints.

Fallback behavior: If pathfinding fails, we fall back to direct movement. This ensures enemies don’t get completely stuck.

Why check if state changed?

Bevy’s change detection tracks when components are modified. If we set *state = new_state every frame even when the value doesn’t change, Bevy thinks the state changed. This triggers systems that run on Changed, like animation updates. By only updating when the value actually changes, we avoid unnecessary work.

Making Enemies Attack

Enemies can follow the player, but they need to attack. We’ll create a combat system that fires when enemies are in range and their cooldown is ready.

The combat system needs to:

Tick the cooldown timer
Check if the player is in attack range
Fire a projectile when ready
Reset the cooldown

Create src/enemy/combat.rs:

// src/enemy/combat.rs
use super::components::{AIBehavior, Enemy, EnemyCombat};
use crate::characters::input::Player;
use crate::combat::systems::spawn_projectile;
use bevy::prelude::*;

/// System that handles enemy attacks
pub fn enemy_attack(
    mut commands: Commands,
    time: Res<Time>,
    mut enemy_query: Query<(&GlobalTransform, &mut EnemyCombat, &AIBehavior), With<Enemy>>,
    player_query: Query<&Transform, With<Player>>,
) {
    let Ok(player_transform) = player_query.single() else {
        return;
    };

    for (enemy_transform, mut combat, ai) in enemy_query.iter_mut() {
        // Tick the cooldown timer
        combat.cooldown.tick(time.delta());

        let enemy_pos = enemy_transform.translation();
        let player_pos = player_transform.translation;
        
        // Calculate distance to player
        let distance = enemy_pos.distance(player_pos);

        // Attack if in range and cooldown is ready
        if distance <= ai.attack_range && combat.cooldown.elapsed() >= combat.cooldown.duration() {
            // Calculate direction to player
            let to_player = (player_pos - enemy_pos).normalize();
            let spawn_position = enemy_pos + to_player * 5.0;

            // Get visuals from power type (using actual direction to player)
            let visuals = combat.power_type.visuals(to_player);

            // Spawn projectile (reuse existing function!)
            spawn_projectile(&mut commands, spawn_position, combat.power_type, &visuals);

            // Reset cooldown for next attack
            combat.cooldown.reset();

            info!("Enemy fired {:?} projectile at player!", combat.power_type);
        }
    }
}

How does the attack system work?

Every frame, we tick each enemy’s cooldown timer. We check if elapsed() >= duration() to see if the cooldown is ready. This allows enemies to attack immediately when spawned (the timer starts in a finished state) and then every 2 seconds after.

We calculate the actual direction vector from enemy to player using (player_pos - enemy_pos).normalize(). This ensures projectiles always aim at the player’s current position, not just in a cardinal direction.

We check if the player is within attack range. If both conditions are met (cooldown ready AND player in range), we fire a projectile toward the player and reset the cooldown.

The spawn_projectile function is the same one the player uses. We made it public in combat/systems.rs so both players and enemies can call it. This is code reuse at its best.

Fixing Player Spawning

Before we spawn enemies, we need to fix a critical bug in how the player spawn. Right now, the player spawns at (0, 0) during Startup, before the collision map exists. This means the player might spawn on an obstacle (rock, tree, water) and get stuck!

To prevent this, let’s use a validate-then-spawn pattern:

Load character assets → Startup
Wait for collision map → Update (run condition)
Validate position → Check is_circle_clear
Spawn at valid position

This ensures characters never spawn on obstacles.

Let’s update src/characters/spawn.rs. We’ll split the old system into two cleaner functions:

First, add these imports at the top of the file:

// src/characters/spawn.rs
use crate::collision::CollisionMapBuilt; // Add this line
use crate::config::player::COLLIDER_RADIUS; // Add this line
use crate::collision::CollisionMap; // Add this line

Remove these old functions:

//DELETE spawn_player
//DELETE initialize_player_character

Add these new functions:

// src/characters/spawn.rs
// Update the resource name at the top of the file
/// Resource to track if player has been spawned (prevents spawning multiple times)
#[derive(Resource, Default, PartialEq, Eq)]
pub struct PlayerSpawned(pub bool);

/// Get a valid spawn position, checking collision map and adjusting if needed
fn get_valid_spawn_position(collision_map: &CollisionMap, desired_pos: Vec2) -> Vec2 {
    // Use the same radius as the runtime collision system
    if collision_map.is_circle_clear(desired_pos, COLLIDER_RADIUS) {
        return desired_pos;
    }

    // Find nearest position where the full collider circle is clear
    if let Some(clear_pos) = collision_map.find_nearest_clear_position(desired_pos, COLLIDER_RADIUS) {
        info!(
            "Adjusted player spawn from {:?} to {:?} (was on obstacle)",
            desired_pos, clear_pos
        );
        return clear_pos;
    }

    // Fallback to original
    warn!("Could not find walkable spawn position near {:?}", desired_pos);
    desired_pos
}

// Replace spawn_player with this
/// Load character assets at startup (before collision map is built)
pub fn load_character_assets(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
    mut character_index: ResMut<CurrentCharacterIndex>,
) {
    // Load the characters list
    let characters_list_handle: Handle<CharactersList> =
        asset_server.load("characters/characters.ron");

    // Store the handle in a resource
    commands.insert_resource(CharactersListResource {
        handle: characters_list_handle,
    });

    // Initialize with first character
    character_index.index = 0;
    
    info!("Character assets loading started");
}

// Add this new function
/// Spawn player at a valid position AFTER collision map is built
pub fn spawn_player_at_valid_position(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
    characters_lists: Res<Assets<CharactersList>>,
    character_index: Res<CurrentCharacterIndex>,
    characters_list_res: Option<Res<CharactersListResource>>,
    collision_map: Option<Res<CollisionMap>>,
    mut player_spawned: ResMut<PlayerSpawned>,
) {
    // Wait for collision map
    let Some(collision_map) = collision_map else {
        return;
    };
    
    // Wait for character list resource
    let Some(characters_list_res) = characters_list_res else {
        return;
    };
    
    // Get the character list asset
    let Some(characters_list) = characters_lists.get(&characters_list_res.handle) else {
        return;
    };
    
    if character_index.index >= characters_list.characters.len() {
        warn!("Invalid character index: {}", character_index.index);
        return;
    }
    
    let character_entry = &characters_list.characters[character_index.index];
    
    // Calculate valid spawn position
    let desired_pos = Vec2::new(0.0, 0.0);
    let valid_pos = get_valid_spawn_position(&collision_map, desired_pos);
    
    // Create sprite
    let texture = asset_server.load(&character_entry.texture_path);
    let layout = create_character_atlas_layout(&mut atlas_layouts, character_entry);
    let sprite = Sprite::from_atlas_image(texture, TextureAtlas { layout, index: 0 });
    
    // Spawn player with all components at valid position
    commands.spawn((
        Player,
        Transform::from_translation(Vec3::new(valid_pos.x, valid_pos.y, PLAYER_Z_POSITION))
            .with_scale(Vec3::splat(PLAYER_SCALE)),
        sprite,
        AnimationController::default(),
        CharacterState::default(),
        Velocity::default(),
        Facing::default(),
        Collider::default(),
        PlayerCombat::default(),
        AnimationTimer(Timer::from_seconds(
            DEFAULT_ANIMATION_FRAME_TIME,
            TimerMode::Repeating,
        )),
        character_entry.clone(),
    ));
    
    // Mark player as spawned
    player_spawned.0 = true;
    info!("Player spawned at validated position {:?}", valid_pos);
}

What changed?

load_character_assets (Startup) - Only loads the asset, doesn’t spawn anything
spawn_player_at_valid_position (Update) - Waits for collision map, validates position, then spawns with ALL components in one step
get_valid_spawn_position - Shared helper that checks is_circle_clear (not just single tile!)

Notice we use COLLIDER_RADIUS — the same constant the runtime collision system uses. This is important: if spawn validation checks a smaller radius than what the movement system enforces, an entity could pass the spawn check but still overlap an obstacle at runtime and get stuck. Using a single source of truth eliminates that mismatch. The fallback find_nearest_clear_position also validates the full circle, not just the tile type.

Updating the Plugin

Now update src/characters/mod.rs:

// src/characters/mod.rs
// Update imports
use spawn::PlayerSpawned; // Add this line
use crate::collision::CollisionMapBuilt; // Add this line

impl Plugin for CharactersPlugin {
    fn build(&self, app: &mut App) {
        app.add_plugins(RonAssetPlugin::<CharactersList>::new(&["characters.ron"]))
            .init_resource::<spawn::CurrentCharacterIndex>()
            .init_resource::<PlayerSpawned>() // Add this line
            // Load character assets at startup (before collision map)
            .add_systems(Startup, spawn::load_character_assets) // Change function name
            // Spawn player at valid position AFTER collision map is built
            // Add this
            .add_systems(
                Update,
                spawn::spawn_player_at_valid_position 
                    .run_if(resource_equals(CollisionMapBuilt(true)))
                    .run_if(resource_equals(PlayerSpawned(false))) 
                    .run_if(in_state(GameState::Playing)),
            )
            .add_systems(
                Update,
                (
                    input::handle_player_input,
                    spawn::switch_character,
                    input::update_jump_state,
                    animation::on_state_change_update_animation,
                    collider::validate_movement,
                    physics::apply_velocity,
                    rendering::update_player_depth,
                    animation::animations_playback,
                )
                    .chain()
                    .run_if(in_state(GameState::Playing)),
            );
    }
}

And one more fix in src/state/mod.rs - remove the old initialization from OnExit(Loading):

// src/state/mod.rs
.add_systems(OnExit(GameState::Loading), 
    loading::despawn_loading_screen,
    // REMOVE: crate::characters::spawn::initialize_player_character,
)

Adding Enemy Configuration

Now, let’s add configuration constants for enemies in src/config.rs:

// src/config.rs
pub mod player {
    // ... existing player config ...
}

pub mod enemy {
    /// Z-position for enemy rendering (same as player for consistent layering)
    pub const ENEMY_Z_POSITION: f32 = 20.0;

    /// Visual scale of enemy sprites (same as player for consistency)
    pub const ENEMY_SCALE: f32 = 1.2;
} // Add this

pub mod pickup {
    // ... existing pickup config ...
}
// ... rest of config ...

We create a separate enemy module to keep enemy constants organized and avoid confusion with player constants.

Spawning Enemies

Now we need to actually create enemy entities in the world. We’ll write a spawn function that creates an enemy with all the necessary components, then a system that spawns test enemies - using the exact same pattern we just used for the player.

The spawn function needs to:

Load the character configuration from characters.ron
Create the sprite atlas
Spawn an entity with all required components

Create src/enemy/spawn.rs:

// src/enemy/spawn.rs
use super::components::{AIBehavior, Enemy, EnemyCombat, EnemyPath};
use crate::characters::{
    animation::{AnimationController, AnimationTimer, DEFAULT_ANIMATION_FRAME_TIME},
    collider::Collider,
    config::{CharacterEntry, CharactersList},
    facing::Facing,
    physics::Velocity,
    spawn::CharactersListResource, // Add this line
    state::CharacterState,
};
use crate::collision::CollisionMap;
use crate::config::enemy::{ENEMY_SCALE, ENEMY_Z_POSITION};
use crate::config::player::COLLIDER_RADIUS;
use bevy::prelude::*;

/// Spawn an enemy at the given position
pub fn spawn_enemy(
    commands: &mut Commands,
    asset_server: &AssetServer,
    atlas_layouts: &mut ResMut<Assets<TextureAtlasLayout>>,
    characters_list: &CharactersList,
    position: Vec3,
    character_name: &str,
) -> Option<Entity> {
    // Find the character entry by name
    let character_entry = characters_list
        .characters
        .iter()
        .find(|c| c.name == character_name)?;

    // Create atlas layout
    let max_row = character_entry.calculate_max_animation_row();
    let layout = atlas_layouts.add(TextureAtlasLayout::from_grid(
        UVec2::splat(character_entry.tile_size),
        character_entry.atlas_columns as u32,
        (max_row + 1) as u32,
        None,
        None,
    ));

    // Load texture
    let texture = asset_server.load(&character_entry.texture_path);

    // Create sprite
    let sprite = Sprite::from_atlas_image(texture, TextureAtlas { layout, index: 0 });

    // Spawn enemy entity with all necessary components
    let entity = commands
        .spawn((
            Enemy,
            sprite,
            Transform::from_translation(position).with_scale(Vec3::splat(ENEMY_SCALE)),
            GlobalTransform::default(),
            AnimationController::default(),
            CharacterState::default(),
            Velocity::default(),
            Facing::default(),
            Collider::default(),
            EnemyCombat::default(),
            AIBehavior::default(),
            EnemyPath::default(),  // Add this line
            AnimationTimer(Timer::from_seconds(
                DEFAULT_ANIMATION_FRAME_TIME,
                TimerMode::Repeating,
            )),
            character_entry.clone(),
        ))
        .id();

    info!("Spawned enemy '{}' at {:?}", character_name, position);

     Some(entity)
}

/// Resource to track if enemies have been spawned
#[derive(Resource, Default, PartialEq, Eq)]
pub struct EnemiesSpawned(pub bool);

/// Validate and adjust spawn position to ensure it's on a walkable tile
fn get_valid_spawn_position(collision_map: &CollisionMap, desired_pos: Vec2) -> Vec2 {
    // Use the same radius as the runtime collision system
    if collision_map.is_circle_clear(desired_pos, COLLIDER_RADIUS) {
        return desired_pos;
    }

    // Find nearest position where the full collider circle is clear
    if let Some(clear_pos) = collision_map.find_nearest_clear_position(desired_pos, COLLIDER_RADIUS) {
        info!(
            "Adjusted spawn from {:?} to {:?} (was on obstacle)",
            desired_pos, clear_pos
        );
        return clear_pos;
    }

    // Fallback to original (shouldn't happen in a valid map)
    warn!("Could not find walkable spawn position near {:?}", desired_pos);
    desired_pos
}

/// System to spawn test enemies when collision map is ready
pub fn spawn_test_enemies(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
    characters_lists: Res<Assets<CharactersList>>,
    characters_list_res: Option<Res<CharactersListResource>>, // Add this line
    collision_map: Option<Res<CollisionMap>>,
    mut enemies_spawned: ResMut<EnemiesSpawned>,
) {
    // Wait for collision map
    let Some(collision_map) = collision_map else {
        return;
    };

    // Wait for character list resource
    let Some(characters_list_res) = characters_list_res else {
        return;
    };

    // Get the character list asset
    let Some(characters_list) = characters_lists.get(&characters_list_res.handle) else {
        return;
    };

    // Define desired spawn positions
    let spawn_positions = [Vec2::new(200.0, 0.0), Vec2::new(-200.0, 100.0)];

    for desired_pos in spawn_positions {
        // Validate position against collision map
        let valid_pos = get_valid_spawn_position(&collision_map, desired_pos);

        spawn_enemy(
            &mut commands,
            &asset_server,
            &mut atlas_layouts,
            characters_list,
            Vec3::new(valid_pos.x, valid_pos.y, ENEMY_Z_POSITION),
            "graveyard_reaper",
        );
    }

    // Mark enemies as spawned so this system doesn't run again
    enemies_spawned.0 = true;
    info!("Enemies spawned with validated positions");
}

What’s happening in spawn_enemy?

This function follows the same pattern as the player spawn system. Both players and enemies need the same components for movement, animation, and collision.

Both player and enemy spawning now follow the same “validate-then-spawn” approach:

Wait for collision map (run condition: CollisionMapBuilt(true))
Check spawn position (using is_circle_clear with COLLIDER_RADIUS)
Find nearest clear position if blocked (using find_nearest_clear_position, which validates the full collider circle)
Spawn with all components (once valid position is determined)

The key differences between player and enemy entities are:

Marker component: Player vs Enemy
Behavior components: PlayerCombat vs EnemyCombat + AIBehavior
Context-specific: Player gets inventory, enemies get pathfinding

Notice how we reuse CharacterEntry from characters.ron. The “graveyard_reaper” character we defined in Chapter 3 works perfectly for enemies. Same sprite system, same animation definitions, zero duplication.

Why return Option?

The find() call might fail if the character name doesn’t exist in characters.ron. Returning Option lets the caller handle this gracefully. If the character is found, we return Some(entity_id). If not, we return None.

The Enemy Plugin

Now we need to wire everything together into a plugin. The plugin will register all our enemy systems and schedule them to run at the right time.

Create src/enemy/mod.rs:

// src/enemy/mod.rs
pub mod ai;
pub mod combat;
pub mod components;
pub mod spawn;

use crate::collision::CollisionMapBuilt;
use crate::state::GameState;
use bevy::prelude::*;
use spawn::EnemiesSpawned;

pub use components::{AIBehavior, Enemy, EnemyCombat};
pub use spawn::spawn_enemy;

pub struct EnemyPlugin;

impl Plugin for EnemyPlugin {
    fn build(&self, app: &mut App) {
        app
            .init_resource::<EnemiesSpawned>()
            // Spawn enemies AFTER collision map is ready (prevents spawning on obstacles)
            .add_systems(
                Update,
                spawn::spawn_test_enemies
                    .run_if(resource_equals(CollisionMapBuilt(true)))
                    .run_if(resource_equals(EnemiesSpawned(false)))
                    .run_if(in_state(GameState::Playing)),
            )
            // Enemy AI and combat systems
            .add_systems(
                Update,
                (ai::enemy_follow_player, combat::enemy_attack)
                    .chain()
                    .run_if(in_state(GameState::Playing)),
            );
    }
}

How does the plugin work?

We use run conditions to control when spawn_test_enemies executes:

CollisionMapBuilt(true) - collision map must exist before validating spawn positions
EnemiesSpawned(false) - spawns only once (resource tracks spawn state)
in_state(GameState::Playing) - only spawns during actual gameplay

This ensures enemies spawn at validated positions AFTER the collision map is ready, preventing them from spawning on obstacles.

The AI and combat systems run every frame during Playing state. We chain them together so AI runs first (updating positions), then combat runs (firing projectiles).

Also, our enemy combat system needs to call spawn_projectile, but it’s currently private to the combat module. We need to make two changes: make the systems module public, and export the spawn_projectile function.

Open src/combat/mod.rs and update it:

// src/combat/mod.rs
mod player_combat;
mod power_type;
pub mod systems; // Line update alert: Make module public

pub use player_combat::PlayerCombat;
pub use power_type::{PowerType, PowerVisuals};
pub use systems::{debug_switch_power, handle_power_input, spawn_projectile}; // Line update alert: Export spawn_projectile

Then open src/combat/systems.rs and make the spawn_projectile function public:

// src/combat/systems.rs
// Find this function and add 'pub' keyword
pub fn spawn_projectile( // Line update alert: Add 'pub' keyword
    commands: &mut Commands,
    position: Vec3,
    power_type: PowerType,
    visuals: &PowerVisuals,
) {
    // ... rest of the function
}

Now both players and enemies can call spawn_projectile from outside the combat module.

Fixing Enemy Depth Sorting

There’s one more issue to address. Remember in Chapter 5 when we implemented depth sorting for the player? The player’s Z position updates based on Y position, so they render correctly behind or in front of objects.

Enemies need the same treatment. Right now, they spawn with a static Z position and never update. This means an enemy standing at the bottom of the screen (low Y) might render behind a tree at the top of the screen (high Y), which looks wrong.

The good news? We already have the depth sorting logic. We just need to make it work for all characters, not just the player.

Open src/characters/rendering.rs and update it:

// src/characters/rendering.rs
use bevy::prelude::*;

use crate::characters::state::CharacterState; // Line update alert: Change from Player to CharacterState
use crate::config::map::{GRID_Y, TILE_SIZE};
use crate::config::player::PLAYER_SCALE;

/// Z-depth constants for proper layering.
/// The tilemap uses `with_z_offset_from_y(true)` which assigns Z based on Y position.
/// We need to match this formula for all characters (player and enemies). // Line update alert
const NODE_SIZE_Z: f32 = 1.0;  // Same as tilemap generator
const CHARACTER_BASE_Z: f32 = 4.0;  // Match props layer Z range // Line update alert
const CHARACTER_Z_OFFSET: f32 = 0.5;  // Small offset to stay above ground props // Line update alert

pub fn update_character_depth( // Line update alert: Renamed from update_player_depth
    //Updated from PlayerState to CharacterState
    mut character_query: Query<&mut Transform, (With<CharacterState>, Changed<Transform>)>, 
) {
    // Map dimensions for normalization
    let map_height = TILE_SIZE * GRID_Y as f32;
    let map_y0 = -TILE_SIZE * GRID_Y as f32 / 2.0;  // Map origin Y (centered)
    
    // Character sprite height for feet position calculation // Line update alert
    let character_sprite_height = 64.0 * PLAYER_SCALE; // Line update alert

    for mut transform in character_query.iter_mut() { // Line update alert
        let character_center_y = transform.translation.y; // Line update alert

        // Use character's FEET position for depth sorting (not center) // Line update alert
        let character_feet_y = character_center_y - (character_sprite_height / 2.0); // Line update alert

        // Normalize feet Y to [0, 1] across the grid height
        let t = ((character_feet_y - map_y0) / map_height).clamp(0.0, 1.0); // Line update alert

        // Y-to-Z formula:
        // Lower Y (bottom of screen) = higher t = lower Z offset = rendered in front
        // Higher Y (top of screen) = lower t = higher Z offset = rendered behind
        let character_z = CHARACTER_BASE_Z + NODE_SIZE_Z * (1.0 - t) + CHARACTER_Z_OFFSET; // Line update alert

        transform.translation.z = character_z; // Line update alert
    }
}

What changed?

We changed the query from With to With. Since both players and enemies have the CharacterState component, this system now runs for all characters.

We also renamed the function and variables to reflect that it’s no longer player-specific.

Now update src/characters/mod.rs to use the new function name:

// src/characters/mod.rs
// Find the Update systems and update this line:
.add_systems(Update, (
    input::handle_player_input,
    spawn::switch_character,
    input::update_jump_state,
    animation::on_state_change_update_animation,
    collider::validate_movement,
    physics::apply_velocity,
    rendering::update_character_depth, // Line update alert: Renamed
    animation::animations_playback,
).chain().run_if(in_state(GameState::Playing)));

Why does this work?

Both players and enemies have the CharacterState component. By querying for With instead of With, the depth sorting system automatically applies to all character entities.

The system uses Changed to only recalculate Z-depth when entities move, keeping it efficient.

Preventing Entity Stacking

We have one more collision problem to solve. Right now, the validate_movement system only checks against the collision map (tiles and obstacles). It doesn’t check against other entities. This means:

Enemies can stack on top of each other
Enemies pass right through the player

We need entity-to-entity collision detection.

The Approach:

After validating against the collision map, we’ll check each entity against all other entities. If two entities overlap (their collision circles intersect), we push them apart.

Open src/characters/collider.rs and add this new system at the end:

// src/characters/collider.rs
// Add at the end of the file

/// Resolve collisions between entities (player and enemies)
/// Prevents entities from moving into each other
pub fn resolve_entity_collisions(
    mut query: Query<(Entity, &Transform, &mut Velocity, &Collider)>,
) {
    // Collect all entity positions first to avoid multiple mutable borrows
    let entities: Vec<_> = query
        .iter()
        .map(|(e, t, _, c)| (e, c.world_position(t), c.radius))
        .collect();

    // Check each entity against all others
    for (entity, transform, mut velocity, collider) in query.iter_mut() {
        // Skip if not moving
        if !velocity.is_moving() {
            continue;
        }

        let pos = collider.world_position(transform);
        let radius = collider.radius;

        for &(other_entity, other_pos, other_radius) in &entities {
            // Skip self
            if entity == other_entity {
                continue;
            }

            let delta = other_pos - pos;
            let distance = delta.length();
            let min_distance = radius + other_radius;

            // Check if entities are overlapping or very close
            if distance < min_distance * 1.1 {
                // Calculate the direction toward the other entity
                if distance > 0.01 {
                    let direction = delta / distance;
                    
                    // Project velocity onto the direction toward the other entity
                    let velocity_toward = velocity.0.dot(direction);
                    
                    // If moving toward the other entity, block that movement
                    if velocity_toward > 0.0 {
                        // Remove the component of velocity moving toward the other entity
                        velocity.0 -= direction * velocity_toward;
                    }
                }
            }
        }
    }
}

How does this work?

This uses vector projection to block movement toward other entities:

Collect positions first - Store all entity positions to avoid borrowing issues
Skip stationary entities - Only check moving entities
Check proximity - If entities are within 1.1 * (radius1 + radius2), they’re close enough to block
Project velocity - Use dot product to find how much velocity points toward the other entity
Remove that component - Subtract the “toward” velocity, leaving only tangential movement

Why vector projection?

Instead of pushing entities apart (which feels jarring), we let them slide past each other. If an enemy walks toward the player, the component of velocity moving directly toward the player is removed, but sideways velocity remains. This creates smooth “sliding” collisions.

Example:

Enemy moving diagonally toward player: ↗
After blocking: Enemy slides sideways past player: →

This feels natural and prevents the jittery pushback effect.

Why modify velocity instead of directly moving entities?

Modifying velocity keeps physics consistent. The pushback force is applied as acceleration, then apply_velocity moves the entity. This ensures collision response feels smooth and natural.

Now add this system to the chain in src/characters/mod.rs:

// src/characters/mod.rs
.add_systems(
    Update,
    (
        input::handle_player_input,
        spawn::switch_character,
        input::update_jump_state,
        animation::on_state_change_update_animation,
        collider::validate_movement,
        collider::resolve_entity_collisions, // NEW: Prevent entity stacking
        physics::apply_velocity,
        rendering::update_character_depth,
        animation::animations_playback,
    )
        .chain()
        .run_if(in_state(GameState::Playing)),
)

System order matters:

validate_movement    → Check vs tiles/obstacles
resolve_entity_collisions  → Check vs other entities  
apply_velocity       → Actually move the character

Both collision checks happen BEFORE movement is applied. This prevents entities from getting stuck inside obstacles or each other.

Integrating the Enemy Module

Finally, let’s add the enemy module to our game. Open src/main.rs and add the module declaration and plugin:

// src/main.rs
mod camera;
mod characters;
mod collision;
mod combat;
mod config;
mod enemy; // Add this line
mod inventory;
mod map;
mod particles;
mod state;

Then add the plugin to your app:

// Inside main function of src/main.rs
fn main() {
    App::new()
        // ... existing plugins ...
        .add_plugins(combat::CombatPlugin)
        .add_plugins(enemy::EnemyPlugin) // Add this line
        .add_plugins(inventory::InventoryPlugin)
        // ... rest of the code ...
        .run();
}

Run your game:

cargo run

You might notice enemies don't actually deal damage yet. In Chapter 8, we'll add health, damage, and death. Enemies will become threatening, and your survival will depend on dodging their attacks.

Optimizing Debug Builds

Community Tip: This optimization was pointed out by one of our community members, thank you for helping make this tutorial better!

Bevy’s default debug configuration can lead to performance issues, scenes that should run smoothly might drop to unplayable framerates, or large assets might take minutes to load.

The Bevy team documents this issue and provides a solution.

Add these optimizations to your Cargo.toml:

# At the bottom of your Cargo.toml

# Enable a small amount of optimization in the dev profile
[profile.dev]
opt-level = 1

# Enable a large amount of optimization in the dev profile for dependencies
[profile.dev.package."*"]
opt-level = 3

What does this do?

opt-level = 1 for your code: Applies minimal optimization to your own code, keeping compile times fast while improving runtime performance
opt-level = 3 for dependencies: Heavily optimizes Bevy and other dependencies (which rarely change), dramatically improving framerate

The trade-off:

Your first build after adding this will take longer (dependencies need to recompile with optimizations). But subsequent builds remain fast since dependencies are cached. You get much better debug performance without sacrificing development speed!

The Impatient Programmer’s Guide to Bevy and Rust: Chapter 6 - Let There Be Particles

2026-01-22T00:00:00+00:00

By the end of this chapter, you’ll have built a particle system that brings magical powers to life. You’ll create four unique effects (Fire, Arcane, Shadow, and Poison), each with glowing particles that move, rotate, and fade. You’ll learn how to create particle emitters, write a custom shader for glowing effects, and use additive blending to make particles that feel magical.

Prerequisites: This is Chapter 6 of our Bevy tutorial series. Join our community for updates on new releases. Before starting, complete Chapter 1: Let There Be a Player, Chapter 2: Let There Be a World, Chapter 3: Let The Data Flow, Chapter 4: Let There Be Collisions, and Chapter 5: Let There Be Pickups, or clone the Chapter 5 code from this repository to follow along.

Let’s Give Your Players Magic Powers

By the end of this chapter, you’ll learn:

How to spawn and update thousands of particles efficiently
Add variance for organic, natural looking effects
Custom shaders with additive blending for that magical glow
Building a flexible system that’s easy to extend
Give your player magical powers

Understanding Particle Systems

A particle system spawns many small sprites that each:

Spawn from an emitter with initial properties (position, velocity, color, size)
Live for a short time, moving and changing
Die when their lifetime expires

The magic is in the numbers: spawn enough particles with slight variations, and they combine to create complex, beautiful effects.

Building the Particle System

Each particle needs to be independent—moving, rotating, fading, and shrinking on its own. To achieve this, we need two types of properties: physics (how it moves) and visuals (how it looks). The physics properties like velocity, acceleration, and angular velocitygive particles realistic motion.

Physics + Visual Properties in Action

Watch particles move (velocity), rotate (angular velocity), shrink (scale curve), and fade (color curve)

Particles shouldn’t live forever. A fire particle needs to burn out, a magic spell needs to fade away. But particles also need smooth animations as they age, they should gradually fade, shrink, and change color over time, not just blink out of existence.

To make this happen, particles need to track two things: when to die and how far along they are in their life. That’s why we use a countdown timer paired with progress tracking.

A countdown timer (lifetime) tells us when to delete the particle, but not its progress value. A particle with 0.5s left could be 25% done (started at 2.0s) or 99% done (started at 0.51s).

We need both values:

lifetime - time remaining
max_lifetime - original duration

Then: progress = 1.0 - (lifetime / max_lifetime)

Now we know exactly where the particle is: 0% at birth, 50% at midpoint, 100% at death. This progress value drives all animations like color, size, opacity. Without both values, particles just blink on/off. With both, they transition smoothly.

Lifetime vs Progress

Watch two particles with different max_lifetimes die at different times

Particle Components

Now that we understand what properties particles need, let’s create these variables for our particle system. We’ll bundle them into a Particle component that tracks everything from physics to visuals.

Create particles folder inside src and add src/particles/components.rs:

// src/particles/components.rs
use bevy::prelude::*;

/// A single particle in the particle system
#[derive(Component, Clone)]
pub struct Particle {
    pub velocity: Vec3,           // Movement speed and direction (units/sec)
    pub lifetime: f32,             // Remaining time before death (seconds)
    pub max_lifetime: f32,         // Original lifetime for progress calculation
    pub scale: f32,                // Current size multiplier
    pub angular_velocity: f32,     // Rotation speed (radians/sec)
    pub acceleration: Vec3,        // Forces like gravity (units/sec²)
    // Color curve support (start → mid → end)
    pub start_color: Color,        // Color at birth (0% lifetime)
    pub mid_color: Color,          // Color at midpoint (50% lifetime)
    pub end_color: Color,          // Color at death (100% lifetime)
    // Scale curve support
    pub start_scale: f32,          // Size at birth
    pub end_scale: f32,            // Size at death (usually smaller)
}

Why three colors?

We animate color over the particle’s lifetime using a curve:

Start (bright) → Mid (dimmer) → End (fade to black)

This creates smooth transitions. A simple blend between two colors looks linear and boring. Three control points give us more expressive fading.

Particle Color Curve

Watch how a Shadow particle smoothly transitions through three color keyframes

The Particle struct holds all the data, but we need methods to:

Create particles easily - A constructor that sets sensible defaults
Customize particles - Builder methods to override specific properties
Calculate animations - Methods that compute current color and scale based on lifetime progress

Without these methods, every system that renders particles would need to duplicate this logic. By centralizing it here, we ensure consistency and make the code easier to maintain.

Let’s implement the particle methods:

// Append to src/particles/components.rs

impl Particle {
    pub fn new(velocity: Vec3, lifetime: f32, scale: f32, start_color: Color) -> Self {
        Self {
            velocity,
            lifetime,
            max_lifetime: lifetime,
            scale,
            angular_velocity: 0.0,
            acceleration: Vec3::ZERO,
            start_color,
            mid_color: start_color,  // Default to same color
            end_color: start_color,
            start_scale: scale,
            end_scale: scale * 0.5,  // Default: shrink to half
        }
    }

    pub fn with_angular_velocity(mut self, angular_velocity: f32) -> Self {
        self.angular_velocity = angular_velocity;
        self
    }

    pub fn with_acceleration(mut self, acceleration: Vec3) -> Self {
        self.acceleration = acceleration;
        self
    }

    /// Set color curve for smooth color transitions
    pub fn with_color_curve(mut self, mid: Color, end: Color) -> Self {
        self.mid_color = mid;
        self.end_color = end;
        self
    }

    /// Set scale curve
    pub fn with_scale_curve(mut self, end_scale: f32) -> Self {
        self.end_scale = end_scale;
        self
    }

    /// Returns the normalized lifetime progress (0.0 to 1.0)
    pub fn progress(&self) -> f32 {
        1.0 - (self.lifetime / self.max_lifetime)
    }
    
    /// Get interpolated color based on lifetime progress
    pub fn current_color(&self) -> Color {
        let progress = self.progress();
        
        if progress < 0.5 {
            // First half: start → mid
            let t = progress * 2.0;  // Remap 0.0-0.5 to 0.0-1.0
            self.start_color.mix(&self.mid_color, t)
        } else {
            // Second half: mid → end
            let t = (progress - 0.5) * 2.0;  // Remap 0.5-1.0 to 0.0-1.0
            self.mid_color.mix(&self.end_color, t)
        }
    }
    
    /// Get interpolated scale based on lifetime progress
    pub fn current_scale(&self) -> f32 {
        let progress = self.progress();
        self.start_scale.lerp(self.end_scale, progress)
    }
}

The Builder Pattern

Methods like with_angular_velocity() and with_color_curve() use the builder pattern, a Rust idiom for constructing complex objects step-by-step. Each method:

Takes self (ownership of the particle)
Modifies one field
Returns self back

This lets us chain calls together:

// Pseudo code, don't use
Particle::new(velocity, 1.0, 2.0, Color::RED)
    .with_angular_velocity(3.14)
    .with_color_curve(Color::ORANGE, Color::BLACK)
    .with_scale_curve(0.1)

Clean, readable, and flexible. You only specify what you need to customize, everything else uses defaults from new().

The Calculation Methods

Methods like progress(), current_color(), and current_scale() are where the magic happens. They compute values based on the particle’s current state:

progress() - Converts remaining lifetime into a 0.0-1.0 percentage, so we know exactly where the particle is in its life cycle (just born at 0%, halfway through at 50%, about to die at 100%)
current_color() - Blends smoothly between the three colors based on progress, creating that magical fade effect where fire particles glow bright orange then dim to black, or poison clouds shift from sickly green to dark purple
current_scale() - Gradually shrinks the particle from full size to tiny as it ages, making effects feel more dynamic and preventing particles from just blinking out of existence

The current_color() method:

First, it calls progress() to get a value between 0.0 (particle just spawned) and 1.0 (particle about to die)
Then it splits the lifetime into two halves:
- First half (0% to 50%): Blends from start_color to mid_color
- Second half (50% to 100%): Blends from mid_color to end_color

What’s .mix()?

Bevy’s color interpolation method. color1.mix(&color2, 0.5) gives you 50% between the two colors.

Why the * 2.0?
The mix() function needs input from 0.0 to 1.0 to do a complete blend. During the first half of life, progress only reaches 0.5. That’s not enough, it would only blend halfway. Multiplying by 2 makes progress reach 1.0 by the halfway point, giving mix() the full range it needs.

The current_scale() method:

You know how good particle effects don’t just blink out,they shrink and fade away naturally? That’s what current_scale() creates. To achieve this, we gradually reduce the particle’s size from its starting size to a tiny ending size based on how much of its life has passed.

For example, imagine a particle that starts at size 2.0 and should end at 0.5:

At 0% progress: size is 2.0 (full size, just spawned)
At 50% progress: size is 1.25 (halfway between)
At 100% progress: size is 0.5 (tiny, about to disappear)

The particle smoothly shrinks over time, creating that satisfying dissipation effect.

Particle Emitter

Now we need something to actually create particles. That’s the job of the ParticleEmitter component. Think of it as a particle factory attached to an entity (like your player character).

The emitter needs to track:

When to spawn - A timer that ticks down and triggers particle creation
How many to spawn - Burst size (e.g., 5 particles at once)
What kind to spawn - The template for creating particles
Whether it’s active - Can be turned on/off
One-shot vs continuous - Fire once or keep firing

Here’s the emitter component:

// Append to src/particles/components.rs

/// Configuration for a particle emitter
#[derive(Component, Clone)]
pub struct ParticleEmitter {
    pub spawn_timer: Timer,
    pub particles_per_spawn: u32,
    pub particle_config: ParticleConfig,
    pub active: bool,
    pub one_shot: bool,
    pub has_spawned: bool,
}

impl ParticleEmitter {
    pub fn new(spawn_rate: f32, particles_per_spawn: u32, particle_config: ParticleConfig) -> Self {
        Self {
            spawn_timer: Timer::from_seconds(spawn_rate, TimerMode::Repeating),
            particles_per_spawn,
            particle_config,
            active: true,
            one_shot: false,
            has_spawned: false,
        }
    }

    pub fn one_shot(mut self) -> Self {
        self.one_shot = true;
        self
    }
}

How does one_shot work?

Without one_shot, the emitter keeps spawning particles forever (or until you manually set active = false). This is perfect for continuous effects like a torch flame or a magic aura.

With one_shot = true, the emitter spawns particles once and then automatically deactivates. This is ideal for one-time effects like a spell cast or an explosion—you don’t want those repeating every frame!

Particle Configuration

The ParticleConfig struct is the DNA for creating particles. It defines all the properties each particle should have, but with a twist: variance.

Variance

Without variance (left) vs with variance (right) - see the difference!

Without variance, every particle would be identical (boring!). With variance, each particle gets slightly randomized values, creating organic, natural looking effects. For each property, we store:

Base value - The target value (e.g., lifetime: 1.0 seconds)
Variance - How much to randomize it (e.g., lifetime_variance: 0.2 means ±0.2 seconds)

So a particle might live for 0.8 seconds, another for 1.1 seconds, another for 0.95 seconds, all slightly different, making the effect feel alive.

Now let’s create the struct that holds all particle properties. This ParticleConfig serves as a template that particle emitters use to spawn new particles. Instead of hardcoding values, we define them once in a config and reuse it.

Here’s the configuration struct:

// Append to src/particles/components.rs

/// Configuration for spawning particles
#[derive(Clone)]
pub struct ParticleConfig {
    pub lifetime: f32,
    pub lifetime_variance: f32,
    pub speed: f32,
    pub speed_variance: f32,
    pub direction: Vec3,
    pub direction_variance: f32,  // In radians
    pub scale: f32,
    pub scale_variance: f32,
    pub color: Color,
    pub angular_velocity: f32,
    pub angular_velocity_variance: f32,
    pub acceleration: Vec3,
    pub emission_shape: EmissionShape,
}

impl Default for ParticleConfig {
    fn default() -> Self {
        Self {
            lifetime: 1.0,
            lifetime_variance: 0.1,
            speed: 100.0,
            speed_variance: 10.0,
            direction: Vec3::X,
            direction_variance: 0.1,
            scale: 1.0,
            scale_variance: 0.1,
            color: Color::WHITE,
            angular_velocity: 0.0,
            angular_velocity_variance: 0.0,
            acceleration: Vec3::ZERO,
            emission_shape: EmissionShape::Point,
        }
    }
}

#[derive(Clone)]
pub enum EmissionShape {
    Point,
    Circle { radius: f32 },
    Cone { angle: f32 },
}

Understanding the config attributes:

lifetime / lifetime_variance - How long particles exist (seconds)
speed / speed_variance - Initial velocity magnitude
direction / direction_variance - Which way particles fly (direction_variance in radians creates spread)
scale / scale_variance - Size of particles
color - Base particle tint (can be HDR values above 1.0)
angular_velocity / angular_velocity_variance - How fast particles spin
acceleration - Constant force applied (like gravity or wind)
emission_shape - Where particles spawn (Point, Circle, or Cone)

Particle System Updates

So far we’ve defined the data structures, what particles and emitters are. Now we need the systems, the code that actually does things every frame.

We need two key behaviors:

Spawn particles - Check each emitter’s timer, and when it fires, create new particle entities
Update particles - Move them, rotate them, fade their colors, shrink their size, and delete them when they die

Without these systems, our components would just sit there doing nothing. Let’s start with the spawning system. Create src/particles/systems.rs:

To spawn particles, we need two functions working together:

update_emitters - Runs every frame, checks each emitter’s timer, and when the timer fires, triggers particle creation
spawn_particle - A helper function that creates a single particle entity with randomized properties

// src/particles/systems.rs
use super::components::*;
use super::material::ParticleMaterial;
use bevy::prelude::*;
use rand::Rng;

/// System to update particle emitters and spawn new particles
pub fn update_emitters(
    mut commands: Commands,
    time: Res<Time>,
    mut emitters: Query<(Entity, &mut ParticleEmitter, &GlobalTransform)>,
    mut meshes: ResMut<Assets<Mesh>>,
    mut materials: ResMut<Assets<ParticleMaterial>>,
) {
    let mut rng = rand::thread_rng();

    for (entity, mut emitter, global_transform) in emitters.iter_mut() {
        if !emitter.active {
            continue;
        }

        // Handle one-shot emitters
        if emitter.one_shot && emitter.has_spawned {
            emitter.active = false;
            continue;
        }

        emitter.spawn_timer.tick(time.delta());

        if emitter.spawn_timer.just_finished() {
            emitter.has_spawned = true;

            // Spawn particles
            for i in 0..emitter.particles_per_spawn {
                spawn_particle(
                    &mut commands,
                    &emitter.particle_config,
                    global_transform,
                    &mut rng,
                    &mut meshes,
                    &mut materials,
                    Some(entity),
                    i,
                );
            }

            if emitter.one_shot {
                emitter.active = false;
            }
        }
    }
}

How update_emitters Works

This system runs every frame and manages all particle emitters in the game. Here’s the flow:

Setup - Create a random number generator (we’ll need it for variance)
Loop through all emitters - The Query gives us every entity with a ParticleEmitter component
Skip inactive emitters - If active is false, don’t spawn anything
Handle one-shot logic - If it’s a one-shot emitter that already spawned, deactivate it
Tick the timer - Advance the spawn timer by the frame’s delta time
Check if timer finished - When the timer completes, it’s time to spawn!
Spawn a burst - Create particles_per_spawn particles using the spawn_particle helper
Deactivate one-shots - If it’s a one-shot emitter, turn it off after spawning

Emitters don’t spawn particles every frame, they use a timer to control the spawn rate. A timer of 0.1 seconds means 10 bursts per second.

What’s rand::thread_rng()?

Creates a random number generator for this thread. We use it to add variance to particle properties, each particle gets slightly different lifetime, speed, direction, etc.

Now the particle spawning function:

update_emitters handles the emitter’s timer and decides when to spawn particles. But it delegates the actual particle creation to a helper function called spawn_particle. This function takes the emitter’s configuration and creates a single particle entity with randomized properties (lifetime, speed, direction, etc.), a visual mesh, and all the necessary Bevy components.

// Append to src/particles/systems.rs

/// Helper function to spawn a single particle
pub fn spawn_particle(
    commands: &mut Commands,
    config: &ParticleConfig,
    global_transform: &GlobalTransform,
    rng: &mut rand::rngs::ThreadRng,
    meshes: &mut ResMut<Assets<Mesh>>,
    materials: &mut ResMut<Assets<ParticleMaterial>>,
    owner: Option<Entity>,
    _particle_index: u32,
) {
    // Calculate randomized values
    let lifetime =
        config.lifetime + rng.gen_range(-config.lifetime_variance..config.lifetime_variance);
    let speed = config.speed + rng.gen_range(-config.speed_variance..config.speed_variance);
    let scale = config.scale + rng.gen_range(-config.scale_variance..config.scale_variance);
    let angular_velocity = config.angular_velocity
        + rng.gen_range(-config.angular_velocity_variance..config.angular_velocity_variance);

    // Calculate direction with variance
    let base_direction = config.direction.normalize_or_zero();
    let direction = if config.direction_variance > 0.0 {
        apply_direction_variance(base_direction, config.direction_variance, rng)
    } else {
        base_direction
    };

    // Calculate emission offset based on shape
    let emission_offset = match config.emission_shape {
        EmissionShape::Point => Vec3::ZERO,
        EmissionShape::Circle { radius } => {
            let angle = rng.gen_range(0.0..std::f32::consts::TAU);
            let distance = rng.gen_range(0.0..radius);
            Vec3::new(angle.cos() * distance, angle.sin() * distance, 0.0)
        }
        EmissionShape::Cone { angle } => {
            let cone_angle = rng.gen_range(-angle..angle);
            let rotated = rotate_vector_2d(base_direction, cone_angle);
            rotated * rng.gen_range(0.0..1.0)
        }
    };

    let velocity = direction * speed;

    // Get position directly from GlobalTransform
    let emitter_position = global_transform.translation();
    let mut position = emitter_position + emission_offset;

    // Ensure particles are at a visible Z layer (above player)
    position.z = 25.0;

    // Create particle with color curves
    let start_color = config.color;
    // Create color curve: bright → slightly dimmer → fade to black
    let mid_color = {
        let linear = config.color.to_linear();
        Color::LinearRgba(LinearRgba::new(
            linear.red * 0.7,
            linear.green * 0.7,
            linear.blue * 0.7,
            linear.alpha,
        ))
    };
    let end_color = Color::srgba(
        config.color.to_linear().red * 0.3,
        config.color.to_linear().green * 0.3,
        config.color.to_linear().blue * 0.3,
        0.0,
    ); // Fading to black

    let particle = Particle::new(velocity, lifetime, scale, start_color)
        .with_angular_velocity(angular_velocity)
        .with_acceleration(config.acceleration)
        .with_color_curve(mid_color, end_color)
        .with_scale_curve(scale * 0.2); // Shrink to 20%

    // Create a mesh for the particle
    let size = 24.0 * scale;
    let mesh = meshes.add(Rectangle::new(size, size));
    let material = materials.add(ParticleMaterial::new(start_color));

    commands.spawn((
        particle,
        Mesh2d(mesh),
        MeshMaterial2d(material),
        Transform::from_translation(position),
    ));
}

How spawn_particle Works

This function creates a single particle entity with randomized properties.

Step 1: Add randomness to basic properties

We don’t want every particle to be identical, it won’t look natural
Take the base values (how long it lives, how fast it moves, how big it is, how fast it spins)
Add a random amount within the variance range
Now each particle is unique!

Step 2: Randomize the direction

Particles shouldn’t all fly in exactly the same direction
Start with the base direction (e.g., “fly to the right”)
If there’s direction variance, randomly rotate it a bit, otherwise keep it straight

Step 3: Pick a spawn position within the emitter’s shape

Point: all particles spawn at the exact same spot (like a laser beam origin)
Circle: particles spawn randomly within a circular area (like a campfire)
Cone: particles spawn in a cone shape (like a flamethrower)

Step 4: Figure out where the particle starts

Combine direction and speed to get velocity (how it moves each frame)
Start at the emitter’s position in the world
Add the shape offset from Step 3
Put it at Z = 25.0 so it appears above the player

Step 5: Set up the color fade animation

Particles should fade out as they die, not just disappear
Start: full brightness (the color you configured)
Middle: 70% brightness (getting dimmer)
End: 30% brightness and transparent (fading to nothing)

Step 6: Create the particle with all its settings

Use the builder pattern to chain all the properties together
Set velocity, lifetime, scale, rotation speed, color curve, scale curve
Everything is configured and ready to go

Step 7: Make a visual square for the particle

Create a 24-pixel square mesh (scaled by the particle’s size)
Create a material that uses the particle’s starting color
This is what you’ll actually see on screen

Step 8: Tell Bevy to create the particle entity

Bundle everything together: the particle data, the mesh, the material, the position
Bevy spawns a new entity with all these components
The particle is now alive in the game world!

Why std::f32::consts::TAU?

TAU is 2π (approximately 6.28), a full circle in radians. For the Circle emission shape, we pick a random angle from 0 to TAU to get a point anywhere around the circle.

What’s .normalize_or_zero()?

Converts a vector to length 1.0, making it a pure direction. If the vector is zero (no direction), it returns (0,0,0) instead of nan (Not a Number). This is safer than .normalize() which can panic on zero vectors.

Now add the helper functions:

These are small utility functions that help with the math in spawn_particle. They handle the geometry of spreading particles in different directions, essential for creating cone and spray effects instead of straight lines.

// Append to src/particles/systems.rs

/// Apply directional variance to a vector
fn apply_direction_variance(
    direction: Vec3,
    variance: f32,
    rng: &mut rand::rngs::ThreadRng,
) -> Vec3 {
    let angle = rng.gen_range(-variance..variance);
    rotate_vector_2d(direction, angle)
}

/// Rotate a 2D vector by an angle (in radians)
fn rotate_vector_2d(vec: Vec3, angle: f32) -> Vec3 {
    let cos = angle.cos();
    let sin = angle.sin();
    Vec3::new(vec.x * cos - vec.y * sin, vec.x * sin + vec.y * cos, vec.z)
}

What’s this rotation math?

This is a 2D rotation matrix. To rotate a vector by an angle:

New X = old X × cos(angle) - old Y × sin(angle)
New Y = old X × sin(angle) + old Y × cos(angle)

Now the particle update system:

We’ve created the spawning system, but now we need to bring particles to life. The update_particles system runs every frame and handles everything that happens during a particle’s lifetime: moving it, spinning it, fading its color, shrinking its size, and removing it when it dies.

// Append to src/particles/systems.rs

/// System to update particle lifetime and properties
pub fn update_particles(
    mut commands: Commands,
    time: Res<Time>,
    mut particles: Query<(
        Entity,
        &mut Particle,
        &mut Transform,
        &MeshMaterial2d<ParticleMaterial>,
    )>,
    mut materials: ResMut<Assets<ParticleMaterial>>,
) {
    for (entity, mut particle, mut transform, material_handle) in particles.iter_mut() {
        particle.lifetime -= time.delta_secs();

        if particle.lifetime <= 0.0 {
            commands.entity(entity).despawn();
            continue;
        }

        // Update position
        let acceleration = particle.acceleration;
        particle.velocity += acceleration * time.delta_secs();
        transform.translation += particle.velocity * time.delta_secs();

        // Update rotation
        transform.rotate_z(particle.angular_velocity * time.delta_secs());

        // Apply color curve interpolation
        let current_color = particle.current_color();

        // Apply scale curve interpolation
        let current_scale = particle.current_scale();
        transform.scale = Vec3::splat(current_scale);

        // Update material color
        if let Some(material) = materials.get_mut(&material_handle.0) {
            material.color = current_color.to_linear();
        }
    }
}

Breaking it down:

Countdown lifetime: Subtract frame time from particle’s remaining life
Despawn dead particles: When lifetime hits zero, remove the entity
Apply acceleration: Forces modify velocity over time
Update position: Move by velocity each frame
Rotate: Spin the particle based on angular velocity
Update color: Use the curve from current_color()
Update scale: Shrink/grow using current_scale()
Update material: Push the new color to the shader

Finally, add emitter cleanup:

// Append to src/particles/systems.rs

/// System to clean up inactive emitters that are one-shot
pub fn cleanup_finished_emitters(
    mut commands: Commands,
    emitters: Query<(Entity, &ParticleEmitter)>,
) {
    for (entity, emitter) in emitters.iter() {
        if emitter.one_shot && !emitter.active {
            commands.entity(entity).despawn();
        }
    }
}

This removes one-shot emitters after they’ve spawned their particles. Continuous emitters stick around until manually despawned.

The Shader

We now have particles spawning, moving, and dying. But they still look like flat colored squares. To make them glow like magical energy, we need a custom shader that runs on the GPU.

What is a shader?

A shader is a small program that runs on your GPU (graphics card) for every pixel on screen. While our Rust code runs on the CPU and manages game logic, shaders run massively in parallel on the GPU to create visual effects.

What we’re achieving:

We’re creating a radial glow effect where each particle is bright and intense at the center, smoothly fading to transparent at the edges. This makes particles look like glowing orbs of energy instead of flat squares.

Shader Glow Effect Comparison

Without shader (left) vs With radial gradient shader (right)

The language:

This shader is written in WGSL (WebGPU Shading Language), Bevy’s shader language. It’s similar to Rust in some ways but designed specifically for GPU programming.

Create the folder shaders in src/assets and add the shader file particle_glow.wgsl, the final path should be src/assets/shaders/particle_glow.wgsl.

// src/assets/shaders/particle_glow.wgsl
// Custom shader for particles
// Creates a radial gradient glow effect with additive blending
#import bevy_sprite::mesh2d_vertex_output::VertexOutput

@group(#{MATERIAL_BIND_GROUP}) @binding(0) var color: vec4;

@fragment
fn fragment(mesh: VertexOutput) -> @location(0) vec4 {
    // Calculate distance from center (UV space is 0-1)
    let center = vec2(0.5, 0.5);
    let dist = distance(mesh.uv, center) * 2.0; // *2 to normalize to 0-1
    
    // Create radial gradient
    // Bright center → fades to edges
    let radial = 1.0 - smoothstep(0.0, 1.0, dist);
    
    // Add extra glow in the center
    let glow = pow(1.0 - dist, 3.0);
    
    // Combine radial gradient with center glow
    let intensity = radial * 0.7 + glow * 0.5;
    
    // Boost brightness near center for hot glow effect
    let brightness = 1.0 + glow * 0.5;
    
    // Apply to color (supports HDR - values > 1.0)
    let final_rgb = color.rgb * brightness;
    let final_alpha = color.a * intensity;
    
    return vec4(final_rgb, final_alpha);
}

How the shader creates the glow effect:

Inputs the shader receives:

color - The particle’s color sent from Rust code via ParticleMaterial (remember the #[uniform(0)] binding)
mesh.uv - The pixel’s position on the particle square. When Bevy renders a sprite with Material2d, it automatically creates a quad (rectangle) mesh and assigns UV coordinates to each corner: (0,0) at bottom-left, (1,1) at top-right. The GPU interpolates these for each pixel in between.

What’s a mesh and what are UV coordinates?

A mesh is a 3D shape made of triangles. For 2D sprites, Bevy creates a simple quad (2 triangles forming a rectangle) to display the image.

UV coordinates are like a map that tells the shader where each pixel is on that rectangle. Think of it like a grid:

U goes left to right (0.0 = left edge, 1.0 = right edge)
V goes bottom to top (0.0 = bottom edge, 1.0 = top edge)
So (0.5, 0.5) is the exact center of the particle

When the shader runs, every pixel knows its UV position. With these inputs (color and UV coordinates), the shader creates a radial gradient by calculating each pixel’s distance from the particle’s center. Pixels near the center get bright colors, while pixels at the edges fade to transparent.

Here’s the technique:

Calculate distance - Measure how far this pixel is from the particle center
Create smooth falloff - Use smoothstep to gradually fade from bright (center) to dark (edges)
Boost center brightness - Multiply center pixels by values above 1.0 for that “hot core” effect
Combine - Mix the smooth fade with the bright center for a natural-looking glow

Without the shader, particles are just flat colored squares. With it, they become glowing orbs of energy.

What’s smoothstep?

A function that creates smooth transitions. smoothstep(edge0, edge1, x) returns 0 when x is at edge0, 1 when x is at edge1, and smoothly transitions between them. Unlike a straight line transition, it starts slow, speeds up in the middle, then slows down at the end, creating natural looking fades.

Custom Shader Material

Now that we understand shaders, let’s create the Rust code that uses our shader. The ParticleMaterial struct is our bridge between Rust code and the GPU shader, it holds the particle’s color and tells Bevy which shader file to use for rendering.

Create src/particles/material.rs:

// src/particles/material.rs
use bevy::{
    prelude::*,
    reflect::TypePath,
    render::render_resource::{
        AsBindGroup, BlendComponent, BlendFactor, BlendOperation, BlendState, ColorWrites,
        RenderPipelineDescriptor, SpecializedMeshPipelineError,
    },
    shader::ShaderRef,
    sprite_render::{AlphaMode2d, Material2d, Material2dKey},
    mesh::MeshVertexBufferLayoutRef,
};

/// Custom material for particles with radial gradient shader and additive blending
#[derive(Asset, TypePath, AsBindGroup, Debug, Clone)]
pub struct ParticleMaterial {
    #[uniform(0)]
    pub color: LinearRgba,
}

impl ParticleMaterial {
    pub fn new(color: Color) -> Self {
        Self {
            color: color.to_linear(),
        }
    }
}

What’s AsBindGroup?

This macro tells Bevy how to send data from your Rust code to the GPU shader. Think of it like packing a box to ship: the #[uniform(0)] label says “put the color value in slot 0 so the shader can find it.”

Understanding the terms:

Material: A material defines how a surface looks when rendered. It combines a shader (the rendering program) with properties (like color). Our ParticleMaterial is a custom material specifically for particles.
Fragment shader: A shader program that runs for each pixel being drawn. It calculates the final color of that pixel. Our fragment shader creates the radial glow effect.
Alpha blending: How transparent objects are combined with what’s behind them. Normal alpha blending makes things see-through. Additive blending (what we use) adds brightness values together for glowing effects.
Specialize: Customizing the rendering pipeline for this specific material. We use it to configure additive blending instead of normal transparency.

Now implement the Material2d trait:

The Material2d trait tells Bevy how to render our custom material. We implement three methods:

fragment_shader() - Returns the path to our shader file
alpha_mode() - Enables transparency blending
specialize() - Configures the rendering pipeline for additive blending

// Append to src/particles/material.rs

impl Material2d for ParticleMaterial {
    fn fragment_shader() -> ShaderRef {
        "shaders/particle_glow.wgsl".into()
    }

    fn alpha_mode(&self) -> AlphaMode2d {
        AlphaMode2d::Blend
    }

    fn specialize(
        descriptor: &mut RenderPipelineDescriptor,
        _layout: &MeshVertexBufferLayoutRef,
        _key: Material2dKey<Self>,
    ) -> Result<(), SpecializedMeshPipelineError> {
        // Set up additive blending for glowing effect
        if let Some(fragment) = &mut descriptor.fragment {
            if let Some(target) = fragment.targets.first_mut() {
                if let Some(target_state) = target.as_mut() {
                    target_state.blend = Some(BlendState {
                        color: BlendComponent {
                            src_factor: BlendFactor::SrcAlpha,
                            dst_factor: BlendFactor::One, // Additive!
                            operation: BlendOperation::Add,
                        },
                        alpha: BlendComponent {
                            src_factor: BlendFactor::One,
                            dst_factor: BlendFactor::One,
                            operation: BlendOperation::Add,
                        },
                    });
                    target_state.write_mask = ColorWrites::ALL;
                }
            }
        }
        Ok(())
    }
}

The specialize function configures the GPU’s rendering pipeline for our particle material. It tells the GPU how to blend each rendered particle with what’s already on screen.

What this means for rendered particles: When a particle is drawn, the GPU needs to know how to combine its color with the background. Normal transparency makes overlapping particles darker. Additive blending makes them brighter and glowing. This is what creates that magical fire/magic look.

Here’s what the function does:

Access the pipeline descriptor - Gets the configuration for how this material will be rendered
Find the color target - Locates where color output is defined
Set up additive blending - Configures the blend mode:
- src_factor: SrcAlpha - Multiply particle color by its transparency
- dst_factor: One - Keep the background color at full strength (don’t darken it)
- operation: Add - Add them together

Result: Overlapping particles add their brightness together, creating intense glows where they overlap. Ten overlapping fire particles create a bright white-hot center!

What’s additive blending?

Normal alpha blending: new_color = particle_color * alpha + background * (1 - alpha)

Additive blending: new_color = particle_color + background

Overlapping particles add their brightness together, creating intense glows. This is how fire, magic, and explosions get that magical glowing look.

Particles Module Plugin

Create src/particles/mod.rs:

// src/particles/mod.rs
pub mod components;
pub mod material;
pub mod systems;

use crate::state::GameState;
use bevy::{prelude::*, sprite_render::Material2dPlugin};

pub use material::*;
pub use systems::*;

pub struct ParticlesPlugin;

impl Plugin for ParticlesPlugin {
    fn build(&self, app: &mut App) {
        info!("Initializing ParticlesPlugin");
        app.add_plugins(Material2dPlugin::<ParticleMaterial>::default())
            .add_systems(
                Update,
                (update_emitters, update_particles, cleanup_finished_emitters)
                    .chain()
                    .run_if(in_state(GameState::Playing)),
            );
        info!("ParticlesPlugin initialized");
    }
}

Why .chain()?

Systems in a chain run sequentially in the order specified. We want:

update_emitters - Spawn new particles
update_particles - Update existing particles
cleanup_finished_emitters - Remove dead emitters

This prevents edge cases where an emitter spawns particles then immediately despawns.

Creating the Combat Module

Now that we have a particle system, let’s build the combat system that uses it! Create a new folder src/combat/ for our combat system.

Power Types

Different powers need different behaviors and visuals. Let’s start by defining what makes each power unique.

Create src/combat/power_type.rs:

// src/combat/power_type.rs
use bevy::prelude::*;
use crate::particles::components::{EmissionShape, ParticleConfig};

/// The different magical powers available
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum PowerType {
    #[default]
    Fire,
    Arcane,
    Shadow,
    Poison,
}

Now let’s define the visual configuration for each power. We’ll separate visuals from behavior (future chapters will add damage, collision, etc.):

// Append to src/combat/power_type.rs

/// Visual configuration for a power - decoupled from behavior
#[derive(Clone)]
pub struct PowerVisuals {
    pub primary: ParticleConfig,
    pub core: Option<ParticleConfig>,
    pub particles_per_spawn: u32,
    pub core_particles_per_spawn: u32,
}

What’s the difference between primary and core?

Many effects have two layers:

Primary: The outer glow/trail (lots of particles, less bright)
Core: The bright center (fewer particles, very bright)

Imagine a fireball, the core is the white-hot center, the primary is the orange flames around it. Not all powers need a core, poison is just a single layer of green particles.

Now we can use the ParticleConfig and EmissionShape types we defined earlier! Let’s implement the visual configurations for each power type:

Now we’ll configure how each power looks and behaves using the ParticleConfig struct. Each power gets unique visual properties (colors, speeds, sizes, variances) that define its character. Fire gets HDR orange colors and wide spread, while Shadow uses tight precision with many fast particles.

// Append to src/combat/power_type.rs

impl PowerType {
    /// Get visual configuration for this power
    pub fn visuals(&self, direction: Vec3) -> PowerVisuals {
        match self {
            PowerType::Fire => Self::fire_visuals(direction),
            PowerType::Arcane => Self::arcane_visuals(direction),
            PowerType::Shadow => Self::shadow_visuals(direction),
            PowerType::Poison => Self::poison_visuals(direction),
        }
    }

    fn fire_visuals(direction: Vec3) -> PowerVisuals {
        PowerVisuals {
            primary: ParticleConfig {
                lifetime: 1.0,
                lifetime_variance: 0.2,
                speed: 350.0,
                speed_variance: 40.0,
                direction,
                direction_variance: 0.12,
                scale: 1.5,
                scale_variance: 0.5,
                color: Color::srgb(3.0, 0.5, 0.1),  // Bright orange-red
                angular_velocity: 3.0,
                angular_velocity_variance: 2.0,
                acceleration: Vec3::ZERO,
                emission_shape: EmissionShape::Circle { radius: 10.0 },
            },
            core: Some(ParticleConfig {
                lifetime: 0.8,
                lifetime_variance: 0.2,
                speed: 350.0,
                speed_variance: 30.0,
                direction,
                direction_variance: 0.08,
                scale: 1.0,
                scale_variance: 0.3,
                color: Color::srgb(4.0, 1.0, 0.2),  // Very bright yellow-white
                angular_velocity: 5.0,
                angular_velocity_variance: 2.0,
                acceleration: Vec3::ZERO,
                emission_shape: EmissionShape::Circle { radius: 5.0 },
            }),
            particles_per_spawn: 5,
            core_particles_per_spawn: 3,
        }
    }

    fn arcane_visuals(direction: Vec3) -> PowerVisuals {
        PowerVisuals {
            primary: ParticleConfig {
                lifetime: 1.2,
                lifetime_variance: 0.2,
                speed: 300.0,
                speed_variance: 30.0,
                direction,
                direction_variance: 0.05,  // Very precise
                scale: 1.2,
                scale_variance: 0.3,
                color: Color::srgb(0.5, 0.8, 2.5),  // Blue arcane energy
                angular_velocity: 2.0,
                angular_velocity_variance: 1.0,
                acceleration: Vec3::ZERO,
                emission_shape: EmissionShape::Circle { radius: 6.0 },
            },
            core: Some(ParticleConfig {
                lifetime: 1.0,
                lifetime_variance: 0.1,
                speed: 300.0,
                speed_variance: 20.0,
                direction,
                direction_variance: 0.03,  // Even more precise
                scale: 0.8,
                scale_variance: 0.2,
                color: Color::srgb(0.9, 0.95, 3.0),  // Bright white-blue
                angular_velocity: 0.5,
                angular_velocity_variance: 0.5,
                acceleration: Vec3::ZERO,
                emission_shape: EmissionShape::Point,
            }),
            particles_per_spawn: 4,
            core_particles_per_spawn: 2,
        }
    }

    fn shadow_visuals(direction: Vec3) -> PowerVisuals {
        PowerVisuals {
            primary: ParticleConfig {
                lifetime: 0.6,  // Short-lived
                lifetime_variance: 0.15,
                speed: 600.0,  // Very fast
                speed_variance: 100.0,
                direction,
                direction_variance: 0.04,
                scale: 1.0,
                scale_variance: 0.4,
                color: Color::srgb(0.6, 0.2, 1.2),  // Dark purple
                angular_velocity: 8.0,  // Spins fast
                angular_velocity_variance: 4.0,
                acceleration: Vec3::ZERO,
                emission_shape: EmissionShape::Point,
            },
            core: Some(ParticleConfig {
                lifetime: 0.5,
                lifetime_variance: 0.1,
                speed: 650.0,
                speed_variance: 80.0,
                direction,
                direction_variance: 0.02,
                scale: 1.3,
                scale_variance: 0.3,
                color: Color::srgb(1.0, 0.5, 1.8),  // Brighter purple core
                angular_velocity: 12.0,
                angular_velocity_variance: 5.0,
                acceleration: Vec3::ZERO,
                emission_shape: EmissionShape::Point,
            }),
            particles_per_spawn: 7,  // Many particles
            core_particles_per_spawn: 3,
        }
    }

    fn poison_visuals(direction: Vec3) -> PowerVisuals {
        PowerVisuals {
            primary: ParticleConfig {
                lifetime: 1.5,  // Long-lived
                lifetime_variance: 0.4,
                speed: 200.0,  // Slow
                speed_variance: 50.0,
                direction,
                direction_variance: 0.25,  // Spreads a lot
                scale: 1.8,  // Large particles
                scale_variance: 0.6,
                color: Color::srgb(0.3, 2.0, 0.3),  // Toxic green
                angular_velocity: 1.0,
                angular_velocity_variance: 2.0,
                acceleration: Vec3::new(0.0, 20.0, 0.0),  // Rises slightly
                emission_shape: EmissionShape::Circle { radius: 15.0 },
            },
            core: None,  // No core - just a cloud
            particles_per_spawn: 6,
            core_particles_per_spawn: 0,
        }
    }
}

The configuration numbers define each power’s unique character. Fire has high speed (350), wide spread (0.12 variance), and HDR orange colors. Shadow has very high speed (500), tight beam (0.05 variance), and dark purple.

Why Color::srgb(3.0, 0.5, 0.1) with values above 1.0?

Values above 1.0 create HDR (High Dynamic Range) colors that glow brighter than normal. When combined with additive blending (from our particle shader), these create the magical glow effect. It’s like cranking the brightness past 100%, perfect for fire and magic.

What’s direction_variance?

Controls how much particles spread. Low variance (0.03 for Arcane) means particles stay in a tight beam. High variance (0.25 for Poison) creates a wide, spreading cloud. It’s measured in radians.

Now notice the design pattern here: each power has a distinct character expressed through numbers:

Power	Character	Speed	Lifetime	Spread	Particles
Fire	Hot, chaotic	Medium	Short	Medium	Medium
Arcane	Precise, magical	Medium	Long	Tight	Few
Shadow	Fast, deadly	Fast	Very short	Tight	Many
Poison	Spreading, lingering	Slow	Long	Wide	Medium

This data-driven approach means adding a new power is just adding a new function with different numbers, no code logic changes needed.

Player Combat Component

Now we need a component to attach to the player that tracks their current power and prevents rapid-fire spam.

We use a countdown Timer that must finish before the next attack. When the player attacks, we check if the timer is finished. If yes, spawn particles and reset the timer back to 0.5 seconds. If no, ignore the input. This creates a smooth attack rate without complex cooldown tracking.

Create src/combat/player_combat.rs:

// src/combat/player_combat.rs
use super::power_type::PowerType;
use bevy::prelude::*;

/// Attach to any entity that can use powers (player, NPCs)
#[derive(Component)]
pub struct PlayerCombat {
    pub power_type: PowerType,
    pub cooldown: Timer,
}

impl Default for PlayerCombat {
    fn default() -> Self {
        Self {
            power_type: PowerType::Fire,
            cooldown: Timer::from_seconds(0.5, TimerMode::Once),
        }
    }
}

impl PlayerCombat {
    pub fn new(power_type: PowerType) -> Self {
        Self {
            power_type,
            cooldown: Timer::from_seconds(0.5, TimerMode::Once),
        }
    }

    pub fn with_cooldown(mut self, seconds: f32) -> Self {
        self.cooldown = Timer::from_seconds(seconds, TimerMode::Once);
        self
    }
}

What’s TimerMode::Once?

Timers in Bevy can be Once (stop when finished) or Repeating (restart automatically). For cooldowns, we want Once, the timer counts down from 0.5 seconds to 0, then stops. We manually reset it when the player attacks.

Why 0.5 seconds?

This creates a ~2 attacks per second rate. Too fast feels spammy, too slow feels unresponsive. You can tweak this with .with_cooldown() for different weapons or upgrades.

Combat Systems

Now for the system that handles player input and spawns projectiles.

Create src/combat/systems.rs:

// src/combat/systems.rs
use super::player_combat::PlayerCombat;
use super::power_type::{PowerType, PowerVisuals};
use crate::characters::facing::Facing;
use crate::characters::input::Player;
use crate::particles::components::ParticleEmitter;
use bevy::prelude::*;

/// Marker for projectile effects
#[derive(Component)]
pub struct ProjectileEffect {
    pub power_type: PowerType,
}

pub fn handle_power_input(
    mut commands: Commands,
    input: Res<ButtonInput<KeyCode>>,
    time: Res<Time>,
    mut player_query: Query<(&GlobalTransform, &Facing, &mut PlayerCombat), With<Player>>,
) {
    let Ok((global_transform, facing, mut combat)) = player_query.single_mut() else {
        return;
    };

    combat.cooldown.tick(time.delta());

    let ctrl_pressed =
        input.just_pressed(KeyCode::ControlLeft) || input.just_pressed(KeyCode::ControlRight);

    if !ctrl_pressed {
        return;
    }

    // Only fire if cooldown has elapsed
    if combat.cooldown.elapsed_secs() < combat.cooldown.duration().as_secs_f32() {
        return;
    }

    combat.cooldown.reset();

    let position: Vec3 = global_transform.translation();
    let direction = facing_to_vec3(facing);
    let spawn_position = position + direction * 5.0;

    // Get visuals from power type
    let visuals = combat.power_type.visuals(direction);

    spawn_projectile(&mut commands, spawn_position, combat.power_type, &visuals);

    info!("{:?} projectile fired!", combat.power_type);
}

Breaking it down:

Tick the cooldown: combat.cooldown.tick(time.delta()) counts down by the frame time
Check input: Only proceed if Ctrl is pressed
Check cooldown: If elapsed_secs() < duration(), we’re still on cooldown
Reset cooldown: combat.cooldown.reset() starts the timer over
Calculate spawn position: Offset slightly from the player in the facing direction
Get visuals: Power type knows its own visual configuration
Spawn projectile: Create the particle emitters using our particle system!

Now let’s implement the projectile spawning system. This is where we convert player input into visible magical effects.

// Append to src/combat/systems.rs

fn spawn_projectile(
    commands: &mut Commands,
    position: Vec3,
    power_type: PowerType,
    visuals: &PowerVisuals,
) {
    // Primary particles
    let primary_emitter =
        ParticleEmitter::new(0.016, visuals.particles_per_spawn, visuals.primary.clone())
            .one_shot();

    commands.spawn((
        primary_emitter,
        Transform::from_translation(position),
        GlobalTransform::from(Transform::from_translation(position)),
        ProjectileEffect { power_type },
    ));

    // Core particles (if the power has a core)
    if let Some(ref core_config) = visuals.core {
        let core_emitter =
            ParticleEmitter::new(0.016, visuals.core_particles_per_spawn, core_config.clone())
                .one_shot();

        commands.spawn((
            core_emitter,
            Transform::from_translation(position),
            GlobalTransform::from(Transform::from_translation(position)),
            ProjectileEffect { power_type },
        ));
    }
}

How the spawning function works:

Create primary emitter - Spawn the main particle layer with configured count and settings
Mark as one-shot - Emitter spawns once then deactivates (perfect for projectiles)
Position it - Place at the specified position
Add marker component - ProjectileEffect tags this as a projectile for other systems
Spawn core (if exists) - Some powers have a bright center layer

The function takes the visual configuration and converts it into actual particle emitters. Each emitter is its own entity with the ParticleEmitter component.

Now add the helper function to convert facing to direction:

// Append to src/combat/systems.rs

fn facing_to_vec3(facing: &Facing) -> Vec3 {
    match facing {
        Facing::Right => Vec3::X,
        Facing::Left => Vec3::NEG_X,
        Facing::Up => Vec3::Y,
        Facing::Down => Vec3::NEG_Y,
    }
}

Finally, let’s add a debug system to quickly switch between powers for testing:

// Append to src/combat/systems.rs

/// Switch powers with number keys (for testing)
pub fn debug_switch_power(
    input: Res<ButtonInput<KeyCode>>,
    mut player_query: Query<&mut PlayerCombat, With<Player>>,
) {
    let Ok(mut combat) = player_query.single_mut() else {
        return;
    };

    let new_power = if input.just_pressed(KeyCode::Digit1) {
        Some(PowerType::Fire)
    } else if input.just_pressed(KeyCode::Digit2) {
        Some(PowerType::Arcane)
    } else if input.just_pressed(KeyCode::Digit3) {
        Some(PowerType::Shadow)
    } else if input.just_pressed(KeyCode::Digit4) {
        Some(PowerType::Poison)
    } else {
        None
    };

    if let Some(power) = new_power {
        combat.power_type = power;
        info!("Switched to {:?}", power);
    }
}

This lets you press 1-4 to instantly switch powers while playing. Essential for testing visual effects without restarting the game.

Combat Module Plugin

Create src/combat/mod.rs:

// src/combat/mod.rs
mod player_combat;
mod power_type;
mod systems;

pub use player_combat::PlayerCombat;
pub use power_type::{PowerType, PowerVisuals};
pub use systems::{ProjectileEffect, debug_switch_power, handle_power_input};

use bevy::prelude::*;

pub struct CombatPlugin;

impl Plugin for CombatPlugin {
    fn build(&self, app: &mut App) {
        app.add_systems(Update, (handle_power_input, debug_switch_power));
    }
}

Perfect! Now our combat module is ready to use the particle system.

Putting it all together

Now let’s wire everything together!

First, add rand to your Cargo.toml:

[dependencies]
bevy = "0.18"
bevy_procedural_tilemaps = "0.2.0"
bevy_common_assets = { version = "0.15.0-rc.1", features = ["ron"] }
serde = { version = "1.0", features = ["derive"] }
rand = "0.8"  # Add this line

Open src/main.rs and add the modules:

// src/main.rs - Add to module declarations
mod combat;
mod particles;

Then add the plugins:

// src/main.rs - Add to the plugin chain
.add_plugins(combat::CombatPlugin)
.add_plugins(particles::ParticlesPlugin)

The player needs the PlayerCombat component. Open src/characters/spawn.rs:

// src/characters/spawn.rs - Add import
use crate::combat::PlayerCombat;

Find the initialize_player_character system and add the combat component when inserting the player:

// In the initialize_player_character function, add PlayerCombat to the character entity bundle
commands.entity(entity).insert((
            AnimationController::default(),
            CharacterState::default(), 
            Velocity::default(),       
            Facing::default(),         
            Collider::default(),
            PlayerCombat::default(), // Add this line
            AnimationTimer(Timer::from_seconds(
                DEFAULT_ANIMATION_FRAME_TIME,
                TimerMode::Repeating,
            )),
            character_entry.clone(),
            sprite,
        ));

Run your game:

cargo run

Spawn Troubleshooting: There's a small chance the procedural generation places the player on top of a blocking object (tree, rock) at spawn. If you can't move when the game starts, simply restart to generate a new map. This is a quirk of random generation we'll address in future chapters.

Controls:

Arrow keys: Move
Ctrl: Fire current power
1-4: Switch powers (Fire, Arcane, Shadow, Poison)

The Impatient Programmer’s Guide to Bevy and Rust: Chapter 5 - Let There Be Pickups

2026-01-11T00:00:00+00:00

By the end of this chapter, you’ll have an inventory system that lets your player collect items from the world, and a smooth camera that follows them around. Walk near a plant or mushroom, and it disappears into your inventory. Move across the map, and the camera keeps you centered with buttery-smooth motion.

Prerequisites: This is Chapter 5 of our Bevy tutorial series. Join our community for updates on new releases. Before starting, complete Chapter 1: Let There Be a Player, Chapter 2: Let There Be a World, Chapter 3: Let The Data Flow, and Chapter 4: Let There Be Collisions, or clone the Chapter 4 code from this repository to follow along.

Building the Pickup System

In Chapter 4, we made solid objects block the player. Now let’s do the opposite: make items the player can walk through and collect.

The Pickup System

Think about how pickups work in games you’ve played:

Detection: “Is the player close enough to this item?”
Collection: “Remove the item from the world”
Storage: “Remember what was collected”

We’ll build this in three parts:

A Pickable component to mark items as collectible
A handle_pickups system to detect when the player is near items
An Inventory resource to track what’s been collected

Configuring Pickup Radius

Before we build the inventory, let’s add configuration for pickup detection. We already have a config.rs file from Chapter 4 where we centralized collision settings. Let’s add pickup configuration there.

Open src/config.rs and you’ll see it’s organized into modules: player, map, debug. Let’s add a pickup module:

// src/config.rs - Add this section after the player module

/// Pickup/inventory configuration
pub mod pickup {
    /// Default radius for item pickup detection (in world units)
    pub const DEFAULT_RADIUS: f32 = 40.0;
}

What’s a world unit?

In Bevy, positions are measured in world units. Our tiles are 32 units wide (from map::TILE_SIZE), so a radius of 40 units means the player can pick up items from slightly more than one tile away. Not too far, not too close.

Building the Inventory System

Create a new folder src/inventory/ for our inventory module.

Defining Item Types

What kinds of items can the player collect? In our game, we have plants, mushrooms(or something that looks like a mushroom) scattered around the map. Each needs a unique identifier.

Create src/inventory/inventory.rs:

// src/inventory/inventory.rs
use bevy::prelude::*;
use std::collections::HashMap;
use std::fmt;

use crate::config::pickup::DEFAULT_RADIUS;

/// Types of items that can be collected.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ItemKind {
    Plant1,
    Plant2,
    Plant3,
    Plant4,
}

Display Names

Players don’t want to see “Plant1” in their inventory. They want “Herb” or “Flower”. Let’s add human-readable names:

// Append to src/inventory/inventory.rs

impl ItemKind {
    pub fn display_name(&self) -> &'static str {
        match self {
            ItemKind::Plant1 => "Herb",
            ItemKind::Plant2 => "Flower",
            ItemKind::Plant3 => "Mushroom",
            ItemKind::Plant4 => "Fern",
        }
    }
}

impl fmt::Display for ItemKind {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(self.display_name())
    }
}

What’s fmt::Display for?

fmt::Display is like a predefined contract Rust makes with your type. It’s like saying, “If you implement this trait, I’ll let you use {} in print statements.”

Without it, println!("Collected: {}", item_kind) would fail to compile. Rust wouldn’t know how to convert your ItemKind::Plant1 into text for display. By implementing Display, we fulfill the contract, we tell Rust “when you need to print this, call this fmt method I wrote.”

The Pickable Component

Now we need a component to mark entities as collectible. When we spawn a plant in the world, we’ll attach this component to say “the player can pick this up.”

// Append to src/inventory/inventory.rs

/// Component marking an entity as collectible.
#[derive(Component, Debug)]
pub struct Pickable {
    pub kind: ItemKind,
    pub radius: f32,
}

impl Pickable {
    pub fn new(kind: ItemKind) -> Self {
        Self {
            kind,
            radius: DEFAULT_RADIUS,
        }
    }
}

Why store radius per item?

Most items use the default radius (40 units), but maybe you want a treasure chest to have a smaller radius (must be right next to it) or a glowing orb to have a larger one (magnetic pull). Storing it in the component gives you flexibility.

The Inventory Resource

The inventory persists across the entire game session, it’s not tied to any single entity. That’s what Resources are for: global game state that any system can access.

// Append to src/inventory/inventory.rs

/// Resource storing collected items.
#[derive(Resource, Default, Debug)]
pub struct Inventory {
    items: HashMap<ItemKind, u32>,
}

Why HashMap instead of Vec?

A Vec would store every individual item: [Plant1, Plant1, Plant2, Plant1...]. To count how many Plant1s you have, you’d scan the whole list. A HashMap stores counts directly: {Plant1: 3, Plant2: 1}. It also makes lookups efficient.

Adding Items to Inventory

Now let’s implement the logic to add items to the inventory:

// Append to src/inventory/inventory.rs

impl Inventory {
    /// Add an item to the inventory, returns new count.
    pub fn add(&mut self, kind: ItemKind) -> u32 {
        let entry = self.items.entry(kind).or_insert(0);
        *entry += 1;
        *entry
    }

    /// Get a summary string of inventory contents.
    pub fn summary(&self) -> String {
        if self.items.is_empty() {
            return "empty".to_string();
        }

        let mut parts: Vec<String> = self
            .items
            .iter()
            .map(|(kind, count)| format!("{}: {}", kind, count))
            .collect();
        parts.sort();
        parts.join(", ")
    }
}

What’s .entry(kind).or_insert(0) doing?

This is HashMap’s “get or create” pattern. If kind exists in the map, .entry(kind) gets a mutable reference to its value. If not, .or_insert(0) creates it with a count of 0. Then we increment and return the new count.

Why return the count from add?

So the pickup system can log “Picked up Herb (total: 3)”. It’s a small quality-of-life feature that makes debugging easier.

What’s the summary method for?

It formats the inventory for display: “Herb: 3, Flower: 1, Wood: 2”. We sort the items alphabetically so the order is consistent. Later, you could show this in a UI panel or debug overlay.

Pickup Detection System

Now for the system that actually detects when the player is near an item. Create src/inventory/systems.rs:

// src/inventory/systems.rs
use bevy::prelude::*;

use crate::characters::input::Player;
use super::inventory::{Pickable, Inventory};

/// System that checks for and processes item pickups.
pub fn handle_pickups(
    mut commands: Commands,
    mut inventory: ResMut<Inventory>,
    player_query: Query<&Transform, With<Player>>,
    pickables: Query<(Entity, &GlobalTransform, &Pickable)>,
) {
    let Ok(player_transform) = player_query.single() else {
        return;
    };

    let player_pos = player_transform.translation.truncate();
    let mut collected = Vec::new();

    // Check distance to each pickable
    for (entity, global_transform, pickable) in pickables.iter() {
        let item_pos = global_transform.translation().truncate();
        let distance_sq = player_pos.distance_squared(item_pos);
        
        if distance_sq <= pickable.radius * pickable.radius {
            collected.push((entity, pickable.kind));
        }
    }

    // Process collected items
    for (entity, kind) in collected {
        commands.entity(entity).despawn();
        let count = inventory.add(kind);
        info!(
            " Picked up {} (total: {}) — inventory: {}",
            kind, count, inventory.summary()
        );
    }
}

Let’s break this down step by step.

Getting the Player Position

We query for the player’s position as we did in the earlier chapters.

What’s .truncate()?

Transform.translation is a Vec3 (x, y, z). We’re in 2D, so we only care about x and y. .truncate() converts Vec3 to Vec2, dropping the z component.

Collecting Items to Process

Before we can despawn collected items, we need to identify which ones are within pickup range.

We create an empty Vec and iterate through all pickable items. For each item within range, we store its entity ID and item kind as a tuple (entity, pickable.kind). This gives us a list of everything the player just picked up.

Why distance_squared instead of distance?

The actual distance formula is sqrt((x2-x1)² + (y2-y1)²). Square root is expensive. But we’re just comparing distances, so we can compare the squared distances instead:

distance < radius is the same as distance² < radius²
No square root needed, just multiplication

This is a common game dev optimization. When checking hundreds of items every frame, it adds up.

Processing Collected Items

Later we go through the collected items and do the following:

Despawn the entity: Removes it from the world (no more rendering, no more queries)
Add to inventory: Updates the count in the HashMap
Log the pickup: Prints to console for debugging

Why collect items into a Vec first before despawning them?

You might notice we use a two-step pattern: first collect items into a list, then process them. In our Bevy code, we could actually skip this and despawn directly in the loop, but we follow this pattern because it’s a Rust best practice that makes code safer and clearer.

Let’s learn why this pattern exists:

The Borrow Checker

Remember in Chapter 1, where we learned about how Rust gets mad when we don’t put mut when declaring a variable we want to change? That was just the beginning. Rust has more rules about how you can access and modify data, enforced by something called the borrow checker.

What’s a borrow checker?

Let’s start with a fundamental problem: when should we free memory? When you create a variable in most languages, it allocates memory. When you’re done with it, that memory should be freed:

Languages like Python and JavaScript: Garbage Collection

In Python or JavaScript, you never explicitly free variables. A garbage collector runs periodically, checking which variables are still being used:

This is convenient, you don’t think about memory. But it has costs:

Pause times: The garbage collector must pause your program to scan memory
Overhead: It tracks every variable at runtime, using extra memory
Unpredictability: You don’t know when pauses happen

Rust’s Approach: Compile-Time Checks

Rust takes a different approach. It checks at compile time that your code follows strict rules. When the compiler sees these rules followed, it knows exactly when each variable’s memory can be freed, no runtime tracking needed:

// Pseudo code, don't use
fn example() {
    let items = vec![1, 2, 3];  // items owns the vector
    
    process(items);              // ownership transferred to process()
                                 // items can't be used anymore
}  // Compiler inserts cleanup here - no garbage collector!

The borrow checker enforces rules that let the compiler figure out memory lifetimes. Let’s learn these rules.

The Borrowing Rules

Many readers OR one writer, never both

You can have many immutable references OR one mutable reference, but not both at the same time.

Why? Imagine you’re reading a map while someone is erasing and redrawing it. You might read half-old, half-new data—corruption! This rule prevents that:

Example code:

// Pseudo code, don't use
let mut inventory = vec!["Herb", "Flower"];

let reader1 = &inventory;  // ✓ Immutable borrow
let reader2 = &inventory;  // ✓ Another immutable borrow is fine
println!("{:?}", reader1); // Both can read
println!("{:?}", reader2);

// After the immutable borrows are done being used, we can create a mutable borrow:
let writer = &mut inventory;  // ✓ Now this works
writer.push("Mushroom");

The key insight: borrows end when they’re last used, not when they go out of scope. Once reader1 and reader2 are done (after the println! calls), the mutable borrow is allowed.

This won’t compile:

// Pseudo code, don't use
let mut inventory = vec!["Herb", "Flower"];

let reader = &inventory;
let writer = &mut inventory;  // ✗ ERROR: Can't borrow as mutable while immutably borrowed

println!("{:?}", reader);  // reader still used here

References must always be valid (no dangling pointers)

A reference can’t outlive the data it points to.

Why? In C++, you can create a pointer to memory that gets freed, leaving a “dangling pointer.” Reading it accesses random memory—crash or worse, subtle corruption.

Here’s a C++ example that compiles but crashes at runtime:

int* create_dangling_pointer() {
    int x = 5;           // x is allocated on the stack
    int* ptr = &x;       // ptr points to x
    return ptr;          // Return pointer to x
}  // x goes out of scope here - memory freed!

int main() {
    int* ptr = create_dangling_pointer();
    
    // ptr now points to freed memory (dangling pointer)
    std::cout << *ptr;   // CRASH! Reading freed memory
    
    return 0;
}

What happens:

Function creates local variable x on the stack
Function returns a pointer to x
When function exits, x is destroyed, but ptr still holds its address
Back in main, using ptr reads memory that’s been freed
Result: undefined behavior (crash, garbage data, or worse)

Rust prevents this at compile time:

// Pseudo code, don't use
fn dangling() -> &String {
    let s = String::from("hello");
    &s  // ✗ ERROR: `s` doesn't live long enough
}  // s is dropped here, but we're trying to return a reference to it!

The compiler rejects this. You must either return the owned value or ensure the reference outlives the data.

How this helps with memory management:

When Rust sees code following these rules, it can prove at compile time that:

No variable is used after being freed
No variable is modified while being read
Memory can be safely freed when the owner goes out of scope

The compiler inserts cleanup code automatically, knowing it’s safe. No garbage collector needed!

Why This Pattern Exists in General Rust

In most Rust code (unlike Bevy’s special Commands), you can’t modify a collection while iterating over it. Here’s a real example that won’t compile:

// Pseudo code, don't use
let mut items = vec![1, 2, 3, 4, 5];

for (index, item) in items.iter().enumerate() {  // ← Immutable borrow starts
    if *item % 2 == 0 {
        items.remove(index);  // ✗ ERROR: Can't mutably borrow while immutably borrowed!
    }
}

Rust rejects this with: “cannot borrow as mutable because it is also borrowed as immutable.”

Why? While .iter() is reading through the list, .remove() tries to modify it. That’s like trying to read a book while someone’s tearing pages out—you might try to read a page that’s gone!

The Safe Pattern: Collect-Then-Process

// Pseudo code, don't use
let mut items = vec![1, 2, 3, 4, 5];
let mut to_remove = Vec::new();

// Step 1: Just reading (immutable borrow)
for (index, item) in items.iter().enumerate() {
    if *item % 2 == 0 {
        to_remove.push(index);
    }
}  // ← Immutable borrow ends

// Step 2: Now we can modify (mutable borrow)
for index in to_remove.iter().rev() {  // Remove from back to front
    items.remove(*index);  // ✓ Safe! No conflicting borrows
}

This pattern separates reading from writing. The borrow checker is happy, and we avoid crashes.

In Our Bevy Code

Even though Bevy’s Commands doesn’t strictly require this pattern (it’s deferred), we use it anyway because:

It makes our intent clear: “find eligible items” then “process them”
It follows Rust best practices that work everywhere
If we later need to work with non-deferred collections, the pattern still applies

Wiring It Together

Create src/inventory/mod.rs to expose the inventory system as a plugin:

// src/inventory/mod.rs
use bevy::prelude::*;

use crate::state::GameState;

mod inventory;
mod systems;

pub use inventory::{ItemKind, Pickable, Inventory};
use systems::handle_pickups;

/// Plugin for inventory and pickup functionality.
pub struct InventoryPlugin;

impl Plugin for InventoryPlugin {
    fn build(&self, app: &mut App) {
        app.init_resource::<Inventory>()
            .add_systems(
                Update,
                handle_pickups.run_if(in_state(GameState::Playing)),
            );
    }
}

What does .init_resource::() do?

It creates the Inventory resource by calling Default::default() (which creates an empty HashMap) and registers it with Bevy. Now any system can access it with Res or ResMut.

Integrating the Plugin

Open src/main.rs and add the inventory module and plugin:

// src/main.rs - Add to module declarations
mod inventory;

Then add the plugin to your app:

// src/main.rs - Add to the plugin chain
.add_plugins(state::StatePlugin)
.add_plugins(characters::CharactersPlugin)
.add_plugins(inventory::InventoryPlugin)  // Add this line
.add_plugins(collision::CollisionPlugin)

Making Items Pickable

Now we have the infrastructure, but no items to pick up! Our procedural map generation system needs to know which decorative objects should be pickable.

Updating the Asset Spawner

Open src/map/assets.rs. First, add the inventory imports at the top of the file:

// src/map/assets.rs - Add to the imports section
use crate::inventory::{ItemKind, Pickable};

Now add a method to the SpawnableAsset struct that marks an asset as pickable:

// src/map/assets.rs - Add this method to the impl block for SpawnableAsset

// Inside impl SpawnableAsset {

/// Make this asset a pickable item.
pub fn with_pickable(mut self, kind: ItemKind) -> Self {
    self.pickable = Some(kind);
    self
}

This method lets us chain .with_pickable(ItemKind::Plant1) when defining spawnable assets.

Next, update the SpawnableAsset struct to store the pickable item kind:

// src/map/assets.rs - Add this field to SpawnableAsset struct

#[derive(Clone)]
pub struct SpawnableAsset {
    sprite_name: &'static str,
    grid_offset: GridDelta,
    offset: Vec3,
    tile_type: Option<TileType>,
    pickable: Option<ItemKind>,  // Add this line
}

Update the constructor to initialize this field:

// src/map/assets.rs - Update the new() method

impl SpawnableAsset {
    pub fn new(sprite_name: &'static str) -> Self {
        Self {
            sprite_name,
            grid_offset: GridDelta::new(0, 0, 0),
            offset: Vec3::ZERO,
            tile_type: None,
            pickable: None,  // Add this line
        }
    }
    // ... rest of the methods

Update the asset loading code:

Since we added a new field to SpawnableAsset, we need to update the destructuring pattern in the load_assets function:

// src/map/assets.rs - Update the destructuring in load_assets function

pub fn load_assets(
    tilemap_handles: &TilemapHandles,
    assets_definitions: Vec<Vec<SpawnableAsset>>,
) -> ModelsAssets<Sprite> {
    let mut models_assets = ModelsAssets::<Sprite>::new();
    
    for (model_index, assets) in assets_definitions.into_iter().enumerate() {
        for asset_def in assets {
            let SpawnableAsset {
                sprite_name,
                grid_offset,
                offset,
                tile_type,
                pickable, // Add this line
            } = asset_def;

            let Some(atlas_index) = TILEMAP.sprite_index(sprite_name) else {
                panic!("Unknown atlas sprite '{}'", sprite_name);
            };

            // Create the spawner function that adds components
            let spawner = create_spawner(tile_type, pickable); // Line update alert

            models_assets.add(
                model_index,
                ModelAsset {
                    assets_bundle: tilemap_handles.sprite(atlas_index),
                    grid_offset,
                    world_offset: offset,
                    spawn_commands: spawner,
                },
            );
        }
    }
    models_assets
}

Making the Spawner Attach Components

Now update the spawner function to actually attach Pickable components when entities are created. Find the create_spawner function in assets.rs and add cases for pickable items:

// src/map/assets.rs - Update create_spawner function to handle pickables

fn create_spawner(
    tile_type: Option<TileType>,
    pickable: Option<ItemKind>,
) -> fn(&mut EntityCommands) {
    match (tile_type, pickable) {
        // Tile types without pickable
        (Some(TileType::Dirt), None) => |e: &mut EntityCommands| {
            e.insert(TileMarker::new(TileType::Dirt));
        },
        (Some(TileType::Grass), None) => |e: &mut EntityCommands| {
            e.insert(TileMarker::new(TileType::Grass));
        },
        (Some(TileType::YellowGrass), None) => |e: &mut EntityCommands| {
            e.insert(TileMarker::new(TileType::YellowGrass));
        },
        (Some(TileType::Water), None) => |e: &mut EntityCommands| {
            e.insert(TileMarker::new(TileType::Water));
        },
        (Some(TileType::Shore), None) => |e: &mut EntityCommands| {
            e.insert(TileMarker::new(TileType::Shore));
        },
        (Some(TileType::Tree), None) => |e: &mut EntityCommands| {
            e.insert(TileMarker::new(TileType::Tree));
        },
        (Some(TileType::Rock), None) => |e: &mut EntityCommands| {
            e.insert(TileMarker::new(TileType::Rock));
        },
        (Some(TileType::Empty), None) => |e: &mut EntityCommands| {
            e.insert(TileMarker::new(TileType::Empty));
        },

        // Pickable plants (with grass tile type)
        (Some(TileType::Grass), Some(ItemKind::Plant1)) => |e: &mut EntityCommands| {
            e.insert((TileMarker::new(TileType::Grass), Pickable::new(ItemKind::Plant1)));
        },
        (Some(TileType::Grass), Some(ItemKind::Plant2)) => |e: &mut EntityCommands| {
            e.insert((TileMarker::new(TileType::Grass), Pickable::new(ItemKind::Plant2)));
        },
        (Some(TileType::Grass), Some(ItemKind::Plant3)) => |e: &mut EntityCommands| {
            e.insert((TileMarker::new(TileType::Grass), Pickable::new(ItemKind::Plant3)));
        },
        (Some(TileType::Grass), Some(ItemKind::Plant4)) => |e: &mut EntityCommands| {
            e.insert((TileMarker::new(TileType::Grass), Pickable::new(ItemKind::Plant4)));
        },

        // Default: no components
        _ => |_: &mut EntityCommands| {},
    }
}

Marking Props as Pickable

Finally, open src/map/rules.rs. First, add the import at the top:

// src/map/rules.rs - Add to the imports section
use crate::inventory::ItemKind;

Now find the build_props_layer function. This is where decorative objects like plants are defined. Add .with_pickable() to make them collectible:

// src/map/rules.rs - Update the plants section in build_props_layer

// Plants - make them all pickable
terrain_model_builder.create_model(
    plant_prop.clone(), 
    vec![SpawnableAsset::new("plant_1")
        .with_tile_type(TileType::Grass)
        .with_pickable(ItemKind::Plant1)  // Add this line
    ]
);
terrain_model_builder.create_model(
    plant_prop.clone(), 
    vec![SpawnableAsset::new("plant_2")
        .with_tile_type(TileType::Grass)
        .with_pickable(ItemKind::Plant2)  // Add this line
    ]
);
terrain_model_builder.create_model(
    plant_prop.clone(), 
    vec![SpawnableAsset::new("plant_3")
        .with_tile_type(TileType::Grass)
        .with_pickable(ItemKind::Plant3)  // Add this line
    ]
);
terrain_model_builder.create_model(
    plant_prop.clone(), 
    vec![SpawnableAsset::new("plant_4")
        .with_tile_type(TileType::Grass)
        .with_pickable(ItemKind::Plant4)  // Add this line
    ]
);

What’s happening here?

We’re using the builder pattern to configure each spawnable asset. .with_tile_type(TileType::Grass) says “this is grass for collision purposes,” and .with_pickable(ItemKind::Plant1) says “the player can collect this as a Plant1 item.”

Run your game:

cargo run

Walk near a plant or mushroom. It should disappear, and you’ll see a log message:

 Picked up Herb (total: 1) — inventory: Herb: 1
 Picked up Flower (total: 1) — inventory: Flower: 1, Herb: 1
 Picked up Herb (total: 2) — inventory: Flower: 1, Herb: 2

Zooming In and Following the Player

Right now, our game window shows the entire map at once. While functional, this has no sense of exploration. You can see everything at a glance, removing the mystery

Let’s zoom in to show only part of the map, making everything larger and more detailed. But this creates a new problem: if the camera stays fixed and only shows part of the map, the player can walk off camera view and disappear!

So we need two changes:

First, scale up the world (larger tiles and sprites) for a zoomed-in view
Then, make the camera smoothly follow the player to keep them on screen

We need three things:

Updated configuration - Bigger tiles, player scale, and camera settings
Map generation updates - Scale sprites 2× larger
Camera system - Logic to smoothly track the player

Updating the Config

Our config.rs file already has player, pickup, and map modules. Let’s add camera configuration.

Open src/config.rs and add this new module after the map module: I

// src/config.rs - Add this after the map module

/// Camera configuration
pub mod camera {
    /// How fast the camera interpolates toward the player (higher = snappier)
    pub const CAMERA_LERP_SPEED: f32 = 6.0;
    
    /// Z position for the camera (must be high to see all layers)
    pub const CAMERA_Z: f32 = 1000.0;
}

Why these values?

CAMERA_LERP_SPEED controls how quickly the camera catches up to the player. A value of 6.0 means the camera closes 60% of the distance each second. Higher values make the camera snappier (instantly follows), lower values make it lag behind (cinematic feel).

CAMERA_Z must be high enough to see all game layers. Our player is around Z=20, props are around Z=4, and we need the camera above everything to render the scene.

What’s “lerp”?

“Lerp” is short for linear interpolation. It’s a smooth transition between two values. Instead of jumping from point A to point B instantly, lerp gradually moves from A to B over time.

Think of it like this: if the camera is at position (0, 0) and the player is at (100, 0), with a lerp factor of 0.6, the camera moves to (60, 0) in the first frame. Next frame, the player is still at (100, 0), but the camera is at (60, 0), so it moves 60% of the remaining distance (40 units) to (84, 0). It keeps closing the gap smoothly until it catches up.

We also need to update some existing values for better scaling. While we’re in config.rs, let’s update the player and map configurations:

// src/config.rs - Update the player module

/// Player-related configuration
pub mod player {
    /// Collision radius for the player's collider (in world units)
    pub const COLLIDER_RADIUS: f32 = 24.0; // Line update alert
    
    /// Z-position for player rendering (above terrain, below UI)
    pub const PLAYER_Z_POSITION: f32 = 20.0;
    
    /// Visual scale of the player sprite
    pub const PLAYER_SCALE: f32 = 1.2; // Line update alert (was 0.8)
}

Now update the map module:

// src/config.rs - Update the map module

/// Map/terrain configuration
pub mod map {
    /// Size of a single tile in world units (64px base * 1.0 scale = 64)
    /// NOTE: This must match TILE_SIZE in generate.rs!
    pub const TILE_SIZE: f32 = 64.0; // Line update alert (was 32.0)
    
    /// Grid dimensions
    pub const GRID_X: u32 = 25;
    pub const GRID_Y: u32 = 18;
    
    /// Z-height of each layer (used for Y-based depth sorting)
    pub const NODE_SIZE_Z: f32 = 1.0; // Add this line
}

Updating Map Generation

Now we need to update src/map/generate.rs to use our centralized config values and scale up the sprites.

Open src/map/generate.rs and make these changes:

1. Update the imports to use config values:
We now import GRID_X, GRID_Y, NODE_SIZE_Z, and TILE_SIZE from config instead of defining them locally

// src/map/generate.rs - Update imports
use bevy_procedural_tilemaps::prelude::*;
use bevy::prelude::*;

use crate::config::map::{GRID_X, GRID_Y, NODE_SIZE_Z, TILE_SIZE}; // Line update alert
use crate::map::{
    assets::{load_assets, prepare_tilemap_handles},
    rules::build_world,
};

2. Delete these local constants (we’re using config values now):

// src/map/generate.rs 
// DELETE THESE LINES:
// DELETE  pub const GRID_X: u32 = 25;
// DELETE  pub const GRID_Y: u32 = 18;
// DELETE  pub const TILE_SIZE: f32 = 32.;

3. Delete the map_pixel_dimensions function (no longer needed):

// src/map/generate.rs 
// DELETE THIS ENTIRE FUNCTION:
// DELETE pub fn map_pixel_dimensions() -> Vec2 {
// DELETE     Vec2::new(TILE_SIZE * GRID_X as f32, TILE_SIZE * GRID_Y as f32)
// DELETE }

4. Update NODE_SIZE to use the config constant:
Uses NODE_SIZE_Z from config for consistency

// src/map/generate.rs 

// BEFORE:
const NODE_SIZE: Vec3 = Vec3::new(TILE_SIZE, TILE_SIZE, 1.);

// AFTER:
const NODE_SIZE: Vec3 = Vec3::new(TILE_SIZE, TILE_SIZE, NODE_SIZE_Z); // Line update alert

5. Update ASSETS_SCALE to 2× for larger sprites:

Change from Vec3::ONE (1.0, 1.0, 1.0) to Vec3::new(2.0, 2.0, 1.0) to scale sprites 2× larger

Our tilemap uses 32px sprites but we’re rendering them at 64px. The 2× scale factor in ASSETS_SCALE makes this happen, creating the zoomed-in view.

// src/map/generate.rs 

// BEFORE:
const ASSETS_SCALE: Vec3 = Vec3::ONE;

// AFTER:
const ASSETS_SCALE: Vec3 = Vec3::new(2.0, 2.0, 1.0); // Line update alert

Building the Camera System

Create a new folder src/camera/ and add src/camera/camera.rs:

// src/camera/camera.rs
use bevy::prelude::*;

use crate::characters::input::Player;
use crate::config::camera::{CAMERA_LERP_SPEED, CAMERA_Z};

/// Marker component for the main game camera.
#[derive(Component)]
pub struct MainCamera;

/// Spawn the main 2D camera.
pub fn setup_camera(mut commands: Commands) {
    commands.spawn((Camera2d::default(), MainCamera));
}

/// Smoothly follow the player with the camera.
///
/// Uses linear interpolation for smooth movement and snaps to pixel boundaries
/// to prevent subpixel rendering artifacts (grid shimmer).
pub fn follow_camera(
    time: Res<Time>,
    player_query: Query<&Transform, (With<Player>, Changed<Transform>)>,
    mut camera_query: Query<&mut Transform, (With<MainCamera>, Without<Player>)>,
) {
    // The Changed filter in player_query means this system only processes
    // when the player has moved - Bevy filters it at the query level
    let Some(player_transform) = player_query.iter().next() else {
        return;
    };

    let Ok(mut camera_transform) = camera_query.single_mut() else {
        return;
    };

    let player_pos = player_transform.translation.truncate();
    let camera_pos = camera_transform.translation.truncate();

    // Early exit if camera is already very close (within 0.5 pixels)
    let distance = player_pos.distance(camera_pos);
    if distance < 0.5 {
        return;
    }

    // Smooth interpolation toward player
    let lerp_factor = (CAMERA_LERP_SPEED * time.delta_secs()).clamp(0.0, 1.0);
    let new_pos = camera_pos.lerp(player_pos, lerp_factor);

    // Snap to pixel boundaries to prevent grid shimmer
    camera_transform.translation.x = new_pos.x.round();
    camera_transform.translation.y = new_pos.y.round();
    camera_transform.translation.z = CAMERA_Z;
}

Breaking it down:

MainCamera marker: Just like we use Player to identify the player entity, we use MainCamera to find the camera entity.

setup_camera: Spawns a 2D camera with the MainCamera marker. This runs once at startup.

follow_camera: This is where the magic happens. Let’s dissect it:

Changed filter: Changed in the query definition means Bevy only calls this system when the player’s transform has changed. This is a query-level optimization - if the player hasn’t moved, Bevy won’t even run this function. No movement? No wasted CPU cycles.
Early exits: If there’s no player or no camera, bail out early. Also, if the camera is already within 0.5 pixels of the player, don’t bother moving it.
Lerp calculation: We calculate how much to move based on CAMERA_LERP_SPEED and the time since last frame (time.delta_secs()). This gives us smooth movement regardless of frame rate.
Pixel snapping: .round() snaps the position to whole pixels. Without this, the camera can land on fractional pixel coordinates (like 10.3), causing the grid to look jittery. Snapping prevents this “shimmer” effect.

Why clamp lerp_factor?

If the frame rate is very slow (say, 2 FPS), delta_secs() could be 0.5 seconds. Multiplying by CAMERA_LERP_SPEED (6.0) gives 3.0, which would overshoot. .clamp(0.0, 1.0) ensures we never move more than 100% of the distance in a single frame.

Camera Module

Now create src/camera/mod.rs to expose the camera systems:

// src/camera/mod.rs
mod camera;

use bevy::prelude::*;
use crate::state::GameState;

// Re-export public items
pub use camera::MainCamera;

/// Plugin for camera systems.
pub struct CameraPlugin;

impl Plugin for CameraPlugin {
    fn build(&self, app: &mut App) {
        app.add_systems(
                Startup,
                camera::setup_camera,
            )
            .add_systems(
                Update,
                camera::follow_camera.run_if(in_state(GameState::Playing)),
            );
    }
}

What’s happening:

The CameraPlugin bundles our camera systems:

setup_camera runs once at Startup to spawn the camera
follow_camera runs every frame during Update, but only when GameState::Playing

Why gate on GameState::Playing?

During the Loading state, the player entity might not exist yet. Running follow_camera would cause errors. By using .run_if(in_state(GameState::Playing)), we ensure the follow system only runs when the game is actually playing.

Integrating the Camera

Now we wire everything together in main.rs. But first, we need to remove the old camera setup.

Open src/main.rs. Find and delete the setup_camera function at the bottom:

// src/main.rs - DELETE this entire function
//DELETE fn setup_camera(mut commands: Commands) {
//DELETE     commands.spawn(Camera2d);
//DELETE }

Now update the module declarations and imports:

// src/main.rs - Update module declarations at the top
mod map;
mod characters;
mod state; 
mod collision;
mod config;
mod inventory;
mod camera; // Add this line

Update the imports to include the CameraPlugin:

// src/main.rs - Update imports
use bevy::{
    prelude::*,
    window::{MonitorSelection, Window, WindowMode, WindowPlugin}, // Line update alert
};

use bevy_procedural_tilemaps::prelude::*;

use crate::camera::CameraPlugin; // Add this line
use crate::map::generate::setup_generator; // Line update alert - remove map_pixel_dimensions

Now update the main function to use the CameraPlugin instead of the old setup_camera:

// src/main.rs - Update the main function
fn main() {
    App::new()
        .insert_resource(ClearColor(Color::BLACK)) // Line update alert
        .add_plugins(
            DefaultPlugins
                .set(AssetPlugin {
                    file_path: "src/assets".into(),
                    ..default()
                })
                .set(WindowPlugin {
                    primary_window: Some(Window {
                        title: "Bevy Game".into(),
                        mode: WindowMode::BorderlessFullscreen(MonitorSelection::Current), // Add this line
                        ..default()
                    }),
                    ..default()
                })
                .set(ImagePlugin::default_nearest()),
        )
        .add_plugins(ProcGenSimplePlugin::<Cartesian3D, Sprite>::default())
        .add_plugins(state::StatePlugin)
        .add_plugins(CameraPlugin) // Add this line
        .add_plugins(inventory::InventoryPlugin)
        .add_plugins(collision::CollisionPlugin)
        .add_plugins(characters::CharactersPlugin)
        .add_systems(Startup, setup_generator) // Line update alert - remove setup_camera here
        .run();
}

What changed:

Added mod camera; to declare the camera module
Imported CameraPlugin and window mode types
Added .add_plugins(CameraPlugin) to the app
Removed setup_camera from the Startup systems (it’s now inside CameraPlugin)
Changed to borderless fullscreen mode - perfect for our zoomed-in camera view! It uses your full screen, making the zoomed world feel immersive without window borders getting in the way
Changed background to black for a cleaner look

Run your game:

cargo run

Walk around using the arrow keys. Notice how the camera smoothly follows your character instead of staying fixed. The camera should feel responsive but not jarring - that’s the lerp in action!

The Impatient Programmer’s Guide to Bevy and Rust: Chapter 4 - Let There Be Collisions

2025-12-16T10:00:00+00:00

By the end of this chapter, your player will interact with the world properly, no more walking through trees, water, or rocks. We’ll implement z-ordering so they can walk behind objects, giving your 2D game true depth. Also, you’ll build a collision visualizer for debugging.

Prerequisites: This is Chapter 4 of our Bevy tutorial series. Join our community for updates on new releases. Before starting, complete Chapter 1: Let There Be a Player, Chapter 2: Let There Be a World, and Chapter 3: Let The Data Flow, or clone the Chapter 3 code from this repository to follow along.

Systems Running When They Shouldn’t

In Chapter 3, we built a character system that loads sprite data from a .ron file. But there’s a problem in how we handle the initialization.

The spawn_player system runs once at startup. It spawns the player entity and begins loading the character data file. So far, so good.

But then initialize_player_character runs every single frame, checking if the assets have finished loading:

We have a polling pattern that repeatedly checks if something is ready:

The system runs every frame forever with wasted checks while loading, one useful execution, then infinite no-ops causing performance waste, code clutter, and making the code difficult to extend.

Systems That Run Only When Needed

Startup and Update we use to trigger our systems are schedules. Bevy’s way of organizing when systems run. Startup runs once at launch, Update runs every frame.

But what if we need systems that run at specific moments? Not every frame, not just at startup, but exactly when something happens like when assets finish loading, or when the player pauses the game.

State-Based Schedules

The solution is to organize our game into distinct phases. We call these phases states: Loading, Playing, and Paused. Each state represents a different mode of the game.

When the game transitions from one state to another (say, from Loading to Playing), Bevy provides special schedules that run exactly once:

OnEnter - Runs when entering a state
OnExit - Runs when leaving a state

This is how we eliminate polling. Instead of initialize_player_character checking every frame “Are assets loaded yet?”, we attach it to OnExit(Loading). When assets finish loading and we leave the Loading state, Bevy runs it exactly once.

Implementing Game States

Let’s build a state management module with loading screens and game pause functionality. Create the folder state inside the src folder.

Defining Game States

What states do we need?

Think about your game’s lifecycle. Right now, when the game starts:

Assets need time to load from disk
Once loaded, gameplay begins
Players might want to pause

These are three distinct phases, each needing different systems:

Loading: Show loading screen, check if assets ready, don’t run gameplay
Playing: Run movement/animation, hide loading screen, allow pausing
Paused: Show pause menu, stop gameplay, allow un-pausing

Let’s define these as an enum:

Create src/state/game_state.rs:

// src/state/game_state.rs
use bevy::prelude::*;

#[derive(States, Default, Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum GameState {
    #[default]
    Loading,
    Playing,
    Paused,
}

What’s the States macro?

The #[derive(States)] macro implements the States trait, which tells Bevy:

This enum represents game phases where only one can be active at a time
Bevy should track which state is active
Systems can be gated to run only in specific states
State transitions should trigger OnEnter/OnExit schedules

The #[default] attribute marks which state the game starts in. Here, Bevy initializes the state to the default value (Loading in our case).

Loading Screen

Let’s create a loading screen with a full-screen dark background, animated “Loading…” text.

Create src/state/loading.rs

// src/state/loading.rs
use bevy::prelude::*;

#[derive(Component)]
pub struct LoadingScreen;

#[derive(Component)]
pub struct LoadingText;

pub fn spawn_loading_screen(mut commands: Commands) {
    commands.spawn((
        LoadingScreen,
        Node {
            width: Val::Percent(100.0),
            height: Val::Percent(100.0),
            justify_content: JustifyContent::Center,
            align_items: AlignItems::Center,
            ..default()
        },
        BackgroundColor(Color::srgb(0.1, 0.1, 0.15)),
    )).with_children(|parent| {
        parent.spawn((
            LoadingText,
            Text::new("Loading..."),
            TextFont {
                font_size: 48.0,
                ..default()
            },
            TextColor(Color::WHITE),
        ));
    });
    
    info!("Loading screen spawned");
}

What’s happening:

LoadingScreen and LoadingText are marker components to identify our UI entities
Node creates a full-screen container (100% width and height)
justify_content and align_items centered means text appears in the middle
.with_children() spawns the text as a child of the background

Now append the animation function to the same file:

// Append to src/state/loading.rs
pub fn animate_loading(
    time: Res<Time>,
    mut query: Query<&mut Text, With<LoadingText>>,
) {
    for mut text in query.iter_mut() {
        let dots = (time.elapsed_secs() * 2.0) as usize % 4;
        **text = format!("Loading{}", ".".repeat(dots));
    }
}

This animates the text: “Loading” → “Loading.” → “Loading..” → “Loading…” (cycling through 0-3 dots).

What’s **text, is this like double dereferencing?

Yes! When we call .iter_mut(), Bevy wraps our &mut Text in a special type that tracks changes. The first * unwraps that to get &mut Text, and the second * dereferences the reference to reach the actual Text value we can modify.

Finally, append the despawn function:

// Append to src/state/loading.rs
pub fn despawn_loading_screen(
    mut commands: Commands,
    query: Query<Entity, With<LoadingScreen>>,
) {
    for entity in query.iter() {
        commands.entity(entity).despawn();
    }
    
    info!("Loading screen despawned");
}

Why despawn?

When we transition to Playing state, the loading screen should disappear. Without despawning, the UI entities would remain in the world forever, cluttering memory and rendering on top of the game. The .despawn() function removes the loading screen entity. Since LoadingText is a child (via .with_children()), Bevy automatically removes it too.

Now let’s create a pause menu that shows a semi-transparent overlay with “PAUSED” text when the player presses Escape, and hides when they press it again.

Create src/state/pause.rs:

// src/state/pause.rs
use bevy::prelude::*;

#[derive(Component)]
pub struct PauseMenu;

pub fn spawn_pause_menu(mut commands: Commands) {
    commands.spawn((
        PauseMenu,
        Node {
            width: Val::Percent(100.0),
            height: Val::Percent(100.0),
            justify_content: JustifyContent::Center,
            align_items: AlignItems::Center,
            ..default()
        },
        BackgroundColor(Color::srgba(0.0, 0.0, 0.0, 0.7)),
    )).with_children(|parent| {
        parent.spawn((
            Text::new("PAUSED\n\nPress ESC to resume"),
            TextFont {
                font_size: 36.0,
                ..default()
            },
            TextColor(Color::WHITE),
            TextLayout::new_with_justify(Justify::Center),
        ));
    });
    
    info!("Pause menu spawned");
}

pub fn despawn_pause_menu(
    mut commands: Commands,
    query: Query<Entity, With<PauseMenu>>,
) {
    for entity in query.iter() {
        commands.entity(entity).despawn();
    }
    
    info!("Pause menu despawned");
}

State Plugin

Now we’ll create the StatePlugin that wires everything together. We’ll build it piece by piece.

Create src/state/mod.rs.

// src/state/mod.rs
mod game_state;
mod loading;
mod pause;

use bevy::prelude::*;
use crate::characters::spawn::CharactersListResource;
use crate::characters::config::CharactersList;

pub use game_state::GameState;

pub struct StatePlugin;

impl Plugin for StatePlugin {
    fn build(&self, app: &mut App) {
        app
            .init_state::<GameState>()
            
            // Loading state systems
            .add_systems(OnEnter(GameState::Loading), loading::spawn_loading_screen)
            .add_systems(Update, (
                check_assets_loaded,
                loading::animate_loading,
            ).run_if(in_state(GameState::Loading)))
            .add_systems(OnExit(GameState::Loading), (
                loading::despawn_loading_screen,
                crate::characters::spawn::initialize_player_character,
            ))
                // Pause state systems
            .add_systems(OnEnter(GameState::Paused), pause::spawn_pause_menu)
            .add_systems(OnExit(GameState::Paused), pause::despawn_pause_menu)
            
            // Pause toggle (works in Playing or Paused states)
            .add_systems(Update, 
                toggle_pause.run_if(in_state(GameState::Playing).or(in_state(GameState::Paused)))
            );
    }
}

fn check_assets_loaded(
    characters_list_res: Option<Res<CharactersListResource>>,
    characters_lists: Res<Assets<CharactersList>>,
    mut next_state: ResMut<NextState<GameState>>,
) {
    let Some(res) = characters_list_res else {
        return;
    };
    
    if characters_lists.get(&res.handle).is_some() {
        info!("Assets loaded, transitioning to Playing!");
        next_state.set(GameState::Playing);
    }
}

fn toggle_pause(
    input: Res<ButtonInput<KeyCode>>,
    current_state: Res<State<GameState>>,
    mut next_state: ResMut<NextState<GameState>>,
) {
    if input.just_pressed(KeyCode::Escape) {
        match current_state.get() {
            GameState::Playing => {
                info!("Game paused");
                next_state.set(GameState::Paused);
            }
            GameState::Paused => {
                info!("Game resumed");
                next_state.set(GameState::Playing);
            }
            _ => {}
        }
    }
}

What’s happening here?

We start by telling Bevy to track our custom GameState enum.

When the game starts and enters Loading state, OnEnter(GameState::Loading) runs spawn_loading_screen once, showing the loading UI.

While in Loading state, Update.run_if(in_state(GameState::Loading)) runs two systems one to check if assets are loaded and another to animate the loading text.

Once assets load, check_assets_loaded requests a transition to Playing state. When this happens, OnExit(GameState::Loading) triggers, running two systems that cleans up the loading UI and initialize the player. Now player initialization can happen only once since exiting from loading state is a one-time event.

For pausing, we added systems on OnEnter(GameState::Paused) and OnExit(GameState::Paused) to show and hide the pause menu. The toggle_pause function listens for the Escape key and switches between Playing and Paused states.

Our StatePlugin now orchestrates the entire game flow. The Loading state handles asset loading with visual feedback, and the Playing state will run gameplay systems. Later in this chapter, we’ll gate our gameplay systems to only run in the Playing state, which will freeze the game when paused. The beauty of this design is that systems automatically attach to state transitions, no polling, no wasted frames. Everything runs exactly when needed.

Now open src/characters/mod.rs and remove initialize_player_character from the Update schedule. Since we have already added it through StatePlugin.

// src/characters/mod.rs
impl Plugin for CharactersPlugin {
    fn build(&self, app: &mut App) {
        app.add_plugins(RonAssetPlugin::<CharactersList>::new(&["characters.ron"]))
            .init_resource::<spawn::CurrentCharacterIndex>()
            .add_systems(Startup, spawn::spawn_player)
            // REMOVE initialize_player_character from here!
            // It now runs in StatePlugin's OnExit(Loading)
            .add_systems(Update, (
                spawn::switch_character,
                movement::move_player,
                movement::update_jump_state,
                animation::animate_characters,
                animation::update_animation_flags,
            ));
    }
}

Integrating StatePlugin

Add the state module and plugin to src/main.rs:

// src/main.rs
mod characters;
mod map;
mod state;  // Add this

Important: Add StatePlugin BEFORE CharactersPlugin so the state system is initialized before character systems try to use it.

// Add state plugin inside main function of src/main.rs
        // Previous code as it is
        .add_plugins(ProcGenSimplePlugin::<Cartesian3D, Sprite>::default())
        .add_plugins(state::StatePlugin)  // Add BEFORE CharactersPlugin!
        .add_plugins(characters::CharactersPlugin)
        .add_systems(Startup, setup_camera)
        .run();

Run your game:

cargo run

You might not see the loading screen (assets load quickly, but you can manually add a delay if needed). The game starts and your character appears, ready to move. Press Escape to toggle the pause overlay. Note that at this point, the game will continue running in the background when paused, we’ll fix that later in the chapter by gating our gameplay systems to only run in the Playing state.

The State Pattern for Characters

We just used states to control our game flow (Loading → Playing → Paused). Now let’s apply the same pattern to something else: character behavior.

Have a look at out AnimationState component:

// Pseudo code, don't use
#[derive(Component, Default)]
pub struct AnimationState {
    pub is_moving: bool,
    pub was_moving: bool,
    pub is_jumping: bool,
    pub was_jumping: bool,
}

Four booleans tracking two pieces of information: what the character is doing now and what they were doing last frame. We needed was_moving and was_jumping to detect transitions like “just started jumping” or “just stopped moving”.

This works to help us with animation, but it has problems.

Too Many Boolean Flags

What if we add running? We’d need:

// Pseudo code, don't use
pub is_running: bool,
pub was_running: bool,

Attacking?

// Pseudo code, don't use
pub is_attacking: bool,
pub was_attacking: bool,

Soon our component is drowning in booleans, and our animation system is drowning in transition logic:

// Pseudo code, don't use
let just_started_moving = state.is_moving && !state.was_moving;
let just_stopped_moving = !state.is_moving && state.was_moving;
let just_started_jumping = state.is_jumping && !state.was_jumping;
let just_stopped_jumping = !state.is_jumping && state.was_jumping;
let just_started_running = state.is_running && !state.was_running;
// ... it keeps growing

Worse, what happens if is_moving and is_jumping are both true? Or is_running and is_attacking? Boolean flags don’t prevent impossible states.

A developer might accidentally set both flags, or forget to clear one when setting another. Your animation system then has to decide: which flag wins? You end up writing priority logic, and bugs creep in when the priorities aren’t consistent across systems.

The State Pattern Solution

Remember how GameState worked? We defined an enum with Loading, Playing, and Paused, and Bevy tracked which state we were in. We can apply the same idea to characters: define an enum of possible states, and let the current state determine behavior.

// Pseudo code, don't use
#[derive(Component, Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum CharacterState {
    #[default]
    Idle,
    Walking,
    Running,
    Jumping,
}

A character can only be in one state at a time. No more impossible combinations. No more boolean math.

Why This Is Better

1. Impossible states become impossible:

With an enum, the compiler enforces that the character is in exactly one state:

// Pseudo code, don't use
// With booleans: you can do this (but shouldn't!)
is_walking = true;
is_jumping = true;  // Now both are true - invalid!

// With enum: you can't have both true
let state = CharacterState::Walking;
// state is Walking. To jump, you must replace it:
let state = CharacterState::Jumping;  // Now it's only Jumping

The variable holds one value. You can’t be Walking and Jumping simultaneously. This approach is called making illegal states unrepresentable, a key principle in type-driven development. Instead of writing code to check for invalid combinations, you design your types so invalid combinations can’t exist.

2. Bevy detects changes for us:

Remember manually tracking was_moving and was_jumping? That was change detection done by hand. Bevy has this built in. When you use Changed, Bevy only runs your code when the state actually changes.

Your animation update system only runs when the character transitions between states. Your sound effect system only runs when entering a new state. Less code, fewer bugs, and we’ll use this later in the chapter.

3. Animation selection becomes a simple match:

With an enum, picking the right animation is straightforward. You match on the current state, and each state maps to exactly one animation. There’s no ambiguity, no priority logic, no “what if both flags are true?” dilemma.

// Pseudo code, don't use
let new_animation = match state {
    CharacterState::Idle | CharacterState::Walking => AnimationType::Walk,
    CharacterState::Running => AnimationType::Run,
    CharacterState::Jumping => AnimationType::Jump,
};

The compiler warns you if you forget to handle a state. If you later add a new state to the enum, every match statement becomes a compile error until you handle the new case. The compiler forces you to think through all possibilities.

Now let’s put this into practice and implement CharacterState.

Implementing Character States

Create a new file src/characters/state.rs:

characters/
├── config.rs
├── animation.rs
├── movement.rs
├── mod.rs
├── spawn.rs
├── state.rs  ← Create this

The CharacterState Enum

We need an enum that represents all possible states our character can be in:

// src/characters/state.rs
use bevy::prelude::*;

/// Character states. Only one can be active at a time.
#[derive(Component, Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum CharacterState {
    #[default]
    Idle,
    Walking,
    Running,
    Jumping,
}

Querying State with Methods

Earlier, we explained how boolean flags can create invalid combinations. Instead of tracking is_jumping and was_jumping flags separately, we now have a single CharacterState. But we still need to answer questions like “can this character jump right now?”

That’s where these query methods come in. They let us ask questions about the current state without maintaining separate flag variables:

// Append to src/characters/state.rs
impl CharacterState {
    /// Check if this is a grounded state (can jump from here)
    pub fn is_grounded(&self) -> bool {
        matches!(self, CharacterState::Idle | CharacterState::Walking | CharacterState::Running)
    }
}

This method replaces boolean flag logic for jump control. Instead of tracking an is_jumping flag and checking it manually, we query the state. The logic is simple: you can only jump when grounded (Idle, Walking, or Running). You can’t jump while already in the Jumping state.

What’s matches!?

The matches! macro checks if a value matches a pattern. matches!(self, CharacterState::Idle) returns true if self is Idle, false otherwise. The | means “or” so matches!(self, CharacterState::Walking | CharacterState::Running) checks if it’s either Walking or Running.

Animation Refactoring

Now we’ll refactor animation.rs to use our new state-based approach. While we’re at it, let’s also clean up a code organization issue: currently, AnimationController stores both the current animation type and the facing direction. But these are owned by different systems, facing decides direction, animation decides the clip. Separating them makes each system’s responsibility clearer.

First, create a new file src/characters/facing.rs. By making Facing its own component, the movement system owns direction updates, and the animation system focuses on sprite animation.

// src/characters/facing.rs
use bevy::prelude::*;

/// The direction a character is facing.
/// Separate from movement - character can face one way while moving another.
#[derive(Component, Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Facing {
    Up,
    Left,
    #[default]
    Down,
    Right,
}

impl Facing {
    pub fn from_velocity(velocity: Vec2) -> Self {
        if velocity.x.abs() > velocity.y.abs() {
            if velocity.x > 0.0 { Facing::Right } else { Facing::Left }
        } else {
            if velocity.y > 0.0 { Facing::Up } else { Facing::Down }
        }
    }
    
    /// Helper to map direction to row offset (0, 1, 2, 3)
    pub(crate) fn direction_index(self) -> usize {
        match self {
            Facing::Up => 0,
            Facing::Left => 1,
            Facing::Down => 2,
            Facing::Right => 3,
        }
    }
}

Expose both state and facing in src/characters/mod.rs:

// src/characters/mod.rs
pub mod config;
pub mod animation;
pub mod movement;
pub mod state; // Add this line
pub mod facing;  // Add this line

Open src/characters/animation.rs. We’ll update it section by section.

First, delete the old Facing enum and AnimationState struct. We’ll be using CharacterState instead.

// src/characters/animation.rs - Delete the following sections 

// DELETE this (Facing moved to facing.rs)
pub enum Facing { ... }
impl Facing { ... }

// DELETE this (AnimationState replaced by CharacterState)
pub struct AnimationState {
    pub is_moving: bool,
    ...
}

Remove facing from AnimationController since it’s now a separate component. Also derive Default macro for AnimationController.

// src/characters/animation.rs - Update AnimationController
#[derive(Component, Default)] // Line update alert
pub struct AnimationController {
    pub current_animation: AnimationType,
    // Facing is removed now, line update alert
}

You’ll also need to delete the old manual Default implementation for AnimationController. Previously, it looked like this:

// DELETE the following old implementation from src/characters/animation.rs
impl Default for AnimationController {
    fn default() -> Self {
        Self {
            current_animation: AnimationType::Walk,
            facing: Facing::Down, 
        }
    }
}

Delete it entirely. Since AnimationController now only has one field (current_animation), we need AnimationType to have a default value. Add #[derive(Default)] to AnimationType and mark Walk as the default:

// src/characters/config.rs - Set default animation type to Walk
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, Default)] // Line update alert
pub enum AnimationType {
    #[default] // Line update alert
    Walk,
    Run,
    Jump
}

Now update the imports at the top of the file. Let’s add imports for CharacterState and Facing.

// src/characters/animation.rs - Update imports
use bevy::prelude::*;
use crate::characters::config::{CharacterEntry, AnimationType};
use crate::characters::state::CharacterState; // Line update alert
use crate::characters::facing::Facing; // Line update alert

Since we moved Facing out of AnimationController, get_clip can no longer access self.facing. We need to pass facing as a parameter. This is actually cleaner: the method now explicitly declares what data it needs:

// src/characters/animation.rs - Update get_clip signature
impl AnimationController {
    /// Get the animation clip for the current animation and facing direction.
    /// `facing` is passed in since it's now a separate component.
    pub fn get_clip(&self, config: &CharacterEntry, facing: Facing) -> Option<AnimationClip> {
        let def = config.animations.get(&self.current_animation)?;
        
        let row = if def.directional {
            def.start_row + facing.direction_index()
        } else {
            def.start_row
        };
        
        Some(AnimationClip::new(row, def.frame_count, config.atlas_columns))
    }
}

Delete update_animation_flags

We no longer need this function since we will be using Changed instead of manual tracking.

// src/characters/animation.rs - DELETE this entire function
pub fn update_animation_flags(...) { ... }

Replace Animation System

Here’s where the state pattern really pays off. The old animate_characters function manually tracked state changes with boolean flags. With CharacterState, Bevy’s Changed filter does this for us automatically.

Delete animate_characters entirely.

// src/characters/animation.rs - DELETE this entire function
pub fn animate_characters(...) { ... }

We’ll write one system that responds to state changes (using Changed), and another that does animation playback. This separation means state-change logic only runs when needed, not every frame.

System 1: Handle Character State Changes

This system runs only when CharacterState changes, using Bevy’s Changed filter. When triggered, it updates the animation type so the playback system knows which animation to play.

// src/characters/animation.rs - Add this new function
pub fn on_state_change_update_animation(
    mut query: Query<
        (&CharacterState, &mut AnimationController, &mut AnimationTimer),
        Changed<CharacterState>
    >,
) {
    for (state, mut controller, mut timer) in query.iter_mut() {
        // Select animation based on new state
        let new_animation = match state {
            CharacterState::Idle | CharacterState::Walking => AnimationType::Walk,
            CharacterState::Running => AnimationType::Run,
            CharacterState::Jumping => AnimationType::Jump,
        };
        
        // Only update and reset timer if animation actually changed
        if controller.current_animation != new_animation {
            controller.current_animation = new_animation;
            timer.0.reset();
        }
    }
}

What’s Changed?

This is the change detection we discussed earlier! The query only returns entities whose CharacterState changed since last frame. No manual tracking needed.

Why check controller.current_animation != new_animation if Changed already filters?

Because multiple states can map to the same animation. Look at the match: both Idle and Walking use AnimationType::Walk. If the player transitions from Idle to Walking, Changed fires (state changed), but the animation type stays Walk. Without this guard, we’d reset the timer and cause a visual stutter even though we’re playing the same animation.

System 2: Animation Playback

While the first system picks which animation to play when state changes, this one handles the frame-by-frame playback. Together they form a complete animation pipeline: state changes set up the animation, and this system keeps it running.

// src/characters/animation.rs - Add this new function
pub fn animations_playback(
    time: Res<Time>,
    mut query: Query<(
        &CharacterState,
        &Facing,
        &AnimationController,
        &mut AnimationTimer,
        &mut Sprite,
        &CharacterEntry,
    )>,
) {
    for (state, facing, controller, mut timer, mut sprite, config) in query.iter_mut() {
        // Don't animate when idle
        if *state == CharacterState::Idle {
            // Ensure idle sprite is at frame 0
            if let Some(atlas) = sprite.texture_atlas.as_mut() {
                if let Some(clip) = controller.get_clip(config, *facing) {
                    if atlas.index != clip.start() {
                        atlas.index = clip.start();
                    }
                }
            }
            continue;
        }
        
        let Some(atlas) = sprite.texture_atlas.as_mut() else { continue; };
        let Some(clip) = controller.get_clip(config, *facing) else { continue; };
        let Some(anim_def) = config.animations.get(&controller.current_animation) else { continue; };
        
        // Safety: If we somehow ended up on a frame outside our clip, reset.
        if !clip.contains(atlas.index) {
            atlas.index = clip.start();
            timer.0.reset();
        }
        
        // Update timer duration if needed
        let expected_duration = std::time::Duration::from_secs_f32(anim_def.frame_time);
        if timer.0.duration() != expected_duration {
            timer.0.set_duration(expected_duration);
        }
        
        // Advance animation
        timer.tick(time.delta());
        if timer.just_finished() {
            atlas.index = clip.next(atlas.index);
        }
    }
}

Completing the State-Based Refactoring

We’ve updated the animation system to use CharacterState instead of boolean flags. But where does CharacterState get set? Right now, our movement.rs still uses the old approach, it directly modifies Transform and sets boolean flags in AnimationState. We need to refactor it to work with our new state-based design.

Look at the current movement.rs. It does three things at once:

Reads input (arrow keys, shift, space)
Moves the character on screen
Decides which animation to play using boolean flags

This mixing of concerns made sense before, but now that we have CharacterState, we can separate these responsibilities. We’ll split movement.rs into:

input.rs - Reads keyboard input and decides what the character should do
physics.rs - Handles moving the character based on velocity

This separation means the animation system we just built will work automatically. When input changes CharacterState, our on_state_change_update_animation system reacts. When input sets Velocity, our physics system moves the entity. Each piece focuses on one job.

Create src/characters/physics.rs:

// src/characters/physics.rs
use bevy::prelude::*;
use super::{state::CharacterState, config::CharacterEntry};

/// Linear velocity in world units per second.
/// Systems that want to move an entity modify this.
/// A physics system reads this to update Transform.
#[derive(Component, Debug, Clone, Copy, Default, Deref, DerefMut)]
pub struct Velocity(pub Vec2);

impl Velocity {
    pub const ZERO: Self = Self(Vec2::ZERO);
    
    pub fn is_moving(&self) -> bool {
        self.0 != Vec2::ZERO
    }
}

Now add the velocity calculation based on state:

// Append to src/characters/physics.rs

/// Calculate velocity based on character state, direction, and configuration.
pub fn calculate_velocity(
    state: CharacterState,
    direction: Vec2,
    character: &CharacterEntry,
) -> Velocity {
    match state {
        CharacterState::Idle => Velocity::ZERO,
        CharacterState::Jumping => Velocity::ZERO,  // No movement during jump
        CharacterState::Walking => {
            Velocity(direction.normalize_or_zero() * character.base_move_speed)
        }
        CharacterState::Running => {
            Velocity(direction.normalize_or_zero() * character.base_move_speed * character.run_speed_multiplier)
        }
    }
}

Notice how CharacterState directly determines velocity. No boolean flags, no conditionals about is_jumping && !is_moving. The state tells us everything we need to know.

Finally, add the system that actually moves the character. It reads the velocity and updates the character’s position on screen:

// Append to src/characters/physics.rs

/// Applies velocity to transform. Pure physics, no game logic.
pub fn apply_velocity(
    time: Res<Time>,
    mut query: Query<(&Velocity, &mut Transform)>,
) {
    for (velocity, mut transform) in query.iter_mut() {
        if velocity.is_moving() {
            transform.translation += velocity.0.extend(0.0) * time.delta_secs();
        }
    }
}

This system knows nothing about input, characters, or states. It just moves things based on their velocity. Add any entity with Velocity and Transform, and it moves automatically.

Refactoring Player Input

Now for the second half of splitting movement.rs. We have physics handling the “how to move” part. Now we need input handling for the “what the player wants to do” part.

This is where we connect everything together. The input system will:

Read keyboard input
Update CharacterState (which triggers our animation system via Changed)
Set Velocity (which our physics system uses to move the entity)

Create src/characters/input.rs. This replaces the input-handling parts of movement.rs.

// src/characters/input.rs
use bevy::prelude::*;
use super::{
    state::CharacterState,
    physics::Velocity,
    facing::Facing,
    config::CharacterEntry,
    animation::{AnimationController, AnimationTimer},
};

#[derive(Component)]
pub struct Player;

We moved the Player marker component here since input handling is player-specific.

// Append to src/characters/input.rs

/// Read directional input and return a direction vector
fn read_movement_input(input: &ButtonInput<KeyCode>) -> Vec2 {
    const MOVEMENT_KEYS: [(KeyCode, Vec2); 4] = [
        (KeyCode::ArrowLeft, Vec2::NEG_X),
        (KeyCode::ArrowRight, Vec2::X),
        (KeyCode::ArrowUp, Vec2::Y),
        (KeyCode::ArrowDown, Vec2::NEG_Y),
    ];
    
    MOVEMENT_KEYS.iter()
        .filter(|(key, _)| input.pressed(*key))
        .map(|(_, dir)| *dir)
        .sum()
}

This is the same input reading we had before, just isolated into its own function.

State Machine Logic

Now we need to decide what state the character should be in based on that input. Remember earlier we said “the state tells us everything we need to know”? This is where we translate raw input into meaningful state transitions.

Instead of scattered if statements that set boolean flags (is_moving = true, is_jumping = true), we have one function that returns the new state:

// Append to src/characters/input.rs

fn determine_new_state(
    current: CharacterState,
    direction: Vec2,
    is_running: bool,
    wants_jump: bool,
) -> CharacterState {
    match current {
        // Can't transition out of jumping until it completes
        CharacterState::Jumping => CharacterState::Jumping,
        
        // Jump takes priority when grounded
        _ if wants_jump && current.is_grounded() => CharacterState::Jumping,
        
        // Movement states
        _ if direction != Vec2::ZERO => {
            if is_running { CharacterState::Running } else { CharacterState::Walking }
        }
        
        // Default to idle
        _ => CharacterState::Idle,
    }
}

What’s this strange pattern of having if conditions inside match?

This is called a match guard. The syntax _ if condition => means “match anything, but only if this condition is also true.” It combines pattern matching with boolean logic.

Why use it here?

We need to check two things: what state we’re currently in, and what the player is doing (moving, jumping, etc.). Match guards let us handle both in one clean expression. The _ means “any state not already matched above,” and the if adds the extra condition.

You can use this pattern when you need to match on one thing but also check something else that isn’t part of the enum itself.

Alright, the new approach puts all state transition logic in one function. You can read it top to bottom and understand the priority.

The Main Input Handler

We’ve built the helper functions: read_movement_input reads keys, determine_new_state decides the state. Now we need the main system that ties them together and actually updates the entity’s components.

This is the new version of the old move_player function from movement.rs. Instead of directly modifying Transform and AnimationController, it now updates CharacterState, Velocity, and Facing. Other systems react to these changes: the animation system responds to Changed, and the physics system reads Velocity to move the entity.

The function works in four steps:

Read input - Check which keys are pressed (arrows for direction, shift for running, space for jump)
Update facing - If moving, update the facing direction so the character looks where they’re going
Determine new state - Use the state machine to figure out the next state based on current state and input
Calculate velocity - Based on the new state, calculate how fast and which direction to move

// Append to src/characters/input.rs

/// Reads player input and updates movement-related components.
pub fn handle_player_input(
    input: Res<ButtonInput<KeyCode>>,
    mut query: Query<(
        &mut CharacterState,
        &mut Velocity,
        &mut Facing,
        &CharacterEntry,
    ), With<Player>>,
) {
    let Ok((mut state, mut velocity, mut facing, character)) = query.single_mut() else {
        return;
    };
    
    // Step 1: Read what keys are pressed
    let direction = read_movement_input(&input);
    let is_running = input.pressed(KeyCode::ShiftLeft) || input.pressed(KeyCode::ShiftRight);
    let wants_jump = input.just_pressed(KeyCode::Space);
    
    // Step 2: Update facing direction (which way the character looks)
    if direction != Vec2::ZERO {
        let new_facing = Facing::from_velocity(direction);
        if *facing != new_facing {
            *facing = new_facing;
        }
    }
    
    // Step 3: Use our state machine to determine the new state
    // This calls the determine_new_state function we wrote earlier
    let new_state = determine_new_state(*state, direction, is_running, wants_jump);
    if *state != new_state {
        *state = new_state;  // This triggers Changed!
    }
    
    // Step 4: Calculate velocity based on state
    // Idle and Jumping = no movement, Walking/Running = movement
    *velocity = super::physics::calculate_velocity(*state, direction, character);
}

Handling Jump Completion

There’s one edge case our main input handler doesn’t cover. Look at determine_new_state, when the character is Jumping, it stays Jumping. But how does jumping ever end?

Unlike walking or running (which end when you release the key), jumping needs to complete its animation before transitioning back to idle. We need a separate system that watches for this:

// Append to src/characters/input.rs

/// Checks if jump animation completed and transitions back to idle
pub fn update_jump_state(
    mut query: Query<(
        &mut CharacterState,
        &Facing,
        &AnimationController,
        &AnimationTimer,
        &Sprite,
        &CharacterEntry,
    ), With<Player>>,
) {
    let Ok((mut state, facing, controller, timer, sprite, config)) = query.single_mut() else {
        return;
    };
    
    // Only check if currently jumping
    if *state != CharacterState::Jumping {
        return;
    }
    
    let Some(atlas) = sprite.texture_atlas.as_ref() else {
        return;
    };
    
    let Some(clip) = controller.get_clip(config, *facing) else {
        return;
    };
    
    // Check if jump animation has completed
    if clip.is_complete(atlas.index, timer.just_finished()) {
        *state = CharacterState::Idle;
    }
}

This system only runs meaningful logic when the player is jumping. It uses clip.is_complete() to check if the animation finished, then transitions to Idle. The state change triggers our on_state_change_update_animation system, which updates the animation to Walk.

Before we update mod.rs, we need to update spawn.rs. We moved Player to input.rs, and our new systems expect entities to have CharacterState, Velocity, and Facing components.

Update the imports at the top of src/characters/spawn.rs:

// src/characters/spawn.rs - Update imports
use bevy::prelude::*;
use crate::characters::animation::*;
use crate::characters::config::{CharacterEntry, CharactersList};
use crate::characters::input::Player;  // Changed from movement::Player
use crate::characters::state::CharacterState;  // Line update alert
use crate::characters::physics::Velocity;  // Line update alert
use crate::characters::facing::Facing;  // Line update alert

Then in initialize_player_character, update the components attached to the player entity.

// src/characters/spawn.rs - Inside initialize_player_character
// Update commands.entity(entity).insert((...)) function call
// Remove the line  AnimationState::default(), and add the following lines:
commands.entity(entity).insert((
    AnimationController::default(),
    CharacterState::default(),   // Line update alert
    Velocity::default(),         // Line update alert  
    Facing::default(),           // Line update alert
    AnimationTimer(Timer::from_seconds(DEFAULT_ANIMATION_FRAME_TIME, TimerMode::Repeating)),
    character_entry.clone(),
    sprite,
));

Now the player entity has all the components our refactored systems need: CharacterState for the animation system to react to, Velocity for the physics system to read, and Facing for sprite direction.

Wiring Up the New Systems

Update src/characters/mod.rs to include the new modules:

// src/characters/mod.rs - Update module declarations
pub mod animation;
pub mod config;
pub mod facing;     // Line update alert
pub mod input;      // Line update alert
pub mod physics;    // Line update alert
pub mod spawn;
pub mod state;      // Line update alert

// DELETE this line:
// pub mod movement;

use crate::state::GameState;

Now update the system registration. Remove the old systems and add the new ones:

// src/characters/mod.rs - DELETE these old systems from add_systems
movement::move_player,           // DELETE
movement::update_jump_state,     // DELETE
animation::animate_characters,   // DELETE
animation::update_animation_flags, // DELETE

Replace them with our new systems. Notice we’re using .chain() to ensure they run in order, and .run_if(in_state(GameState::Playing)) so they only run during gameplay. This is where we actually implement the freeze-on-pause behavior, when the game is in the Paused state, these systems won’t run, freezing all character movement and animation:

// src/characters/mod.rs - Add new systems
.add_systems(Update, (
    input::handle_player_input,
    spawn::switch_character,
    input::update_jump_state,
    animation::on_state_change_update_animation,
    physics::apply_velocity,
    animation::animations_playback,
).chain().run_if(in_state(GameState::Playing)));

The .chain() ensures systems run in order. Input sets state and velocity, animation responds to state changes, physics moves the entity, and animation playback animates the character.

Building a Collision System

Right now our character can walk anywhere, even through trees and into water. We need a collision system that prevents movement into obstacles.

Our approach is simple, each tile in our world has a type (grass, water, tree, etc.), and each type is either walkable or not. When the player tries to move, we check if the destination is walkable. If not, we block the move.

Defining Tile Types

First, we need to categorize what kinds of tiles exist in our world. Create src/collision/tile_type.rs:

// src/collision/tile_type.rs
use bevy::prelude::*;

/// Tile types for collision detection.
/// Each type has different walkability and collision behavior.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub enum TileType {
    // Walkable terrain
    #[default]
    Empty,
    Dirt,
    Grass,
    YellowGrass,
    Shore,  // Water edges (walkable)
    // Non-walkable obstacles
    Water,
    Tree,
    Rock,
}

Now add a method to check walkability:

// Append to src/collision/tile_type.rs
impl TileType {
    /// Check if this tile type allows movement through it.
    pub fn is_walkable(&self) -> bool {
        !matches!(self, TileType::Water | TileType::Tree | TileType::Rock)
    }

    /// Get the collision adjustment for this tile type.
    /// Positive = push player away, negative = allow corner cutting.
    pub fn collision_adjustment(&self) -> f32 {
        match self {
            TileType::Tree | TileType::Rock => -0.2,  // Allow cutting corners
            _ => 0.0,
        }
    }
}

Notice how we define walkability: instead of listing everything that is walkable, we list what isn’t. This means new tile types are walkable by default, a safer choice since forgetting to add a tile would make it passable rather than creating invisible walls.

What’s collision_adjustment?

Some tiles feel better with adjusted collision. A negative value (like -0.2 for trees and rocks) lets players cut corners more naturally instead of getting stuck on edges. Positive values would push players away from tiles.

We also need a marker component to attach tile type information to entities:

// Append to src/collision/tile_type.rs

/// Component to mark entities with their collision type.
/// Attached to tiles during map generation.
#[derive(Component, Debug, Clone)]
pub struct TileMarker {
    pub tile_type: TileType,
}

impl TileMarker {
    pub fn new(tile_type: TileType) -> Self {
        Self { tile_type }
    }
}

The Collision Map

Every frame, when the player tries to move, we need to answer “can they move there?” quickly. Checking every tree and water tile in the world each frame would be slow. Instead, we build a lookup table once: a grid where each cell knows if it’s walkable or not.

Here’s what a collision map looks like for a small 4x3 area:

Collision Map (4x3 grid)

    
      Grass
      Water
      Water
      Grass
    

      Grass
      Grass
      Tree
      Grass
    

      Grass
      Dirt
      Dirt
      Rock
    

    walkable
    blocked
  

This is CollisionMap. When the level loads, we scan all tiles and record their types. During gameplay, checking “is position (x, y) walkable?” is just an array lookup.

Create src/collision/map.rs:

// src/collision/map.rs
use bevy::prelude::*;
use super::TileType;

/// Collision map resource that stores walkability information.
/// Provides efficient spatial queries for movement validation.
#[derive(Resource)]
pub struct CollisionMap {
    /// Flat array of tile types (row-major order)
    tiles: Vec<TileType>,
    /// Grid dimensions
    width: i32,
    height: i32,
    /// Size of each tile in world units
    tile_size: f32,
    /// World position of grid origin (bottom-left corner)
    origin_x: f32,
    origin_y: f32,
}

We store tiles in a flat Vec rather than a 2D array for better performance.

Why a flat array?

In memory, we flatten the grid above row by row into a single array:

1D Array (how it's stored)
0Grass
1Dirt
2Dirt
3Rock
4Grass
5Grass
6Tree
7Grass
8Grass
9Water
10Water
11Grass
Row 0 (indices 0-3) → Row 1 (indices 4-7) → Row 2 (indices 8-11)

All 12 tiles sit next to each other in memory. When you access index 6 (Tree), indices 7 and 8 are likely already loaded into fast memory. A 2D array (Vec>) stores each row separately, which can be slower.

Why store origin?

In Bevy, the default camera places (0, 0) at the center of the screen. If we center a 4x4 tile grid, where does each tile sit?

Our grid uses tile coordinates: the bottom-left tile is (0, 0), the one to its right is (1, 0), and so on.

Tile Grid (each tile = 32px)

      32
      0
      -32
      -64
    

        
          0,3
          1,3
          2,3
          3,3
        

          0,2
          1,2
          2,2
          3,2
        

          0,1
          1,1
          2,1
          3,1
        

          0,0 
          1,0
          2,0
          3,0
        

        -64
        -32
        0
        32
      
← screen X (pixels) / ↑ screen Y (pixels)

     origin (tile 0,0)
     screen center
     player
  

The grid is 4 tiles wide × 32 pixels each = 128 pixels total. To center it, we shift left by half: 128 ÷ 2 = 64 pixels. So the grid’s bottom-left corner (tile 0,0) sits at screen position (-64, -64). That’s the origin.

Screen center (0, 0) lands inside tile (2, 2), not tile (0, 0)!

Now the player stands at screen position (-32, 0). Which tile?

With origin: (-32 - (-64)) / 32 = 1, (0 - (-64)) / 32 = 2 → Tile (1, 2) ✓
Without origin: (-32) / 32 = -1, (0) / 32 = 0 → Tile (-1, 0) (wrong tile!)

That’s why our CollisionMap stores the origin. Let’s implement the struct with methods to handle this conversion automatically.

The constructor creates an empty map filled with TileType::Empty. We also need two internal helpers:

xy_to_idx converts 2D coordinates like (3, 7) to a single number for array access, since tiles are stored in a 1D array.
in_bounds checks if coordinates are inside the grid, this serves double duty: it prevents accessing invalid memory and treats anything outside the map as “blocked” for collision purposes.

// Append to src/collision/map.rs
impl CollisionMap {
    /// Create a new collision map with specified dimensions and origin.
    pub fn new(width: i32, height: i32, tile_size: f32, origin_x: f32, origin_y: f32) -> Self {
        let size = (width * height) as usize;
        Self {
            tiles: vec![TileType::Empty; size],
            width,
            height,
            tile_size,
            origin_x,
            origin_y,
        }
    }

    /// Convert 2D grid coordinates to 1D array index.
    #[inline]
    fn xy_to_idx(&self, x: i32, y: i32) -> usize {
        (y * self.width + x) as usize
    }

    /// Check if grid coordinates are within bounds.
    #[inline]
    pub fn in_bounds(&self, x: i32, y: i32) -> bool {
        x >= 0 && x < self.width && y >= 0 && y < self.height
    }
}

Players move in screen positions like (150.5, -32.0). We need to convert these to tile coordinates like (4, -1) to check collision. That’s what these two functions do.

What’s #[inline]?

This hints to the compiler that these small, frequently-called functions should be inlined (copied directly into the caller function) rather than called as separate functions.

// Append to src/collision/map.rs
// Add this inside impl CollisionMap {

    // ... earlier functions inside impl CollisionMap 

    /// Convert world position to grid coordinates.
    pub fn world_to_grid(&self, world_pos: Vec2) -> IVec2 {
        let grid_x = ((world_pos.x - self.origin_x) / self.tile_size).floor() as i32;
        let grid_y = ((world_pos.y - self.origin_y) / self.tile_size).floor() as i32;
        IVec2::new(grid_x, grid_y)
    }

    /// Convert grid coordinates to world position (tile center).
    pub fn grid_to_world(&self, grid_x: i32, grid_y: i32) -> Vec2 {
        Vec2::new(
            self.origin_x + (grid_x as f32 + 0.5) * self.tile_size,
            self.origin_y + (grid_y as f32 + 0.5) * self.tile_size,
        )
    }

Understanding grid_to_world

This function does the opposite of world_to_grid: it takes grid coordinates like (3, 7) and converts them back to a world position.

Notice the + 0.5 in the code—this returns the center of the tile rather than its corner. If tile (3, 7) spans pixels 96-127, adding 0.5 gives us the center at pixel 112:

origin_x + (grid_x * tile_size)        // ← This gives the left edge (96)
origin_x + (grid_x + 0.5) * tile_size  // ← This gives the center (112)

This is useful because when you spawn a sprite in Bevy, its Transform position represents its center point by default. So grid_to_world gives you the exact position to place entities that should be visually centered in their tiles.

Now add tile access methods. Here’s how they fit together:

set_tile is used when building the map (during level load, we scan tiles and call set_tile for each one)
get_tile retrieves a tile type at grid coordinates
is_walkable asks can I walk on tile (3, 7)? It calls get_tile, then checks if that tile type is walkable
is_world_pos_walkable is the same question, but starts from screen position (150, -32). It converts to grid coordinates, then calls is_walkable

In practice, the circle collision code uses these internally. You rarely call them directly.

// Append to src/collision/map.rs
// Add this inside impl CollisionMap {

    // ... earlier functions inside impl CollisionMap 


    /// Get the tile type at grid coordinates.
    pub fn get_tile(&self, x: i32, y: i32) -> Option<TileType> {
        if self.in_bounds(x, y) {
            Some(self.tiles[self.xy_to_idx(x, y)])
        } else {
            None
        }
    }

    /// Set a tile at grid coordinates.
    pub fn set_tile(&mut self, x: i32, y: i32, tile_type: TileType) {
        if self.in_bounds(x, y) {
            let idx = self.xy_to_idx(x, y);
            self.tiles[idx] = tile_type;
        }
    }

    /// Check if a grid position is walkable.
    pub fn is_walkable(&self, x: i32, y: i32) -> bool {
        self.get_tile(x, y).map_or(false, |t| t.is_walkable())
    }

    /// Check if a world position is walkable.
    pub fn is_world_pos_walkable(&self, world_pos: Vec2) -> bool {
        let grid_pos = self.world_to_grid(world_pos);
        self.is_walkable(grid_pos.x, grid_pos.y)
    }

Circle Collision

The methods above check if a single point is walkable. But our character isn’t a point, they have a body! If we only check the player’s center position, they could overlap walls.

We model the player’s collision area as a circle at their center. To check if a circle collides with a tile (rectangle), we need to solve a problem: how do you test if a circle overlaps a rectangle?

The trick is to find the point on the rectangle closest to the circle’s center. If that point is inside the circle (distance less than radius), they overlap.

// Append to src/collision/map.rs
// Add this inside impl CollisionMap {

    // ... earlier functions inside impl CollisionMap 


    /// Check if a circle intersects with a tile's bounding box.
    fn circle_intersects_tile(&self, center: Vec2, radius: f32, gx: i32, gy: i32) -> bool {
        // Tile bounding box
        let tile_min = Vec2::new(
            self.origin_x + gx as f32 * self.tile_size,
            self.origin_y + gy as f32 * self.tile_size,
        );
        let tile_max = tile_min + Vec2::splat(self.tile_size);

        // Find closest point on tile to circle center
        let closest = Vec2::new(
            center.x.clamp(tile_min.x, tile_max.x),
            center.y.clamp(tile_min.y, tile_max.y),
        );

        // Check if closest point is within radius
        center.distance_squared(closest) <= radius * radius
    }

With circle_intersects_tile ready, we can build is_circle_clear. But first, we need to prevent the player from walking off the edge of the map.

// Append to src/collision/map.rs
// Add this inside impl CollisionMap {

    // ... earlier functions inside impl CollisionMap 
    /// Check if a position with radius is within map bounds.
    fn is_within_bounds(&self, center: Vec2, radius: f32) -> bool {
        let left = self.origin_x;
        let right = self.origin_x + self.width as f32 * self.tile_size;
        let bottom = self.origin_y;
        let top = self.origin_y + self.height as f32 * self.tile_size;

        center.x - radius >= left
            && center.x + radius <= right
            && center.y - radius >= bottom
            && center.y + radius <= top
    }

Now the main collision check.

// Append to src/collision/map.rs
// Add this inside impl CollisionMap {

    // ... earlier functions inside impl CollisionMap 

    /// Check if a circle at the given world position is clear of obstacles.
    pub fn is_circle_clear(&self, center: Vec2, radius: f32) -> bool {
        // Early bounds check
        if !self.is_within_bounds(center, radius) {
            return false;
        }

        // Point collision if no radius
        if radius <= 0.0 {
            return self.is_world_pos_walkable(center);
        }

        // Find grid cells that could overlap the circle
        let min_gx = ((center.x - radius - self.origin_x) / self.tile_size).floor() as i32;
        let max_gx = ((center.x + radius - self.origin_x) / self.tile_size).floor() as i32;
        let min_gy = ((center.y - radius - self.origin_y) / self.tile_size).floor() as i32;
        let max_gy = ((center.y + radius - self.origin_y) / self.tile_size).floor() as i32;

        for gy in min_gy..=max_gy {
            for gx in min_gx..=max_gx {
                if !self.in_bounds(gx, gy) {
                    return false;  // Out of bounds = blocked
                }

                if let Some(tile) = self.get_tile(gx, gy) {
                    if !tile.is_walkable() {
                        // Apply tile-specific collision adjustment
                        let effective_radius = radius + tile.collision_adjustment() * self.tile_size;
                        
                        if self.circle_intersects_tile(center, effective_radius, gx, gy) {
                            return false;
                        }
                    }
                }
            }
        }
        true
    }

Here’s how is_circle_clear works:

Early exit if circle is outside map bounds (is_within_bounds)
Find all grid cells the circle might touch (based on circle bounds)
For each unwalkable tile, use circle_intersects_tile to check overlap
Apply collision_adjustment() to allow corner cutting on certain tiles

Notice that is_circle_clear builds on everything we’ve created: in_bounds, get_tile, is_walkable, is_within_bounds, and circle_intersects_tile. Each layer builds on the previous one.

Swept Collision

We can now check if a position is valid using is_circle_clear. But there’s a problem: if a player moves fast enough in one frame, they could jump over a thin wall. The collision check at the destination would pass, but they’d skip right through the obstacle.

sweep_circle solves this by checking the entire path from start to end. It uses is_circle_clear repeatedly along small steps, ensuring we catch any collision along the way:

// Append to src/collision/map.rs
// Add this inside impl CollisionMap {

    // ... earlier functions inside impl CollisionMap 

    /// Perform swept circle movement with axis-sliding.
    /// Returns the furthest valid position the circle can reach.
    pub fn sweep_circle(&self, start: Vec2, end: Vec2, radius: f32) -> Vec2 {
        let delta = end - start;
        
        // No movement needed
        if delta.length() < 0.001 {
            return start;
        }

        // Step size (quarter tile for smooth collision)
        let max_step = self.tile_size * 0.25;
        let steps = (delta.length() / max_step).ceil().max(1.0) as i32;
        let step_vec = delta / steps as f32;

        let mut pos = start;
        for _ in 0..steps {
            let candidate = pos + step_vec;

            if self.is_circle_clear(candidate, radius) {
                pos = candidate;
            } else {
                // Try sliding along X axis only
                let try_x = Vec2::new(candidate.x, pos.y);
                if self.is_circle_clear(try_x, radius) {
                    pos = try_x;
                    continue;
                }

                // Try sliding along Y axis only
                let try_y = Vec2::new(pos.x, candidate.y);
                if self.is_circle_clear(try_y, radius) {
                    pos = try_y;
                    continue;
                }

                // Completely blocked
                break;
            }
        }
        pos
    }

We’ll be soon working on a feature to visually debug collisions. We need the following helper functions to calculate the collision map. The #[cfg(debug_assertions)] attribute means these only exist in debug builds, they’re completely removed from release builds:

// Append to src/collision/map.rs
// Append to src/collision/map.rs
// Add this inside impl CollisionMap {

    // ... earlier functions inside impl CollisionMap 
    #[cfg(debug_assertions)]
    pub fn width(&self) -> i32 { self.width }
    
    #[cfg(debug_assertions)]
    pub fn height(&self) -> i32 { self.height }
    
    #[cfg(debug_assertions)]
    pub fn tile_size(&self) -> f32 { self.tile_size }
    
    #[cfg(debug_assertions)]
    pub fn origin(&self) -> Vec2 { Vec2::new(self.origin_x, self.origin_y) }

Building the Collision Map

We have the CollisionMap data structure, but when does it get populated? We need a system that scans all the tiles after WFC generation and builds the collision map.

Create src/collision/systems.rs:

The collision map should only be built once after tiles are spawned. We need a way to track this. A simple boolean resource does the job: it starts as false, and once we build the map, we flip it to true.

We register this resource with Bevy’s scheduler using run_if(resource_equals(CollisionMapBuilt(false))), which means the build system won’t even run after the map is built.

// src/collision/systems.rs
use bevy::prelude::*;
use std::collections::{HashMap, hash_map::Entry};

use super::{CollisionMap, TileMarker, TileType};
use crate::config::map::{TILE_SIZE, GRID_X, GRID_Y};

/// Resource to track if collision map has been built.
#[derive(Resource, Default, PartialEq, Eq)]
pub struct CollisionMapBuilt(pub bool);

Now the main system that builds the map. This is the longest function we’ve written, so let’s understand what it does before looking at the code.

The system detects when WFC has finished by querying for tiles, if no tiles exist yet, it exits early. Once tiles exist, it:

Calculates the grid origin - Our map is centered on the screen, so the bottom-left corner of the grid isn’t at (0, 0). We need to figure out where it actually is.
Scans all tiles - Each tile entity has a Transform (its position in the world) and a TileMarker (what type of tile it is). We loop through every tile and read both.
Handles overlapping tiles - Our WFC generator can place tiles on top of each other. For example, a tree sprite sits on top of grass at the same (x, y) position but at a higher Z (depth). For collision, we only care about the topmost tile: if there’s a tree on grass, the player collides with the tree.
Tracks bounds - We track the leftmost, rightmost, topmost, and bottommost tile coordinates. From these, we calculate the dimensions of the CollisionMap.
Creates and populates the CollisionMap - Using the world_to_grid logic we built earlier, we convert each tile’s world position to grid coordinates and call set_tile to record its type.
Post-processes - Finally, we run shore conversion to turn water tiles at the edge of lakes into walkable shore tiles. This gives players a better experience at water boundaries.

// Append to src/collision/systems.rs

/// System that builds the collision map from spawned tiles.
/// Handles multi-layer maps by keeping only the TOPMOST tile at each (x,y).
pub fn build_collision_map(
    mut commands: Commands,
    mut built: ResMut<CollisionMapBuilt>,
    tile_query: Query<(&TileMarker, &Transform)>,
) {
    // Need at least one tile to proceed
    let mut tile_iter = tile_query.iter();
    let Some((first_marker, first_transform)) = tile_iter.next() else {
        return; // WFC hasn't generated tiles yet
    };

    // Calculate grid origin (centered map)
    let grid_origin_x = -TILE_SIZE * GRID_X as f32 / 2.0;
    let grid_origin_y = -TILE_SIZE * GRID_Y as f32 / 2.0;

    // Track bounds and layer info
    let (mut min_x, mut max_x) = (i32::MAX, i32::MIN);
    let (mut min_y, mut max_y) = (i32::MAX, i32::MIN);
    let mut layer_tracker: HashMap<(i32, i32), (TileType, f32)> = HashMap::new();
    let mut tile_count: usize = 0;

    // Process all tiles, keeping only the topmost at each position
    let mut process_tile = |marker: &TileMarker, transform: &Transform| {
        tile_count += 1;

        let world_x = transform.translation.x;
        let world_y = transform.translation.y;
        let world_z = transform.translation.z;
        
        let grid_x = ((world_x - grid_origin_x) / TILE_SIZE).floor() as i32;
        let grid_y = ((world_y - grid_origin_y) / TILE_SIZE).floor() as i32;

        min_x = min_x.min(grid_x);
        max_x = max_x.max(grid_x);
        min_y = min_y.min(grid_y);
        max_y = max_y.max(grid_y);

        // Keep only the topmost layer (highest Z)
        match layer_tracker.entry((grid_x, grid_y)) {
            Entry::Occupied(mut entry) => {
                if world_z > entry.get().1 {
                    *entry.get_mut() = (marker.tile_type, world_z);
                }
            }
            Entry::Vacant(entry) => {
                entry.insert((marker.tile_type, world_z));
            }
        }
    };

    // Process first tile and remaining
    process_tile(first_marker, first_transform);
    for (marker, transform) in tile_iter {
        process_tile(marker, transform);
    }

    // Calculate actual dimensions
    let actual_width = (max_x - min_x + 1) as i32;
    let actual_height = (max_y - min_y + 1) as i32;

    // Create the collision map
    let mut map = CollisionMap::new(
        actual_width,
        actual_height,
        TILE_SIZE,
        grid_origin_x,
        grid_origin_y,
    );

    // Populate the map from layer tracker
    for ((grid_x, grid_y), (tile_type, _z)) in layer_tracker.iter() {
        // Convert world grid to local array coordinates
        let local_x = grid_x - min_x;
        let local_y = grid_y - min_y;
        map.set_tile(local_x, local_y, *tile_type);
    }

    // Post-processing: Convert water edges to shore
    convert_water_edges_to_shore(&mut map);
    // Insert as resource and mark built
    commands.insert_resource(map);
    built.0 = true;
}

Shore Conversion

Imagine a lake in your game. Water tiles block movement completely, but what about the edge of the lake? If the player walks up to water at the edge of grass, they should be able to get close to the waterline rather than stopping a full tile away.

Shore conversion solves this by finding water tiles that touch walkable terrain and marking them as Shore. Shore tiles are walkable (remember our TileType::Shore from earlier), so the player can walk right up to the water’s edge while still being blocked by the deep water in the middle of the lake.

The algorithm is straightforward: scan every tile, find water tiles, check their 8 neighbors, and if any neighbor is walkable, mark this water tile as shore.

// Append to src/collision/systems.rs

/// Convert water tiles adjacent to walkable tiles into shore tiles.
fn convert_water_edges_to_shore(map: &mut CollisionMap) {
    let mut shores = Vec::new();

    // Find water tiles that touch walkable tiles
    for y in 0..map.height() {
        for x in 0..map.width() {
            if map.get_tile(x, y) != Some(TileType::Water) {
                continue;
            }

            // Check 8 neighbors
            let neighbors = [
                (x - 1, y),     (x + 1, y),     // left, right
                (x, y - 1),     (x, y + 1),     // down, up
                (x - 1, y - 1), (x + 1, y - 1), // bottom corners
                (x - 1, y + 1), (x + 1, y + 1), // top corners
            ];

            for (nx, ny) in neighbors {
                if map.is_walkable(nx, ny) {
                    shores.push((x, y));
                    break;
                }
            }
        }
    }

    for (x, y) in shores {
        map.set_tile(x, y, TileType::Shore);
    }


}

Debug Visualization

When collision isn’t working, you need to see what’s happening. Is the player’s collider in the right place? Are tiles marked correctly? Visual debugging makes these problems obvious.

We’ll create a debug overlay that:

Shows green for walkable tiles, red for blocked
Draws the player’s collision circle
Highlights which grid cell the player is in
Only exists in debug builds (removed from release)

Create src/collision/debug.rs:

// src/collision/debug.rs
use bevy::prelude::*;
use super::CollisionMap;
use crate::characters::input::Player;
use crate::characters::collider::Collider;

/// Resource to toggle debug visualization.
#[derive(Resource, Default)]
pub struct DebugCollisionEnabled(pub bool);

This DebugCollisionEnabled resource controls whether debug drawing is active. We start with it off and let the player toggle it with a key.

// Append to src/collision/debug.rs

/// Toggle collision debug visualization with F3 key.
pub fn toggle_debug_collision(
    keyboard: Res<ButtonInput<KeyCode>>,
    mut debug_enabled: ResMut<DebugCollisionEnabled>,
) {
    if keyboard.just_pressed(KeyCode::F3) {
        debug_enabled.0 = !debug_enabled.0;
        if debug_enabled.0 {
            info!("🔍 Collision debug ENABLED (F3 to toggle)");
        } else {
            info!("Collision debug disabled");
        }
    }
}

Why debug_enabled.0 instead of just debug_enabled?

Our DebugCollisionEnabled is a “tuple struct” - a struct that wraps a single value. The .0 accesses the first (and only) field inside it. This pattern is common in Rust for creating type-safe wrappers: instead of passing around a raw bool, we wrap it in a named type that makes the code’s intent clearer.

We have used F3 as keyboard shortcut to toggle the debug overlay on and off in the gameplay.

What’s Gizmos?

Gizmos are Bevy’s built-in tool for drawing debug shapes like lines, circles, and rectangles. Unlike regular sprites, gizmos only last for one frame and automatically disappear. This makes them perfect for debug visualization: you draw what you need each frame, and when you stop drawing, they’re gone.

// Append to src/collision/debug.rs

/// Draw colored rectangles over tiles showing walkability.
pub fn debug_draw_collision(
    map: Option<Res<CollisionMap>>,
    debug_enabled: Res<DebugCollisionEnabled>,
    mut gizmos: Gizmos,
) {
    if !debug_enabled.0 {
        return;
    }

    let Some(map) = map else { return };

    let tile_size = map.tile_size();
    let origin = map.origin();

    // Draw each tile
    for y in 0..map.height() {
        for x in 0..map.width() {
            let world_pos = Vec2::new(
                origin.x + (x as f32 + 0.5) * tile_size,
                origin.y + (y as f32 + 0.5) * tile_size,
            );

            let color = if map.is_walkable(x, y) {
                Color::srgba(0.0, 1.0, 0.0, 0.25)  // Green, 25% opacity
            } else {
                Color::srgba(1.0, 0.0, 0.0, 0.4)   // Red, 40% opacity
            };

            gizmos.rect_2d(
                world_pos,
                Vec2::splat(tile_size * 0.9),
                color,
            );
        }
    }
}

This loops through every tile and draws a colored rectangle: green for walkable, red for blocked. The 0.9 multiplier makes each rectangle slightly smaller than the tile so you can see the grid lines.

Next, we visualize the player’s collider:

// Append to src/collision/debug.rs

/// Draw player position and collider visualization.
pub fn debug_player_position(
    player_query: Query<(&Transform, &Collider), With<Player>>,
    map: Option<Res<CollisionMap>>,
    debug_enabled: Res<DebugCollisionEnabled>,
    mut gizmos: Gizmos,
) {
    if !debug_enabled.0 {
        return;
    }

    let Some(map) = map else { return };
    let Ok((transform, collider)) = player_query.single() else { return };

    let center = transform.translation.truncate();
    
    // Get actual collider position
    let collider_pos = collider.world_position(transform);
    let grid = map.world_to_grid(collider_pos);

    // Draw line from center to collider (shows offset)
    gizmos.line_2d(center, collider_pos, Color::srgba(1.0, 1.0, 0.0, 0.5));

    // Draw actual collider circle
    gizmos.circle_2d(collider_pos, collider.radius, Color::srgb(0.0, 1.0, 1.0));

    // Draw current grid cell outline
    if map.in_bounds(grid.x, grid.y) {
        let cell_center = map.grid_to_world(grid.x, grid.y);
        gizmos.rect_2d(
            cell_center,
            Vec2::splat(map.tile_size()),
            Color::srgb(1.0, 1.0, 0.0),
        );

        // Draw red X if on unwalkable tile
        if !map.is_walkable(grid.x, grid.y) {
            let offset = 15.0;
            gizmos.line_2d(
                collider_pos + Vec2::new(-offset, -offset),
                collider_pos + Vec2::new(offset, offset),
                Color::srgb(1.0, 0.0, 0.0),
            );
            gizmos.line_2d(
                collider_pos + Vec2::new(-offset, offset),
                collider_pos + Vec2::new(offset, -offset),
                Color::srgb(1.0, 0.0, 0.0),
            );
        }
    }
}

This draws:

Cyan circle - the player’s collision radius
Yellow rectangle - which grid cell the player is in
Red X - appears if the player is somehow on an unwalkable tile

Wiring It Together: The Collision Module

Now we tie everything together in src/collision/mod.rs. This file declares our submodules, re-exports the public types, and defines the CollisionPlugin.

// src/collision/mod.rs
mod tile_type;
mod map;
mod systems;

#[cfg(debug_assertions)]
mod debug;

use bevy::prelude::*;
use crate::state::GameState;

// Re-export commonly used types
pub use tile_type::{TileType, TileMarker};
pub use map::CollisionMap;
pub use systems::CollisionMapBuilt;

#[cfg(debug_assertions)]
pub use debug::DebugCollisionEnabled;

The pub use lines make these types available to other modules. Instead of writing collision::tile_type::TileType, other code can simply use collision::TileType.

Now the plugin that registers everything with Bevy:

// Append to src/collision/mod.rs

/// Plugin for collision detection functionality
pub struct CollisionPlugin;

impl Plugin for CollisionPlugin {
    fn build(&self, app: &mut App) {
        app.init_resource::<CollisionMapBuilt>()
            .add_systems(
                Update,
                systems::build_collision_map
                    .run_if(resource_equals(CollisionMapBuilt(false)))
                    .run_if(in_state(GameState::Playing)),
            );

        // Debug systems - only in debug builds
        #[cfg(debug_assertions)]
        {
            app.init_resource::<DebugCollisionEnabled>()
                .add_systems(
                    Update,
                    (
                        debug::toggle_debug_collision,
                        debug::debug_draw_collision,
                        debug::debug_player_position,
                    )
                        .run_if(in_state(GameState::Playing)),
                );
        }
    }
}

Notice the two run_if conditions on build_collision_map:

resource_equals(CollisionMapBuilt(false)) - Only runs when the map hasn’t been built yet
in_state(GameState::Playing) - Only runs during gameplay, not menus or loading

The debug systems are wrapped in #[cfg(debug_assertions)], so they don’t exist in release builds at all.

Also add the collision module to your main.rs:

// In main.rs
mod collision; // Line update alert

// In your app setup:
        .add_plugins(ProcGenSimplePlugin::<Cartesian3D, Sprite>::default())
        .add_plugins(state::StatePlugin)
        .add_plugins(collision::CollisionPlugin) // Line update alert
        .add_plugins(characters::CharactersPlugin) 
        .add_systems(Startup, (setup_camera, setup_generator))
        .run();

Integrating Collision with Map Assets

Now we need to modify our map generation to attach TileMarker components to spawned tiles. This connects the visual tiles to the collision system.

First, update src/map/assets.rs to support tile types:

// src/map/assets.rs - Updated imports
use bevy::prelude::*;
use bevy_procedural_tilemaps::prelude::*;

use crate::collision::{TileMarker, TileType}; // Line update alert
use crate::map::tilemap::TILEMAP;

Update the SpawnableAsset struct to include tile type. Note: We are replacing components_spawner we had earlier with tile_type, so this include multiple changes in struct, function arguments, etc.

// src/map/assets.rs - Updated SpawnableAsset struct
#[derive(Clone)]
pub struct SpawnableAsset {
    /// Name of the sprite inside our tilemap atlas
    sprite_name: &'static str,
    /// Offset in grid coordinates (for multi-tile objects)
    grid_offset: GridDelta,
    /// Offset in world coordinates (fine positioning)
    offset: Vec3,
    /// The tile type for collision detection
    tile_type: Option<TileType>, // Line update alert
}

impl SpawnableAsset {
    pub fn new(sprite_name: &'static str) -> Self {
        Self {
            sprite_name,
            grid_offset: GridDelta::new(0, 0, 0),
            offset: Vec3::ZERO,
            tile_type: None, // Line update alert
        }
    }

    /// Set grid offset for multi-tile objects.
    pub fn with_grid_offset(mut self, offset: GridDelta) -> Self {
        self.grid_offset = offset;
        self
    }

    /// Set tile type for collision detection.
    // Function added alert
    pub fn with_tile_type(mut self, tile_type: TileType) -> Self { 
        self.tile_type = Some(tile_type);
        self
    }
}

The builder pattern lets us chain methods: SpawnableAsset::new("grass").with_tile_type(TileType::Grass).

Update the load_assets function to use a spawner:

// src/map/assets.rs - Updated load_assets function
pub fn load_assets(
    tilemap_handles: &TilemapHandles,
    assets_definitions: Vec<Vec<SpawnableAsset>>,
) -> ModelsAssets<Sprite> {
    let mut models_assets = ModelsAssets::<Sprite>::new();
    
    for (model_index, assets) in assets_definitions.into_iter().enumerate() {
        for asset_def in assets {
            let SpawnableAsset {
                sprite_name,
                grid_offset,
                offset,
                tile_type, // Line update alert
            } = asset_def;

            let Some(atlas_index) = TILEMAP.sprite_index(sprite_name) else {
                panic!("Unknown atlas sprite '{}'", sprite_name);
            };

            // Create the spawner function that adds components
            let spawner = create_spawner(tile_type); // Line update alert

            models_assets.add(
                model_index,
                ModelAsset {
                    assets_bundle: tilemap_handles.sprite(atlas_index),
                    grid_offset,
                    world_offset: offset,
                    spawn_commands: spawner, // Line update alert
                },
            );
        }
    }
    models_assets
}

Now add the create_spawner function that generates the right component insertion based on tile type:

// src/map/assets.rs - Add create_spawner function

fn create_spawner(
    tile_type: Option<TileType>,
) -> fn(&mut EntityCommands) {
    match tile_type {
        // Tile types without pickable
        Some(TileType::Dirt) => |e: &mut EntityCommands| {
            e.insert(TileMarker::new(TileType::Dirt));
        },
        Some(TileType::Grass) => |e: &mut EntityCommands| {
            e.insert(TileMarker::new(TileType::Grass));
        },
        Some(TileType::YellowGrass) => |e: &mut EntityCommands| {
            e.insert(TileMarker::new(TileType::YellowGrass));
        },
        Some(TileType::Water) => |e: &mut EntityCommands| {
            e.insert(TileMarker::new(TileType::Water));
        },
        Some(TileType::Shore) => |e: &mut EntityCommands| {
            e.insert(TileMarker::new(TileType::Shore));
        },
        Some(TileType::Tree) => |e: &mut EntityCommands| {
            e.insert(TileMarker::new(TileType::Tree));
        },
        Some(TileType::Rock) => |e: &mut EntityCommands| {
            e.insert(TileMarker::new(TileType::Rock));
        },
        Some(TileType::Empty) => |e: &mut EntityCommands| {
            e.insert(TileMarker::new(TileType::Empty));
        },
        // Default: no components
        _ => |_: &mut EntityCommands| {},
    }
}

Updating Map Rules with Tile Types

Now update src/map/rules.rs to specify tile types for each spawnable asset. Add the import at the top:

// src/map/rules.rs - Updated imports
use crate::collision::TileType; //Line update alert
use crate::map::assets::SpawnableAsset;
use crate::map::models::TerrainModelBuilder;
use crate::map::sockets::*;
use bevy_procedural_tilemaps::prelude::*;

Now update each layer function. Here’s the dirt layer:

// src/map/rules.rs - Updated build_dirt_layer
fn build_dirt_layer(
    terrain_model_builder: &mut TerrainModelBuilder,
    terrain_sockets: &TerrainSockets,
    socket_collection: &mut SocketCollection,
) {
    terrain_model_builder
        .create_model(
            SocketsCartesian3D::Simple {
                x_pos: terrain_sockets.dirt.material,
                x_neg: terrain_sockets.dirt.material,
                z_pos: terrain_sockets.dirt.layer_up,
                z_neg: terrain_sockets.dirt.layer_down,
                y_pos: terrain_sockets.dirt.material,
                y_neg: terrain_sockets.dirt.material,
            },
            //Line update alert
            vec![SpawnableAsset::new("dirt").with_tile_type(TileType::Dirt)],
        )
        .with_weight(20.);

    socket_collection.add_connections(vec![(
        terrain_sockets.dirt.material,
        vec![terrain_sockets.dirt.material],
    )]);
}

The grass layer (showing the main tile and one corner as example), you will need to repeat this to all other grass corner and side tiles.

// src/map/rules.rs - Updated build_grass_layer (partial)
// Main grass tile
terrain_model_builder
    .create_model(
        SocketsCartesian3D::Multiple {
            x_pos: vec![terrain_sockets.grass.material],
            x_neg: vec![terrain_sockets.grass.material],
            z_pos: vec![
                terrain_sockets.grass.layer_up,
                terrain_sockets.grass.grass_fill_up,
            ],
            z_neg: vec![terrain_sockets.grass.layer_down],
            y_pos: vec![terrain_sockets.grass.material],
            y_neg: vec![terrain_sockets.grass.material],
        },
        //Line update alert
        vec![SpawnableAsset::new("green_grass").with_tile_type(TileType::Grass)],
    )
    .with_weight(5.);

// Outer corners
terrain_model_builder.create_model(
    green_grass_corner_out.clone(),
    vec![SpawnableAsset::new("green_grass_corner_out_tl").with_tile_type(TileType::Grass)],
);
// ... repeat for all corner and side variants with .with_tile_type(TileType::Grass)

Ensure to repeat for all corner and side variants with .with_tile_type(TileType::Grass), if you are confused check the github repo for the full code.

The yellow grass layer follows the same pattern:

// Main yellow grass tile
vec![SpawnableAsset::new("yellow_grass").with_tile_type(TileType::YellowGrass)]

// All yellow grass corners and sides
vec![SpawnableAsset::new("yellow_grass_corner_out_tl").with_tile_type(TileType::YellowGrass)]
// ... etc

Ensure to repeat for all corner and side variants with .with_tile_type(TileType::YellowGrass).

The water layer:

// Main water tile
vec![SpawnableAsset::new("water").with_tile_type(TileType::Water)]

// All water corners and sides
vec![SpawnableAsset::new("water_corner_out_tl").with_tile_type(TileType::Water)]
// ... etc

Ensure to repeat for all corner and side variants with .with_tile_type(TileType::Water).

The props layer has mixed tile types. Trees and rocks block movement, plants are walkable:

// src/map/rules.rs - Updated build_props_layer (key examples)

// Small tree - bottom blocks, top is walkable (canopy)
terrain_model_builder.create_model(
    plant_prop.clone(),
    vec![
        // Line update alert
        SpawnableAsset::new("small_tree_bottom").with_tile_type(TileType::Tree),
        SpawnableAsset::new("small_tree_top").with_grid_offset(GridDelta::new(0, 1, 0)),
    ],
);

// Big tree 1 - left side (base blocks, canopy walkable)
vec![
    SpawnableAsset::new("big_tree_1_bl").with_tile_type(TileType::Tree),
    SpawnableAsset::new("big_tree_1_tl").with_grid_offset(GridDelta::new(0, 1, 0)),
]

// Big tree 1 - right side
vec![
    SpawnableAsset::new("big_tree_1_br").with_tile_type(TileType::Tree),
    SpawnableAsset::new("big_tree_1_tr").with_grid_offset(GridDelta::new(0, 1, 0)),
]

// Big tree 2 - left side
vec![
    SpawnableAsset::new("big_tree_2_bl").with_tile_type(TileType::Tree),
    SpawnableAsset::new("big_tree_2_tl").with_grid_offset(GridDelta::new(0, 1, 0)),
]

// Big tree 2 - right side
vec![
    SpawnableAsset::new("big_tree_2_br").with_tile_type(TileType::Tree),
    SpawnableAsset::new("big_tree_2_tr").with_grid_offset(GridDelta::new(0, 1, 0)),
]

// Tree stumps block movement
vec![SpawnableAsset::new("tree_stump_1").with_tile_type(TileType::Tree)]
vec![SpawnableAsset::new("tree_stump_2").with_tile_type(TileType::Tree)]
vec![SpawnableAsset::new("tree_stump_3").with_tile_type(TileType::Tree)]

// Rocks block movement
// Lines updated
vec![SpawnableAsset::new("rock_1").with_tile_type(TileType::Rock)]
vec![SpawnableAsset::new("rock_2").with_tile_type(TileType::Rock)]
vec![SpawnableAsset::new("rock_3").with_tile_type(TileType::Rock)]
vec![SpawnableAsset::new("rock_4").with_tile_type(TileType::Rock)]

// Plants are walkable (grass tile type)
vec![SpawnableAsset::new("plant_1").with_tile_type(TileType::Grass)]
vec![SpawnableAsset::new("plant_2").with_tile_type(TileType::Grass)]
vec![SpawnableAsset::new("plant_3").with_tile_type(TileType::Grass)]
vec![SpawnableAsset::new("plant_4").with_tile_type(TileType::Grass)]

Notice tree canopies (the “top” parts) don’t have a tile type. This is intentional: the player can walk under tree canopies but collides with the trunk.

Centralizing Configuration

Before we create the player’s collider, let’s centralize our magic numbers. Scattered constants make tuning gameplay tedious. Create a single configuration file:

Create src/config.rs:

// src/config.rs
//! Centralized configuration constants for the game.

/// Player-related configuration
pub mod player {
    /// Collision radius for the player's collider (in world units)
    pub const COLLIDER_RADIUS: f32 = 16.0;
    
    
    /// Z-position for player rendering (above terrain, below UI)
    pub const PLAYER_Z_POSITION: f32 = 20.0;
    
    /// Visual scale of the player sprite
    pub const PLAYER_SCALE: f32 = 0.8;
}

/// Map/terrain configuration
pub mod map {
    /// Size of a single tile in world units
    pub const TILE_SIZE: f32 = 32.0;
    
    /// Grid dimensions
    pub const GRID_X: u32 = 25;
    pub const GRID_Y: u32 = 18;
}

These constants define our collision radius (16 pixels) and map dimensions. Having them in one place means you can tweak collision behavior without hunting through multiple files.

Add this module to src/main.rs:

// src/main.rs
mod config;  // Add this line

Creating the Player Collider

Now we need a component that represents the player’s collision shape. We’ll use a circle positioned at the player’s center.

Create src/characters/collider.rs:

// src/characters/collider.rs
use bevy::prelude::*;

use crate::collision::CollisionMap;
use crate::characters::physics::Velocity;
use crate::config::player::{COLLIDER_RADIUS};

/// A circular collider for collision detection.
/// 
/// The collider position is offset from the entity's transform,
#[derive(Component, Debug, Clone)]
pub struct Collider {
    /// Radius of the circular collider in world units
    pub radius: f32,
    /// Offset from entity center
    pub offset: Vec2,
}

impl Default for Collider {
    fn default() -> Self {
        Self {
            radius: COLLIDER_RADIUS,
            offset: Vec2::ZERO,
        }
    }
}

impl Collider {
    /// Get the world position of this collider given an entity's transform.
    pub fn world_position(&self, transform: &Transform) -> Vec2 {
        transform.translation.truncate() + self.offset
    }
}

Validating Movement Against Collision

Now the crucial system: checking if the player can actually move where they want to go.

// Append to src/characters/collider.rs

/// System that validates movement against the collision map.
/// 
/// Runs after input (which sets velocity) but before physics (which applies velocity).
/// Modifies velocity to prevent movement into unwalkable tiles.
pub fn validate_movement(
    map: Option<Res<CollisionMap>>,
    time: Res<Time>,
    mut query: Query<(&Transform, &mut Velocity, &Collider)>,
) {
    let Some(map) = map else { return };

    for (transform, mut velocity, collider) in query.iter_mut() {
        // Skip if not moving
        if !velocity.is_moving() {
            continue;
        }

        // Current collider position
        let current_pos = collider.world_position(transform);
        
        // Desired new position based on velocity
        let delta = velocity.0 * time.delta_secs();
        let desired_pos = current_pos + delta;

        // Use swept collision to find valid position
        let valid_pos = map.sweep_circle(current_pos, desired_pos, collider.radius);

        // Calculate what velocity would get us to valid_pos
        let actual_delta = valid_pos - current_pos;
        
        // Only update velocity if collision modified our path
        if (actual_delta - delta).length_squared() > 0.001 {
            // Convert position delta back to velocity
            let dt = time.delta_secs();
            if dt > 0.0 {
                velocity.0 = actual_delta / dt;
            }
        }
    }
}

How this works:

Get the current collider position
Calculate where the player wants to go based on their velocity
Use sweep_circle to find the furthest valid position along that path
If collision blocked part of the movement, adjust velocity accordingly

The key insight: we don’t block movement entirely. If the player tries to walk diagonally into a wall, sweep_circle might allow sliding along the wall’s surface. This feels much better than getting stuck.

Updating the Characters Module

Add the collider module to src/characters/mod.rs:

// src/characters/mod.rs - Add at the top
pub mod collider;  // Add this line

Now update the system registration. We need validate_movement to run after input sets velocity but before physics applies it:

// src/characters/mod.rs - Update the system chain
.add_systems(Update, (
    // 1. Input determines state + velocity + facing
    input::handle_player_input,
    spawn::switch_character,
    input::update_jump_state,
    
    // 2. State changes trigger animation updates
    animation::on_state_change_update_animation,
    
    // 3. Collision validation adjusts velocity  <-- Line update alert!
    collider::validate_movement,
    
    // 4. Physics applies velocity to transform
    physics::apply_velocity,
    
    // 5. Animation ticks frames
    animation::tick_animations,
).chain().run_if(in_state(GameState::Playing)));

Attaching Collider to the Player

Finally, update src/characters/spawn.rs to attach the Collider component when initializing the player.

Update the imports:

// src/characters/spawn.rs - Add import
use crate::characters::collider::Collider; // Line update alert!
use crate::config::player::{PLAYER_SCALE, PLAYER_Z_POSITION}; // Line update alert!

Also remove these existing constants since we are importing the constants from the config.

// Delete these lines
// const PLAYER_SCALE: f32 = 0.8;
// const PLAYER_Z_POSITION: f32 = 20.0;

Then in initialize_player_character, add Collider::default() to the component bundle:

// src/characters/spawn.rs - In initialize_player_character
commands.entity(entity).insert((
    AnimationController::default(),
    CharacterState::default(),
    Velocity::default(),
    Facing::default(),
    Collider::default(),  // Line update alert!
    AnimationTimer(Timer::from_seconds(DEFAULT_ANIMATION_FRAME_TIME, TimerMode::Repeating)),
    character_entry.clone(),
    sprite,
));

Now run the game:

cargo run

Walk your character around. You should now collide with trees, rocks, and water! The character slides smoothly along obstacles rather than getting stuck. Press F3 to toggle the debug overlay and see the collision map visualized.

The Illusion of Depth

There’s one more problem. Walk your character behind a tree. Notice anything odd?

The player always renders on top. They don’t disappear behind the tree trunk. In a top-down game, objects higher on the screen (further away from you) should appear “behind” objects lower on the screen (closer to you). When your character walks upward and passes behind a tree, they should disappear behind it.

This is Y-based depth sorting. The concept is simple: objects with a lower Y position (closer to the bottom of the screen) are “in front” of objects with a higher Y position.

In 2D rendering, Z determines draw order. Higher Z draws on top. So we need:

Higher Y (top of screen) → Lower Z (drawn first, appears behind)
Lower Y (bottom of screen) → Higher Z (drawn last, appears in front)

Our tilemap generator already does this for tiles using with_z_offset_from_y(true). But the player’s Z position is fixed! We need to update the player’s Z dynamically based on their Y position.

Creating the Rendering Module

Create src/characters/rendering.rs:

// src/characters/rendering.rs
//! Rendering utilities for depth sorting.

use bevy::prelude::*;

use crate::characters::input::Player;
use crate::config::map::{GRID_Y, TILE_SIZE};
use crate::config::player::PLAYER_SCALE;

/// Z-depth constants for proper layering.
/// The tilemap uses `with_z_offset_from_y(true)` which assigns Z based on Y position.
/// We need to match this formula for the player.
const NODE_SIZE_Z: f32 = 1.0;  // Same as tilemap generator
const PLAYER_BASE_Z: f32 = 4.0;  // Match props layer Z range
const PLAYER_Z_OFFSET: f32 = 0.5;  // Small offset to stay above ground props

These constants need to match how the tilemap generator calculates Z. PLAYER_BASE_Z positions the player in the same Z range as props (trees, rocks). PLAYER_Z_OFFSET adds a tiny buffer so the player doesn’t z-fight with ground-level decorations.

Now the depth sorting system. The key is to dynamically adjust the player’s Z position based on their Y position. When the player moves up the screen (higher Y), we lower their Z so they render behind objects. When they move down (lower Y), we raise their Z so they render in front.

But there’s a subtlety: we use the player’s feet position, not their sprite center, for depth calculation. Why? Imagine your character standing just in front of a tree. The sprite’s center is at chest level, but visually, what matters is where their feet are. If we used the center, the player’s head might incorrectly poke out above a tree they’re standing in front of. Using feet position makes occlusion look natural.

// Append to src/rendering.rs

/// System to update player depth based on Y position.
/// 
/// Objects with lower Y (further down screen) get higher Z (rendered in front).
/// This creates proper occlusion when walking behind trees.
pub fn update_player_depth(
    mut player_query: Query<&mut Transform, (With<Player>, Changed<Transform>)>,
) {
    // Map dimensions for normalization
    let map_height = TILE_SIZE * GRID_Y as f32;
    let map_y0 = -TILE_SIZE * GRID_Y as f32 / 2.0;  // Map origin Y (centered)
    
    // Player sprite height for feet position calculation
    let player_sprite_height = 64.0 * PLAYER_SCALE;

    for mut transform in player_query.iter_mut() {
        let player_center_y = transform.translation.y;

        // Use player's FEET position for depth sorting (not center)
        let player_feet_y = player_center_y - (player_sprite_height / 2.0);

        // Normalize feet Y to [0, 1] across the grid height
        let t = ((player_feet_y - map_y0) / map_height).clamp(0.0, 1.0);

        // Y-to-Z formula:
        // Lower Y (bottom of screen) = higher t = lower Z offset = rendered in front
        // Higher Y (top of screen) = lower t = higher Z offset = rendered behind
        let player_z = PLAYER_BASE_Z + NODE_SIZE_Z * (1.0 - t) + PLAYER_Z_OFFSET;

        transform.translation.z = player_z;
    }
}

What’s Changed?

This is a Bevy query filter that only matches entities whose Transform was modified this frame. It’s a performance optimization: we only recalculate Z when the player actually moves. If they’re standing still, the system skips them entirely.

Integrating Depth Sorting

Now, you can add it to the character system chain in src/characters/mod.rs after physics::apply_velocity:

// src/characters/mod.rs

mod rendering; // Line update alert!


.add_systems(Update, (
    // ... existing systems ...
    physics::apply_velocity,
    rendering::update_player_depth,  // Add after physics , line update alert!
    animation::tick_animations,
).chain().run_if(in_state(GameState::Playing)));

Adjusting Water Generation

Before running the game, make one small tweak to prevent the player from spawning in water. Open src/map/rules.rs and find the water layer weight:

// src/map/rules.rs - In build_water_layer function
const WATER_WEIGHT: f32 = 0.001;  // Reduce from 0.02 to 0.001

This reduces water generation, making it less likely the player spawns in an inaccessible area.

Run the game again:

cargo run

Now walk behind a tree. Your character should disappear behind the trunk! Walk back down, and they reappear. The illusion of depth makes the world feel three-dimensional even though it’s all 2D sprites.

What We Built

Let’s take a step back and appreciate what we’ve accomplished in this chapter:

Game States - Proper lifecycle management with Loading, Playing, and Paused states. No more polling patterns.
Character States - An enum-based state machine that prevents impossible states and simplifies animation logic.
Collision System - A tile-based collision map with circle colliders, swept collision for smooth wall-sliding, and shore detection for water edges.
Debug Visualization - Press F3 to see the collision map, player collider, and current grid cell.
Depth Sorting - Y-based rendering that creates the illusion of walking behind objects.

Your character can now walk through a procedurally generated world, colliding realistically with obstacles, sliding around corners, and disappearing behind trees. That’s a lot of systems working together!

In the next chapter, we’ll add interactivity: picking up items and building an inventory system. Until then, experiment with the collision parameters, try different collider sizes, and see how the debug visualization helps you understand what’s happening under the hood.

The Impatient Programmer’s Guide to Bevy and Rust: Chapter 3 - Let The Data Flow

2025-11-19T10:00:00+00:00

I was supposed to release this on Halloween, but my code was so scary it kept running away. 🎃 Now that we’ve debugged the ghosts in the machine, let’s begin!

By the end of this tutorial, you’ll have a flexible, data-driven character system that supports character switching, multiple animation types (Walk, Run, Jump) configured through a data file.

Prerequisites: This is Chapter 3 of our Bevy tutorial series. Join our community for updates on new releases. Before starting, complete Chapter 1: Let There Be a Player and Chapter 2: Let There Be a World, or clone the Chapter 2 code from this repository to follow along.

The Problem with Hardcoded Characters

In Chapter 1, we built a player with movement and animation, however everything was hardcoded and tightly coupled.

// Pseudo code warning, don't use
// From Chapter 1 player.rs - Everything is hardcoded!
const TILE_SIZE ... = 64;        // ← Hardcoded sprite size
const WALK_FRAMES ... = 9;     // ← Hardcoded frame count
const MOVE_SPEED ... = 140.0;    // ← Hardcoded movement speed
const ANIM_DT ... = 0.1;         // ← Hardcoded animation timing

Maintenance Nightmare

Let’s see what happens when you add a second character. You’d need to duplicate everything:

// Pseudo code warning, don't use
// First character
const WARRIOR_TILE_SIZE ... = 64;
const WARRIOR_WALK_FRAMES ... = 9;
const WARRIOR_MOVE_SPEED ... = 140.0;

fn spawn_warrior(...) { /* 50 lines of code */ }
fn animate_warrior(...) { /* 80 lines of animation logic */ }
fn warrior_row_zero_based(...) { /* row mapping */ }

// Second character - DUPLICATE ALL THE CODE
const MAGE_TILE_SIZE ... = 64;
const MAGE_WALK_FRAMES ... = 6;
const MAGE_MOVE_SPEED ... = 100.0;

fn spawn_mage(...) { /* 50 lines of IDENTICAL code */ }
fn animate_mage(...) { /* 80 lines of IDENTICAL animation logic */ }
fn mage_row_zero_based(...) { /* different row mapping */ }

Now imagine you discover a bug in your animation system. You need to fix it in:

animate_warrior()
animate_mage()
animate_rogue()
animate_paladin()
…and 6 more character functions

Miss one? That character breaks. Want to add a “jump” animation? Update 10 functions. Want to change how movement works? Touch every single character’s code.

This is the copy-paste maintenance nightmare you want to avoid.

Data-Driven Design

The solution lies in data-oriented programming, a design approach where we separate what things are (data) from what they do (behavior).

Instead of tightly coupling character attributes with character-specific code, we:

1. Separate Data from Code

Move character properties into a single external .ron configuration file:

// characters.ron, All characters in one file!
(
    characters: [
        (
            name: "Warrior",
            base_move_speed: 140.0,
            max_health: 150.0,
            animations: {...}
        ),
        (
            name: "Mage",
            base_move_speed: 100.0,
            max_health: 80.0,
            animations: {...}
        ),
    ]
)

What’s a .ron file?

RON stands for Rusty Object Notation, a data format similar to JSON but designed for Rust. It’s human-readable, supports Rust types like tuples and structs, and allows comments. Think of it as JSON that feels native to Rust developers.

JSON	RON
Requires quotes on every key	Optional quotes for simple identifiers
No comment support	Inline and multiline comments, document your data directly
Trailing commas cause syntax errors	Trailing commas allowed
Limited to JavaScript types	Native Rust types (tuples, structs, enums), matches your code

RON eliminates JSON’s verbosity while adding features that Rust developers need, making it ideal for game configuration.

2. Write Systems that Operate on Data

Build generic systems that work with any character data:

// Pseudo code warning, don't use
// Before: Code + Data mixed together
fn animate_warrior(...) { /* hardcoded warrior logic */ }
fn animate_mage(...) { /* hardcoded mage logic */ }

// After: Flexible system that operates on data
fn animate_characters(...) { 
    // Reads character data and animates accordingly
    // Works for warrior, mage, rogue, or any future character!
}

Benefits of Separation

When data lives separately from code, the same animation system adapts to any character automatically.

Fix a bug? One place. Change animation speeds or frame counts? Update the data file, no code changes. Switch characters? Load different data from the file.

But the benefits extend far beyond maintenance. This separation helps with powerful capabilities that would be difficult or impossible with hardcoded values.

You can load characters from a network server at runtime, enabling downloadable content and live game updates without redistributing your entire game binary.

Players can create their own custom characters by simply editing the .ron file, opening the door to user-generated content.

What We’ll Build in This Chapter:

While the data-driven approach opens up all these possibilities, we’ll start with the foundation:

Creating & loading external .ron file containing all character data
Generic animation system that works with any character
Runtime character switching with number keys (1-6)
Multiple animation types (Walk, Run, Jump) per character

Ready to build this data-driven character system? Let’s dive in!

Setting Up the Characters Module

Find the Chapter 3 project files from the repo and copy these spritesheets into your project’s src/assets/ directory:

male_spritesheet.png
female_spritesheet.png
crimson_count_spritesheet.png
graveyard_reaper_spritesheet.png
lantern_warden_spritesheet.png
starlit_oracle_spritesheet.png

Character Schema

Every entry in characters.ron follows the same structure:

name: Identifier that shows up in logs/UI.
max_health, base_move_speed, run_speed_multiplier: Gameplay attributes.
texture_path: Which spritesheet to load.
tile_size: Each frame’s width/height in pixels.
atlas_columns: How many columns exist in the spritesheet grid.
animations: Map where the key is an AnimationType (Walk, Run, Jump) and the value is:
- start_row: Row number in the spritesheet grid, counting from 0 at the top.
- frame_count: Number of frames for that animation.
- frame_time: Seconds per frame.
- directional: true when the spritesheet contains four direction rows (Up, Left, Down, Right) stacked vertically for that animation. If false, Bevy uses the same row regardless of facing direction.

Create a folder src/assets/characters/ and copy the characters.ron file from the repo and add place it inside the folder. It includes data for all 6 characters.

Setting Up the Config

With our data file in place, we need code that reads it and spawns the player. We’re going to replace the Chapter 1 player.rs with a new characters module.

Hence delete src/player.rs and remove mod player; and PlayerPlugin usage from main.rs.

Create a new folder src/characters/ and create the file config.rs inside it.

characters/
├── config.rs

First we need to define what type of animation are possible. Presently we only support Walk, Run and Jump animations. AnimationDefinition captures where each animation lives in the spritesheet, how many frames it has, and how fast it should play.

// characters/config.rs
use bevy::prelude::*;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum AnimationType {
    Walk,
    Run,
    Jump
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AnimationDefinition {
    pub start_row: usize,
    pub frame_count: usize,
    pub frame_time: f32,
    pub directional: bool, // true = 4 rows (one per direction), false = 1 row
}

What’s Hash, Serialize, and Deserialize?
Hash lets us use AnimationType as a key inside HashMap, so retrieving the settings for AnimationType::Run is just a dictionary lookup. Serialize and Deserialize allow Rust to turn these structs into .ron text (and back) automatically when you load or save character data.

With the animation schema in place, we can define CharacterEntry, the asset we load from characters.ron. It bundles character attributes, sprite metadata, and the animation map so every system pulls the info it needs from a single struct record.

Append the following code to characters/config.rs.

// Append this to characters/config.rs
#[derive(Component, Asset, TypePath, Debug, Clone, Serialize, Deserialize)]
pub struct CharacterEntry {
    pub name: String,
    pub max_health: f32,
    pub base_move_speed: f32,
    pub run_speed_multiplier: f32,
    pub texture_path: String,
    pub tile_size: u32,
    pub atlas_columns: usize,
    pub animations: HashMap<AnimationType, AnimationDefinition>,
}

impl CharacterEntry {
    pub fn calculate_max_animation_row(&self) -> usize {
        self.animations
            .values()
            .map(|def| if def.directional { def.start_row + 3 } else { def.start_row })
            .max()
            .unwrap_or(0)
    }
}

#[derive(Asset, TypePath, Debug, Clone, Serialize, Deserialize)]
pub struct CharactersList {
    pub characters: Vec<CharacterEntry>,
}

The calculate_max_animation_row helper inspects every animation definition to figure out how many rows the texture atlas needs.

Directional animations like Walk often consume four stacked rows (Up, Left, Down, Right), while others, say a climb animation, may only need a single row regardless of facing. This helper keeps those differences data-driven so atlas loading code can stay generic.

Is self.animations calling multiple functions sequentially?
Yes! This is called method chaining. Each function runs in order: first .values() gets all animation definitions from the HashMap, then .map() transforms each one, then .max() finds the largest value. They execute top-to-bottom, one after another.

What’s map doing, also is that a closure inside map?
map transforms each item in the collection. Yes, |def| is a closure as we studied in the previous chapter. It takes each animation definition (def) and calculates its maximum row: if the animation is directional (4 rows), it returns start_row + 3; otherwise just start_row. Think of it as “for each animation, calculate its end row.”

What’s unwrap_or?
max() returns an Option, it could be Some(number) if there are animations, or None if the HashMap is empty. unwrap_or(0) says “if you got a number, give it to me; if you got None, use 0 instead.” This prevents crashes when a character has no animations defined.

CharactersList groups all your CharacterEntry configs into one loadable asset, so Bevy can read every character’s data from a single JSON/RON file instead of loading many separate files.

What’s the purpose of using Asset, TypePath macros?
Asset simply tells Bevy “this struct is something you can load from disk and store in the asset server.” TypePath gives Bevy a unique name for the type so it knows exactly which asset you’re asking for later. Together they turn CharacterEntry/CharactersList into first-class loadable data, the same way textures or audio files already work.

What’s HashMap doing?
Each character needs different timing and sprite rows for Walk, Run, Jump, etc. The HashMap is simply a lookup table with key as AnimationType, so when the animation system asks for AnimationType::Run, it instantly receives the corresponding AnimationDefinition (start row, frame count, frame speed, directional flag).

Now that we have a data structure to hold our character information, we need a system to bring it to life.

The Animation Engine

Here we will be building the animation engine to interpret our data structure.

Create a new file src/characters/animation.rs. This will house the logic that brings our sprites to life.

characters/
├── config.rs
├── animation.rs  <- Create this

Our animation engine needs to help us with the following:

Direction Tracking: When your character moves right, you want them to face right. When they move up, they should face up. We need a system to convert movement into facing direction.
State Management: We need to know when to change animations. Did the player just start running? Just stop? Just jump? These transitions are when we reset the animation.
Frame Calculation: Given a character’s current state (“running left”), which exact frame from the spritesheet should we display right now?

Let’s build each piece.

Direction Tracking

When your player presses the arrow keys, we get a velocity vector like Vec2 { x: 1.0, y: 0.0 } for moving right. But our spritesheet doesn’t understand vectors—it has specific rows for Up, Down, Left, and Right animations.

We need to translate “moving in this direction” into “show this specific row of sprites.” That’s what the Facing enum does.

Add this to src/characters/animation.rs:

// src/characters/animation.rs
use bevy::prelude::*;
use serde::{Deserialize, Serialize};
use crate::characters::config::{CharacterEntry, AnimationType};

// Default animation timing (10 FPS = 0.1 seconds per frame)
pub const DEFAULT_ANIMATION_FRAME_TIME: f32 = 0.1;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
pub enum Facing {
    Up,
    Left,
    Down,
    Right,
}

impl Facing {
    // Convert a velocity vector into a discrete direction
    pub fn from_direction(direction: Vec2) -> Self {
        if direction.x.abs() > direction.y.abs() {
            if direction.x > 0.0 { Facing::Right } else { Facing::Left }
        } else {
            if direction.y > 0.0 { Facing::Up } else { Facing::Down }
        }
    }
    
    // Helper to map direction to row offset (0, 1, 2, 3)
    fn direction_index(self) -> usize {
        match self {
            Facing::Up => 0,
            Facing::Left => 1,
            Facing::Down => 2,
            Facing::Right => 3,
        }
    }
}

Converting Movement to Facing

The from_direction function takes a velocity vector and figures out which direction is dominant. If the player is moving diagonally (both x and y are non-zero), we pick the stronger component. Moving mostly right with a bit of up? Face right. Moving mostly up with a bit of right? Face up. This ensures your character always faces the most relevant direction during gameplay.

Mapping Direction to Sprite Rows

Our spritesheets follow a convention. For directional animations like “Walk”, the rows are organized as:

Row 0: Walk Up
Row 1: Walk Left
Row 2: Walk Down
Row 3: Walk Right

The direction_index function converts our Facing enum into these row offsets (0, 1, 2, 3). So when we know the player is facing Down and we want to play the “Walk” animation starting at row 8, we calculate: 8 + Facing::Down.direction_index() = 8 + 2 = row 10. That’s where the “Walk Down” frames live in the atlas.

Tracking Animation State

We need to know when to change animations. If your character transitions from standing still to running, we need to detect that moment and restart the animation from frame 0. Otherwise, the run animation might start mid-cycle, looking janky.

We need these components to track the current state of the animation.

AnimationController: It knows what animation we want to play (e.g., “Run”) and which way we are facing.
AnimationState: It tracks if we are moving or jumping, and importantly, if we were moving last frame. This helps us detect state changes (like starting to run) so we can reset the animation timer.
AnimationTimer: Controls how fast frames update.

Add these components to src/characters/animation.rs:

// Append this to src/characters/animation.rs
// Component that holds animation configuration
#[derive(Component)]
pub struct AnimationController {
    pub current_animation: AnimationType,
    pub facing: Facing,
}

impl Default for AnimationController {
    fn default() -> Self {
        Self {
            current_animation: AnimationType::Walk,
            facing: Facing::Down,
        }
    }
}

#[derive(Component, Default)]
pub struct AnimationState {
    pub is_moving: bool,
    pub was_moving: bool,
    pub is_jumping: bool,
    pub was_jumping: bool,
}

#[derive(Component, Deref, DerefMut)]
pub struct AnimationTimer(pub Timer);

You might notice we're using boolean flags (is_moving, was_moving, is_jumping, was_jumping) to track animation state. While this works for our current simple case, it's not the best approach for managing state transitions.As your game grows more complex (adding attacks, dodges, climbing, etc.), managing all these boolean combinations becomes error-prone and hard to maintain.

In Chapter 4, we'll learn about the state machine design pattern, which provides a much cleaner and more scalable way to handle state transitions. For now, we'll use this simpler approach to keep our focus on understanding the animation system fundamentals.

Frame Calculation

Now we know which animation to play (Walk, Run, Jump) and which direction the character is facing. But how do we translate that into “show frame 47 from the texture atlas right now”?

Think of the spritesheet as a numbered grid, reading left-to-right, top-to-bottom. If “Walk Down” is on row 2 and the grid has 12 columns, the first frame of that animation is at position 24 (because we skip the first 2 rows: 2 × 12 = 24). If the animation has 6 frames, we’ll cycle through positions 24, 25, 26, 27, 28, 29, then loop back to 24.

We’ll create an AnimationClip struct to handle this math for us.

// Append this to src/characters/animation.rs
// Runtime animation clip helper
#[derive(Clone, Copy)]
pub struct AnimationClip {
    first: usize,
    last: usize,
}

impl AnimationClip {
    pub fn new(row: usize, frame_count: usize, atlas_columns: usize) -> Self {
        let first = row * atlas_columns;
        Self {
            first,
            last: first + frame_count - 1,
        }
    }
    
    pub fn start(self) -> usize {
        self.first
    }
    
    // Check if a frame index belongs to this clip
    pub fn contains(self, index: usize) -> bool {
        (self.first..=self.last).contains(&index)
    }
    
    // Calculate the next frame, looping back to start if needed
    pub fn next(self, index: usize) -> usize {
        if index >= self.last {
            self.first
        } else {
            index + 1
        }
    }
    
    // Check if animation has completed (used for non-looping animations like Jump)
    pub fn is_complete(self, current_index: usize, timer_finished: bool) -> bool {
        current_index >= self.last && timer_finished
    }
}

The AnimationClip struct stores just two numbers: the first and last frame indices for a specific animation sequence. The new method calculates these indices from the row, frame count, and atlas width.

The start method returns where the animation begins. The contains method checks if a given frame index belongs to this clip (useful for detecting if we’ve wandered into the wrong animation). The next method advances to the next frame, automatically looping back to the start when we reach the end.

The is_complete method checks if we’ve reached the last frame and the timer has finished—this is crucial for non-looping animations like Jump, where we need to know when to transition back to Walk.

Connecting Clips to Controllers

Now that we have a way to represent frame ranges, we need to connect it to our AnimationController. Remember, the controller knows what animation to play (“Run”) and which direction we’re facing (“Left”). We’ll add a helper method that combines this information with the character’s configuration data to produce the correct AnimationClip.

Now we can add a method to AnimationController to easily get the current clip based on the character’s config:

// Append this to src/characters/animation.rs
impl AnimationController {
    pub fn get_clip(&self, config: &CharacterEntry) -> Option<AnimationClip> {
        // 1. Get the definition (e.g. "Walk" data)
        let def = config.animations.get(&self.current_animation)?;
        
        // 2. Calculate the actual row based on facing direction
        let row = if def.directional {
            def.start_row + self.facing.direction_index()
        } else {
            def.start_row
        };
        
        // 3. Create the clip
        Some(AnimationClip::new(row, def.frame_count, config.atlas_columns))
    }
}

Animating Characters

Finally, the system that ties it all together. This system runs every frame and:

Checks if the animation changed (e.g., started moving).
If changed, resets the timer and frame index.
If not changed, ticks the timer and advances the frame.

// Append this to src/characters/animation.rs
// Generic animation system - works for ALL entities
pub fn animate_characters(
    time: Res<Time>,
    mut query: Query<(
        &AnimationController,
        &AnimationState,
        &mut AnimationTimer,
        &mut Sprite,
        &CharacterEntry,
    )>,
) {
    for (animated, state, mut timer, mut sprite, config) in query.iter_mut() {
        
        let Some(atlas) = sprite.texture_atlas.as_mut() else { continue; };
        
        // Get the correct clip for current state/facing
        let Some(clip) = animated.get_clip(config) else { continue; };
        
        // Get timing info
        let Some(anim_def) = config.animations.get(&animated.current_animation) else { continue; };
        
        // Safety: If we somehow ended up on a frame outside our clip, reset.
        if !clip.contains(atlas.index) {
            atlas.index = clip.start();
            timer.0.reset();
        }
        
        // Detect state changes
        let just_started_moving = state.is_moving && !state.was_moving;
        let just_stopped_moving = !state.is_moving && state.was_moving;
        let just_started_jumping = state.is_jumping && !state.was_jumping;
        let just_stopped_jumping = !state.is_jumping && state.was_jumping;
        
        let should_animate = state.is_jumping || state.is_moving;
        let animation_changed = just_started_moving || just_started_jumping 
                              || just_stopped_moving || just_stopped_jumping;
        
        if animation_changed {
            // Reset animation
            atlas.index = clip.start();
            timer.0.set_duration(std::time::Duration::from_secs_f32(anim_def.frame_time));
            timer.0.reset();
        } else if should_animate {
            // Advance animation
            timer.tick(time.delta());
            if timer.just_finished() {
                atlas.index = clip.next(atlas.index);
            }
        } else {
            // When idle (not moving or jumping), stay on frame 0
            if atlas.index != clip.start() {
                atlas.index = clip.start();
            }
        }
    }
}

// Helper to update "was_moving" flags at the end of the frame
pub fn update_animation_flags(mut query: Query<&mut AnimationState>) {
    for mut state in query.iter_mut() {
        state.was_moving = state.is_moving;
        state.was_jumping = state.is_jumping;
    }
}

How the Animation System Works

The animation system has three branches that handle different scenarios:

Animation changed (starting/stopping movement or jumping): Reset to frame 0 and update the timer duration for the new animation.
Should animate (actively moving or jumping): Tick the timer and advance through frames.
Idle state (standing still): Ensure we stay on frame 0, the neutral standing pose.

Why State Change Detection Matters

The first branch relies on detecting the exact moment a state changes. is_moving tells us the current state (“am I moving right now?”), while was_moving tells us the previous frame’s state (“was I moving last frame?”). When is_moving is true but was_moving is false, we know the player just pressed a movement key.

This detection is crucial for smooth transitions. Without it, animations would continue from wherever they left off. Imagine your character’s walk cycle is on frame 5, then you press jump—without resetting, the jump animation would start at frame 5 instead of frame 0, looking broken.

The third branch (idle state) handles a different case: when the player stops moving, we transition to Walk animation but need to ensure we display the idle pose (frame 0), not whatever frame the walk cycle was on when they stopped.

Why do we need update_animation_flags?
We need update_animation_flags to run after all logic is done, so that in the next frame, was_moving correctly reflects the previous frame’s state. This allows us to detect the exact moment a state changes.

The Movement System

Our animation engine can display the right frames, but it needs to know what the player is doing. The AnimationController we built earlier stores the current animation state (“I’m running left”), but something needs to update that state based on player input. That’s where the movement system comes in. It reads keyboard input, moves the character, and tells the AnimationController which animation to play.

Create a new file src/characters/movement.rs:

characters/
├── config.rs
├── animation.rs
├── movement.rs  <- Create this

The movement system has three responsibilities:

Input Reading: Convert arrow key presses into a direction vector
Movement Calculation: Apply speed and delta time to move the character smoothly
Animation Coordination: Tell the animation system when to switch between Walk, Run, and Jump

Here’s how we’ll tackle this:

Reading Player Input

When the player presses arrow keys, we need to convert those discrete button presses into a continuous direction vector. If they press Up and Right simultaneously, we want Vec2 { x: 1.0, y: 1.0 } for diagonal movement.

Add this to src/characters/movement.rs:

// src/characters/movement.rs
use bevy::prelude::*;
use crate::characters::animation::*;
use crate::characters::config::{CharacterEntry, AnimationType};

/// Read directional input and return a direction vector
fn read_movement_input(input: &ButtonInput<KeyCode>) -> Vec2 {
    const MOVEMENT_KEYS: [(KeyCode, Vec2); 4] = [
        (KeyCode::ArrowLeft, Vec2::NEG_X),
        (KeyCode::ArrowRight, Vec2::X),
        (KeyCode::ArrowUp, Vec2::Y),
        (KeyCode::ArrowDown, Vec2::NEG_Y),
    ];
    
    MOVEMENT_KEYS.iter()
        .filter(|(key, _)| input.pressed(*key))
        .map(|(_, dir)| *dir)
        .sum()
}

What’s happening here?

We define a constant array mapping each arrow key to its direction vector. Vec2::NEG_X means “negative X direction” (left), Vec2::X means “positive X direction” (right), and so on.

Then we iterate through all four keys, filter to only the ones currently pressed, extract their direction vectors, and sum them. If both Up and Right are pressed, we get Vec2::Y + Vec2::X = Vec2 { x: 1.0, y: 1.0 }.

What’s _ in (keys, _) and in (_, dir)?

The _ (underscore) is Rust’s “I don’t care” placeholder in pattern matching. When destructuring tuples, you use _ to ignore values you don’t need:

In (key, _): We only need the key to check if it’s pressed, so we ignore the direction with _
In (_, dir): We only need the dir (direction vector), so we ignore the key with _

This is more readable than naming unused variables like (key, _unused_dir) or (_unused_key, dir). Rust’s compiler also knows these values are intentionally ignored, so you won’t get warnings about unused variables.

Calculating Movement Speed

Different characters move at different speeds. The Male character might be slower, while the Female character is faster. We also need to support running (holding Shift).

Add this helper function:

// Append this to src/characters/movement.rs
/// Calculate movement speed based on character config and running state
fn calculate_movement_speed(character: &CharacterEntry, is_running: bool) -> f32 {
    if is_running {
        character.base_move_speed * character.run_speed_multiplier
    } else {
        character.base_move_speed
    }
}

This reads the character’s base_move_speed from our data file and multiplies it by run_speed_multiplier if the player is holding Shift. All the speed values are data-driven—no hardcoded constants!

The Player Marker

We need a way to identify which entity is the player. We’ll use a simple marker component:

// Append this to src/characters/movement.rs
/// Marker component for the player entity
#[derive(Component)]
pub struct Player;

This component has no data, it’s just a tag. When we spawn the player entity, we’ll attach this component. Then our movement system can query for entities with Player to find the player. We have already studied this in the first chapter.

The Movement System

Now we tie it all together. This system runs every frame, reads input, calculates movement, and updates the animation state:

// Append this to src/characters/movement.rs
/// Handle player movement input and update transform/animation
pub fn move_player(
    input: Res<ButtonInput<KeyCode>>,
    time: Res<Time>,
    mut query: Query<(
        &mut Transform, 
        &mut AnimationController,
        &mut AnimationState,
        &CharacterEntry,
    ), With<Player>>,
) {
    let Ok((mut transform, mut animated, mut state, character)) = query.single_mut() else {
        return;
    };
    
    let direction = read_movement_input(&input);
    
    // Check for jump input (space key)
    if input.just_pressed(KeyCode::Space) {
        state.is_jumping = true;
        animated.current_animation = AnimationType::Jump;
    }
    
    // Check if running
    let is_running = input.pressed(KeyCode::ShiftLeft) || input.pressed(KeyCode::ShiftRight);
    
    // Handle movement
    if direction != Vec2::ZERO {
        let move_speed = calculate_movement_speed(character, is_running);
        let delta = direction.normalize() * move_speed * time.delta_secs();
        transform.translation += delta.extend(0.0);
        
        animated.facing = Facing::from_direction(direction);
        
        // Only update animation if not jumping
        if !state.is_jumping {
            state.is_moving = true;
            animated.current_animation = if is_running {
                AnimationType::Run
            } else {
                AnimationType::Walk
            };
        }
    } else if !state.is_jumping {
        state.is_moving = false;
        animated.current_animation = AnimationType::Walk;
    }
}

Breaking it down:

Query for the player: With filters to only entities with the Player component. single_mut() gets the one player entity.
Read input: Get the direction vector from arrow keys.
Handle jumping: If Space was just pressed, set is_jumping and switch to the Jump animation.
Check for running: Are either Shift keys pressed?
Move the character: If there’s input, normalize the direction (so diagonal movement isn’t faster), multiply by speed and delta time, and update the transform.

Update facing: Use our Facing::from_direction helper to determine which way to face.
Update animation: If not jumping, set the animation to Run or Walk based on whether Shift is held.

Handling Jump Completion

Jump animations are special, they have a beginning and an end. Unlike Walk or Run, which loop forever, Jump plays once and then we need to return to the idle state.

Add this system:

// Append this to src/characters/movement.rs
/// Monitor jump animation completion and reset state
pub fn update_jump_state(
    mut query: Query<(
        &mut AnimationController,
        &mut AnimationState,
        &AnimationTimer,
        &Sprite,
        &CharacterEntry,
    ), With<Player>>,
) {
    for (mut animated, mut state, timer, sprite, config) in query.iter_mut() {
        if !state.is_jumping {
            continue;
        }
        
        let Some(atlas) = sprite.texture_atlas.as_ref() else {
            continue;
        };
        
        let Some(clip) = animated.get_clip(config) else {
            continue;
        };
        
        // Check if jump animation has completed
        if clip.is_complete(atlas.index, timer.just_finished()) {
            state.is_jumping = false;
            animated.current_animation = AnimationType::Walk;
        }
    }
}

This system checks if the jump animation has reached its last frame and the timer has finished (using the is_complete method we defined earlier in AnimationClip). If so, it resets is_jumping to false and switches back to the Walk animation. The player can then move normally again.

What’s .as_ref()?

In the animation system, we used .as_mut() to get a mutable reference to the texture atlas so we could change the frame index. Here, we only need to read the current frame index, not modify it. The .as_ref() method converts Option into Option<&TextureAtlas>, giving us a read-only reference.

Spawning Characters

We have animation, movement, and data structures, but no actual character on screen yet! The spawn system is responsible for:

Loading the characters.ron file
Creating the player entity with all necessary components
Setting up the texture atlas from the spritesheet
Allowing runtime character switching with number keys (1-6)

Create a new file src/characters/spawn.rs:

characters/
├── config.rs
├── animation.rs
├── movement.rs
├── spawn.rs  <- Create this

Resources for Character Management

We’ll need two resources: one to track which character is currently active, and another to hold a reference to our loaded character data file.

Add this to src/characters/spawn.rs:

// src/characters/spawn.rs
use bevy::prelude::*;
use crate::characters::animation::*;
use crate::characters::config::{CharacterEntry, CharactersList};
use crate::characters::movement::Player;

const PLAYER_SCALE: f32 = 0.8;
const PLAYER_Z_POSITION: f32 = 20.0;

#[derive(Resource, Default)]
pub struct CurrentCharacterIndex {
    pub index: usize,
}

#[derive(Resource)]
pub struct CharactersListResource {
    pub handle: Handle<CharactersList>,
}

What are these resources for?

CurrentCharacterIndex: Tracks which character is currently active (0 = first character, 1 = second, etc.)
CharactersListResource: Stores the handle to our loaded characters.ron file. A handle is like a reference to an asset that Bevy is loading or has loaded.

How to decide between using resources and components?

Use Components for data that belongs to specific entities (like a player’s health, position, or animation state). Use Resources for global data that isn’t tied to any particular entity (like the current level number, game settings, or in our case, which character is active). Think of it this way: if you’d ask “which entity does this belong to?” and the answer is “all of them” or “none of them,” it’s probably a Resource.

What’s the Default macro?

The Default derive macro automatically implements the Default trait, which provides a default value for the struct. For usize, Rust’s default is 0. When you later in the chapter use init_resource::(), Bevy internally calls CurrentCharacterIndex::default(), which creates CurrentCharacterIndex { index: 0 }.

This is equivalent to manually writing:

// Pseudo code warning, don't use
impl Default for CurrentCharacterIndex {
    fn default() -> Self {
        Self { index: 0 }
    }
}

But the derive macro does it for us! Different types have different defaults: bool → false, String → "", Option → None, etc.

Creating the Texture Atlas Layout

Remember how we talked about spritesheets being grids of frames? Bevy doesn’t automatically know where one frame ends and another begins. We need to give it instructions: “Each frame is 64×64 pixels, there are 12 columns, and 8 rows.” That’s what a texture atlas layout does, it’s like a map that tells Bevy how to navigate the spritesheet.

This helper function creates that map:

// Append this to src/characters/spawn.rs
/// Create a texture atlas layout for a character
fn create_character_atlas_layout(
    atlas_layouts: &mut ResMut<Assets<TextureAtlasLayout>>,
    character_entry: &CharacterEntry,
) -> Handle<TextureAtlasLayout> {
    let max_row = character_entry.calculate_max_animation_row();
    
    atlas_layouts.add(TextureAtlasLayout::from_grid(
        UVec2::splat(character_entry.tile_size),
        character_entry.atlas_columns as u32,
        (max_row + 1) as u32,
        None,
        None,
    ))
}

Breaking it down:

calculate_max_animation_row(): We defined this earlier in CharacterEntry. It figures out how many rows the spritesheet needs based on all the animations.
UVec2::splat(tile_size): Creates a 2D vector where both x and y are the tile size (e.g., 64×64 pixels per frame).
from_grid(...): Tells Bevy “this texture is a grid with X columns and Y rows, each cell is this size.”

Spawning the Player Entity

Now we spawn the player. But here’s the catch: loading files from disk takes time. We can’t wait for characters.ron to load before creating the player entity, that would freeze the game during startup.

So we use a two stage approach: create a “placeholder” entity immediately, then fill in the details once the data finishes loading.

Stage 1: Create the entity

// Append this to src/characters/spawn.rs
pub fn spawn_player(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
    mut character_index: ResMut<CurrentCharacterIndex>,
) {
    // Load the characters list
    let characters_list_handle: Handle<CharactersList> = asset_server.load("characters/characters.ron");
    
    // Store the handle in a resource
    commands.insert_resource(CharactersListResource {
        handle: characters_list_handle,
    });
    
    // Initialize with first character
    character_index.index = 0;
    
    // Spawn player entity (will be initialized once asset loads)
    commands.spawn((
        Player,
        Transform::from_translation(Vec3::new(0.0, 0.0, PLAYER_Z_POSITION))
            .with_scale(Vec3::splat(PLAYER_SCALE)),
        Sprite::default(),
    ));
}

This system runs once at startup. It loads the characters.ron file, stores the handle in a resource, and spawns a player entity with just the Player marker, a Transform, and an empty Sprite. We can’t fully initialize it yet because the asset is still loading.

Why not load everything immediately?

Asset loading in Bevy is asynchronous. When you call asset_server.load(), Bevy starts loading the file in the background. It might take a few frames (or longer for large files). We need to wait until it’s ready.

Stage 2: Initialize once loaded

// Append this to src/characters/spawn.rs
pub fn initialize_player_character(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
    characters_lists: Res<Assets<CharactersList>>,
    character_index: Res<CurrentCharacterIndex>,
    characters_list_res: Option<Res<CharactersListResource>>,
    mut query: Query<Entity, (With<Player>, Without<AnimationController>)>,
) {
    let Some(characters_list_res) = characters_list_res else {
        return;
    };
    
    for entity in query.iter_mut() {
        let Some(characters_list) = characters_lists.get(&characters_list_res.handle) else {
            continue;
        };
        
        if character_index.index >= characters_list.characters.len() {
            continue;
        };
        
        let character_entry = &characters_list.characters[character_index.index];
        
        let texture = asset_server.load(&character_entry.texture_path);
        let layout = create_character_atlas_layout(&mut atlas_layouts, character_entry);
        
        let sprite = Sprite::from_atlas_image(
            texture,
            TextureAtlas {
                layout,
                index: 0,
            },
        );
        
        commands.entity(entity).insert((
            AnimationController::default(),
            AnimationState::default(),
            AnimationTimer(Timer::from_seconds(DEFAULT_ANIMATION_FRAME_TIME, TimerMode::Repeating)),
            character_entry.clone(),
            sprite,
        ));
    }
}

Earlier in Stage 1, we started loading characters.ron in the background. But we don’t know when it will finish—could be the next frame, could be 10 frames later.

This system runs every frame, checking: “Is the file loaded yet? Is there a player entity that still needs initialization?”

The query (With, Without) finds player entities that exist but haven’t been fully set up yet. Once the file loads, characters_lists.get() succeeds, and we can finally add all the animation components.

We grab the character data, load its texture, create the atlas layout, and insert all the necessary components.

Character Switching

One of the coolest features of our data-driven system: switching characters at runtime by pressing number keys!

// Append this to src/characters/spawn.rs
pub fn switch_character(
    input: Res<ButtonInput<KeyCode>>,
    mut character_index: ResMut<CurrentCharacterIndex>,
    characters_lists: Res<Assets<CharactersList>>,
    characters_list_res: Option<Res<CharactersListResource>>,
    mut query: Query<(
        &mut CharacterEntry,
        &mut Sprite,
    ), With<Player>>,
    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
    asset_server: Res<AssetServer>,
) {
    // Map digit keys to indices
    const DIGIT_KEYS: [KeyCode; 9] = [
        KeyCode::Digit1, KeyCode::Digit2, KeyCode::Digit3,
        KeyCode::Digit4, KeyCode::Digit5, KeyCode::Digit6,
        KeyCode::Digit7, KeyCode::Digit8, KeyCode::Digit9,
    ];
    
    // Find which digit key was pressed
    let new_index = DIGIT_KEYS.iter()
        .position(|&key| input.just_pressed(key));
    
    let Some(new_index) = new_index else {
        return;
    };
    
    let Some(characters_list_res) = characters_list_res else {
        return;
    };
    
    let Some(characters_list) = characters_lists.get(&characters_list_res.handle) else {
        return;
    };
    
    if new_index >= characters_list.characters.len() {
        return;
    }
    
    // Update character index
    character_index.index = new_index;
    
    // Update player entity
    let Ok((mut current_entry, mut sprite)) = query.single_mut() else {
        return;
    };
    
    let character_entry = &characters_list.characters[new_index];
    
    // Update character entry
    *current_entry = character_entry.clone();
    
    // Update sprite with new texture
    let texture = asset_server.load(&character_entry.texture_path);
    let layout = create_character_atlas_layout(&mut atlas_layouts, character_entry);
    
    *sprite = Sprite::from_atlas_image(
        texture,
        TextureAtlas {
            layout,
            index: 0,
        },
    );
}

How it works:

Detect key press: Check if any digit key (1-9) was just pressed.
Validate index: Make sure the index is within bounds (we have 6 characters, so keys 1-6 work).
Update resources: Set character_index.index to the new value.
Swap the character: Replace the CharacterEntry component with the new character’s data.
Update the sprite: Load the new character’s texture and create a new atlas layout.

This is the payoff of our data-driven design! Remember how in Chapter 1, adding a second character would have meant duplicating all the animation and movement code? Here, we just swap out the data. The animation system doesn’t care if it’s animating a Male character or a Crimson Count, it just reads the CharacterEntry component and does its job. Same with movement: it reads base_move_speed and run_speed_multiplier from the new character’s data. No code changes needed.

How does .position() work?

This iterator method searches through the array and returns the index of the first item where the condition is true. The closure |&key| input.just_pressed(key) checks each key: “was this key just pressed?” If the player presses Digit3, .position() returns Some(2) (because Digit3 is at index 2 in the array). If no digit key is pressed, it returns None. It’s similar to the filter operation.

What’s the * in *current_entry?

The * is the dereference operator. current_entry is a mutable reference (&mut CharacterEntry), not the actual data. To modify the data it points to, we need to dereference it with *. Think of it like this: current_entry is a pointer to a box, *current_entry is the contents of the box. We’re replacing the contents, not the pointer.

Bringing It All Together

We’ve built all the pieces: animation, movement, spawning, and character switching. Now we need to package them into a plugin and integrate it into our game.

Adding the RON Asset Loader

First, we need to add dependencies that let Bevy load .ron files and serialize/deserialize our data structures. Open Cargo.toml and add these to your [dependencies] section:

bevy_common_assets = { version = "0.15.0-rc.1", features = ["ron"] }
serde = { version = "1.0", features = ["derive"] }

The bevy_common_assets crate provides asset loaders for common file formats. We’re using the ron feature to load our characters.ron file. The serde crate with the derive feature allows us to use #[derive(Serialize, Deserialize)] on our structs, which we used in config.rs and animation.rs.

Creating the Characters Plugin

Create src/characters/mod.rs:

// src/characters/mod.rs
pub mod animation;
pub mod config;
pub mod movement;
pub mod spawn;

use bevy::prelude::*;
use bevy_common_assets::ron::RonAssetPlugin;
use config::CharactersList;

pub struct CharactersPlugin;

impl Plugin for CharactersPlugin {
    fn build(&self, app: &mut App) {
        app.add_plugins(RonAssetPlugin::<CharactersList>::new(&["characters.ron"]))
            .init_resource::<spawn::CurrentCharacterIndex>()
            .add_systems(Startup, spawn::spawn_player)
            .add_systems(Update, (
                spawn::initialize_player_character,
                spawn::switch_character,
                movement::move_player,
                movement::update_jump_state,
                animation::animate_characters,
                animation::update_animation_flags,
            ));
    }
}

Breaking it down:

Module declarations: pub mod animation; etc. make our submodules accessible.
RonAssetPlugin: Registers the .ron file loader for our CharactersList type.
init_resource: Creates the CurrentCharacterIndex resource with its default value (0).
Startup systems: spawn_player runs once at game start.
Update systems: All other systems run every frame.

Why are we keeping initialize_player_character in the Update instead of Startup? Does it initialize player character every frame?

Good catch! The system does run every frame, but it doesn’t initialize the player every frame. Look at the query: Query, Without)>. This only matches player entities that don’t have an AnimationController yet.

Once we add the AnimationController component (which happens inside the system), the entity no longer matches the query, so the system does nothing on subsequent frames. It’s a self-terminating system—it runs until it finds and initializes uninitialized players, then effectively becomes a no-op.

We can’t put it in Startup because the characters.ron file might not be loaded yet when Startup runs. By putting it in Update, it keeps checking every frame: “Is the file loaded? Is there an uninitialized player?” Once both conditions are true, it initializes the player and then stops doing anything.

Plugging Into the Game

Now we connect our plugin to the main game. Open src/main.rs and add the module declaration at the top:

// Update line in src/main.rs
mod map;
mod characters;  // Add this line

Then add the plugin to your app:

// Update line in src/main.rs
fn main() {
    let map_size = map_pixel_dimensions();

    App::new()
        .insert_resource(ClearColor(Color::WHITE))
        .add_plugins(
            DefaultPlugins
                .set(AssetPlugin {
                    file_path: "src/assets".into(),
                    ..default()
                })
                .set(WindowPlugin {
                    primary_window: Some(Window {
                        resolution: WindowResolution::new(map_size.x as u32, map_size.y as u32),
                        resizable: false,
                        ..default()
                    }),
                    ..default()
                })
                .set(ImagePlugin::default_nearest()),
        )
        .add_plugins(ProcGenSimplePlugin::<Cartesian3D, Sprite>::default())
        .add_plugins(characters::CharactersPlugin)  // Add this line
        .add_systems(Startup, (setup_camera, setup_generator))
        .run();
}

That’s it! Run your game with cargo run, and you should see your character on screen. Press the arrow keys to move, hold Shift to run, press Space to jump, and press number keys 1-6 to switch characters!

The Impatient Programmer’s Guide to Bevy and Rust: Chapter 2 - Let There Be a World

2025-10-11T10:00:00+00:00

By the end of this tutorial, you’ll build a procedurally generated game world with layered terrain, water bodies, and props.

Prerequisites: This is Chapter 2 of our Bevy tutorial series. Join our community for updates on new releases. Before starting, complete Chapter 1: Let There Be a Player, or clone the Chapter 1 code from this repository to follow along.

Procedural Generation

I respect artists who hand craft tiles to build game worlds. But I belong to the impatient/lazy species.

I went on an exploration and came across procedural generation.

Little did I know the complexities involved. I was on the verge of giving up, however because of the comments and messages from readers of previous chapter, I kept going. And the enlightenment came three days ago, all the pieces fit together.

Basically it’s about automatically fitting things together like a jigsaw puzzle. To solve this problem, let’s again think in systems.

What do we need to generate the game world procedurally?

Tileset.
Sockets for tiles because only compatible tiles should fit.
Compatibility rules.
Magic algorithm that uses these components to generate a coherent world.

How does this magic algorithm work?

That “magic algorithm” has a name: Wave Function Collapse (WFC). The easiest way to see it is with a tiny Sudoku. Same idea: pick the cell with the fewest valid options, place a value, update neighbors, and repeat. If a choice leads to a dead end, undo that guess and try the next option.

Small 4×4 Sudoku

Let’s solve this step by step, focusing on the most constrained cells first.

Initial Puzzle: We need to fill in the empty cells (marked with dots) following Sudoku rules.

?	.	2	.
.	3	.	.
.	.	.	1
4	.	.	.

Step 1 — Finding the most constrained cell:
Let's analyze the top-left 2×2 box:

Row 1 already has: 2
Column 1 already has: 4
Top-left box already has: 3
Available numbers: 1, 2, 3, 4
Eliminating: 2 (in row), 4 (in column), 3 (in box)
Only 1 remains!

1	.	2	.
.	3	.	.
.	.	.	1
4	.	.	.

Propagation Effect: Now that we placed 1, we can eliminate 1 from:

Row 1: ✓ (already done)
Column 1: ✓ (already done)
Top-left 2×2 box: ✓ (already done)

This makes other cells more constrained!

Step 2 — Next most constrained cell:
Now let's find the next cell with the fewest options.

1	?	2	.
.	3	.	.
.	.	.	1
4	.	.	.

Analysis for the position:

Row 1 already has: 1, 2
Column 2 already has: 3
Top-left box already has: 1, 3
Available numbers: 1, 2, 3, 4
Eliminating: 1 (in row), 2 (in row), 3 (in column and box)
Only 4 remains!

1	4	2	.
.	3	.	.
.	.	.	1
4	.	.	.

Key Insight
This is the essence of constraint propagation! Each placement immediately reduces the options for neighboring cells, making the puzzle progressively easier to solve.

We continue this process: pick the most constrained cell → place the only possible value → propagate constraints → repeat.

If any cell ends up with zero possibilities, we've hit a contradiction—in Sudoku, you backtrack and try a different value.

For our tile-based world: Imagine each grid cell as a Sudoku cell, but instead of numbers, we’re placing tiles.

Then we craft rules for valid connections:

Rule 1: Water center tiles connect to other water tiles on all sides
Rule 2: Water edge tiles have two types of sides - water-facing sides connect to other water tiles, land-facing sides connect to the shore

The algorithm uses these rules to ensure tiles fit together properly, creating coherent water bodies with natural-looking shorelines.

Let’s see this in action:

Step 1 - Initial Grid

?	?	?	?
?	?	?	?

We start with an empty grid where every cell can potentially hold any tile. The ? symbols represent the “superposition” - each cell contains all possible tiles until we begin constraining them through the algorithm.

Step 2 - First Placement

?	?	?	?
?		?	?

The algorithm starts by placing the initial water center tile. Following Rule 1, this center tile needs other water tiles on all sides. This immediately constrains the neighboring cells - they must be water tiles that can connect to the center.

Step 3 - Propagate Constraints

?			?
?			?

Constraint propagation kicks in! The algorithm expands the water area by placing more center tiles. The edge tiles at the top follow Rule 2 - their bottom sides (water-facing) connect to the center tiles, while their top sides (land-facing) will connect to the shore.

Step 4 - Final Result

The algorithm completes by filling the edges with appropriate boundary tiles. Notice how our rules create perfect connections - center tiles (Rule 1) have water on all sides, while edge and corner tiles (Rule 2) have water-facing sides connecting inward and land-facing sides connecting to the shore, creating a coherent geography.

This demonstrates the core Wave Function Collapse algorithm in action:

Find the most constrained cell - the one with the fewest valid tiles that could fit
Place a tile whose sockets are compatible with its neighbors
Propagate constraints - this placement immediately reduces the valid options for surrounding cells
Repeat until the grid is complete

When we hit a dead end (no valid tiles for a cell), our implementation takes a simpler approach than Sudoku: instead of backtracking through previous choices, we restart with a fresh random seed (up to a retry limit) and run the entire process again until we generate a valid map.

What do you mean by fresh random seed?

A “random seed” is a starting number that controls which “random” sequence the algorithm will follow. Same seed = same tile placement order every time. When we hit a dead end, instead of backtracking, we generate a new random seed and start over—this gives us a completely different sequence of tile choices to try.

Can configuring this randomness help us customize maps?

Yes! The algorithm’s randomness comes from the order in which it picks cells and tiles, and we can control this to influence the final result. By adjusting the random seed or the selection strategy, we can:

Bias toward certain patterns - Weight certain tiles more heavily to create specific landscape types.
Control size and complexity - Influence whether we get small ponds or large lakes.
Create predictable variations - Use the same seed for consistent results, or different seeds for variety.

The same tileset can generate endless variations of coherent landscapes, from simple ponds to complex branching river systems, all by tweaking the randomness probability configuration.

While Wave Function Collapse is powerful, it has its limitations.

No large-scale structure control - WFC focuses on tile compatibility, so it won't automatically create big patterns like "one large lake" or "mountain ranges".
Can get stuck - Complex rules might lead to impossible situations where no valid tiles remain, requiring restarts.
Performance depends on complexity - More tile types and stricter rules increase computation time and failure rates.
Requires careful rule design - Poorly designed compatibility rules can lead to unrealistic or broken landscapes.

We'll address these limitations in a later chapter. For now, we'll focus on building a functional section of our game world that will become the foundation for building larger game worlds.

From Theory to Implementation

Now that we understand how Wave Function Collapse works—the constraint propagation, socket compatibility, and tile placement logic. It’s time to transform this knowledge into actual running code.

The reality of implementation:

Building a WFC algorithm from scratch is complex. You’d need to implement:

Constraint propagation across the entire grid
Backtracking when hitting dead ends
Efficient data structures for tracking possibilities
Grid coordinate management
Random selection with proper probability weights

That’s a lot of algorithmic complexity before we even get to the game-specific parts, like sprites, rules, and world design.

Our approach:

Instead of reinventing the wheel, we’ll use a library that handles the WFC algorithm internals. This lets us focus on what makes our game unique: the tiles, the rules, the world aesthetics. We define what we want; the library figures out how to achieve it.

Setting Up Our Toolkit

Let’s add the procedural generation library to our project. We’ll be using the bevy_procedural_tilemaps crate, which I built by forking ghx_proc_gen library. I created this fork primarily to ensure compatibility with latest Bevy and to simplify this tutorial.

If you need advanced features, check out the original ghx_proc_gen crate by Gilles Henaux, which includes 3D capabilities and debugging tools.

Hope you are following the code from first chapter. Here’s the source code.

Update your Cargo.toml with the bevy_procedural_tilemaps crate.

[package]
name = "bevy_game"
version = "0.1.0"
edition = "2024" 

[dependencies]
bevy = "0.18" // Line update alert 
bevy_procedural_tilemaps = "0.2.0" // Line update alert

Bevy Procedural Tilemaps

The bevy_procedural_tilemaps library handles the complex logic of generating coherent, rule-based worlds.

What the library handles

The library takes care of the algorithmic complexity of procedural generation:

Rule Processing: Converts our game rules into the library’s internal format
Generator Creation: Builds the procedural generation engine with our configuration
Constraint Solving: Figures out which tiles can go where based on rules
Grid Management: Handles the 2D grid system and coordinate transformations
Entity Spawning: Creates Bevy entities and positions them correctly

What we need to provide

We need to give the library the game-specific information it needs:

Sprite Definitions: What sprites to use for each tile type
Compatibility Rules: Which tiles can be placed next to each other
Generation Configuration: The patterns and constraints for our specific game world
Asset Data: Sprite information, positioning, and custom components

Now that we understand how the procedural generation system works, let’s build our map module.

Important Note

Unlike Chapter 1 where you could see immediate results, procedural generation requires doing some ground work. You'll create asset loaders, tile spawning infrastructure before seeing your generated world.

The payoff comes when you finish the grass layer, at that point, you've learned the complete pattern. Adding water and props becomes straightforward repetition with different sprites and connection rules. Along the way, you'll understand Rust concepts (lifetimes, trait bounds, closures) that apply to any Rust project.

Don't give up if concepts feel unclear on first read. That's normal with procedural generation. Revisit confusing sections, experiment with the code, and understanding will emerge. Mastery comes through tinkering, not perfect comprehension on the first pass.

The Map Module

We’ll create a dedicated map folder inside the src folder to house all our world generation logic.

Why create a separate folder for map generation?

The map system requires multiple components working together. World generation involves:

Asset management - Loading and organizing hundreds of tile images.
Rule definitions - Compatibility rules between different terrain types.
Grid setup - Configuring map dimensions and coordinate systems.

Trying to fit all this logic into a single file would create a large file that can become difficult to navigate.

src/
├── main.rs
├── player.rs
└── map/
    ├── mod.rs       
    ├── assets.rs       

What’s mod.rs

The mod.rs file is Rust’s way of declaring what modules exist in a folder. It’s like the “table of contents” for our map module. Add the following line to your mod.rs.

// src/map/mod.rs
pub mod assets;   // Exposes assets.rs as a module

Why mod.rs specifically?

It’s Rust convention, when you create a folder, Rust looks for mod.rs to understand the module structure.

Creating SpawnableAsset

Let’s start by creating our assets.rs file inside the map folder. This will be the foundation that defines how we spawn sprites in our world.

The bevy_procedural_tilemaps library needs to know what to actually place at each generated location.

It requires the following details:

Which sprite to use from our tilemap atlas?
Where exactly to position it?
What components to add (collision, physics, etc.)?

The library expects us to provide this information in a very specific format. And doing this for every single tile type in your game - grass, dirt, trees, rocks, water, etc will result in redundant code.

This is where SpawnableAsset comes in. It’s our abstraction layer to help you avoid unnecessary boilerplate.

// src/map/assets.rs

use bevy::{prelude::*, sprite::Anchor};
use bevy_procedural_tilemaps::prelude::*;

#[derive(Clone)]
pub struct SpawnableAsset {
    /// Name of the sprite inside our tilemap atlas
    sprite_name: &'static str,
    /// Offset in grid coordinates (for multi-tile objects)
    grid_offset: GridDelta,
    /// Offset in world coordinates (fine positioning)
    offset: Vec3,
    /// Function to add custom components (like collision, physics, etc.)
    components_spawner: fn(&mut EntityCommands),
}

SpawnableAsset Struct

The SpawnableAsset struct contains all the information needed to spawn a tile in our world. The sprite_name field gives a name to your sprite (like “grass”, “tree”, “rock”).

The grid_offset is used for objects that span multiple tiles - it’s a positioning within the tile grid itself.

For example, the follow tree asset needs four tiles.

Grid Offset

Tree Part	Grid Offset	Description
Bottom-left	`(0, 0)`	Stays at original position
Bottom-right	`(1, 0)`	Moves one tile right
Top-left	`(0, 1)`	Moves one tile up
Top-right	`(1, 1)`	Moves one tile up and right

The offset field, on the other hand, is for fine-tuning the position within the tile - like moving a rock slightly to the left or making sure a tree trunk is perfectly centered within its tile space.

Let’s see how offset works with rock positioning:

Offset

Rock	Offset	Description
Rock 1	`(0, 0)`	Centered in tile
Rock 2	`(-8, -6)`	Moved slightly left and up
Rock 3	`(6, 5)`	Moved slightly right and down

Finally, the components_spawner is a function that adds custom behavior like collision, physics, or other game mechanics.

Why is sprite name defined as &'static str?

Let’s break down &'static str piece by piece to understand why we use it for sprite names.

The & symbol means “reference to” - instead of making a new copy of the text, we just note where the original text is located.

The 'static is a special lifetime annotation that tells Rust “this text will exist for the entire duration of your game.” When you write "grass" directly in your code, Rust bakes it into your game file when you build it. It’s always there, from game startup to shutdown.

What’s a lifetime and what has 'static got to do with it?

A lifetime is Rust’s way of tracking how long data lives in memory. Rust needs to know when it’s safe to use data and when it might be deleted.

Most data has a limited lifetime. For example:

Local variables live only while a function runs
Function parameters live only while the function executes
Data created in a loop might be deleted when the loop ends

But some data lives forever - like string literals embedded in your program. The 'static lifetime means “this data lives for the entire duration of the program” - it never gets deleted.

This is perfect for our sprite names because they’re hardcoded in our source code (like "grass", "tree", "rock") and will never change or be deleted while the program runs. Rust can safely let us use these references anywhere in our code because it knows the data will always be there.

What’s a string literal?

A string literal is text you write directly in quotes in your code: "grass", "dirt", "tree".

Why does Rust need to know when it’s safe to use data? Other languages don’t seem to care about this.

Most languages (like C, C++, Java, Python) handle memory safety differently:

C/C++: Don’t track lifetimes at all - you can accidentally use deleted data, leading to crashes or security vulnerabilities
Java/Python/C#: Use garbage collection - the runtime automatically deletes unused data, but this adds overhead and unpredictable pauses
Rust: Tracks lifetimes at compile time - prevents crashes without runtime overhead

The Problem Other Languages Have

// Psuedo code warning, don't use
// This would crash in C++ or cause undefined behavior
let sprite_name = {
    let temp = "grass";
    &temp  // temp gets deleted here!
}; 
println!("{}", sprite_name); // CRASH! Using deleted data

Rust Prevents This
Rust’s compiler analyzes your code and says “Hey, you’re trying to use data that might be deleted. I won’t let you compile this unsafe code.” This catches bugs before your game even runs.

Does str mean String data type?
Not quite. str represents text data, known as a string slice, but you can only use it through a reference like &str (a view of text stored somewhere else). String is text you own and can modify. Our sprite names like “grass” are baked into the program, so &str just points to that text without copying it - much more efficient than using String.

&'static str means “a reference (&), to a string slice (str) that lives for the entire program duration ('static).” This gives us the best of all worlds: memory efficiency (no copying), performance (direct access), and safety (Rust knows the data will always be valid).

What’s GridDelta?

GridDelta is a struct that represents movement in grid coordinates. It specifies “how many tiles to move” in each direction. For example, GridDelta::new(1, 0, 0) means “move one tile to the right”, while GridDelta::new(0, 1, 0) means “move one tile up”. It’s used for positioning multi-tile objects like the tree sprite with multiple tiles we mentioned earlier in grid offset.

Why’s components_spawner defined as fn(&mut EntityCommands)?

This is a function pointer that takes a mutable reference to EntityCommands (Bevy’s way of adding components to entities). Looking at the code in assets.rs, we can see it defaults to an empty function that does nothing.

The function pointer allows us to customize what components get added to each spawned entity. For example, a tree sprite might need collision components for physics, while a decorative flower might only need basic rendering components. Each sprite can have its own custom set of components without affecting others.

Why do we need a mutable reference to EntityCommands?

Yes! In Rust, you need a mutable reference (&mut) when you want to modify something. EntityCommands needs to be mutable because it’s used to add, remove, or modify components on entities.

Now let’s add some helpful methods to our SpawnableAsset struct to make it easier to create and configure sprite assets.

Append the following code to the same assets.rs file.

// src/map/assets.rs
impl SpawnableAsset {
    pub fn new(sprite_name: &'static str) -> Self {
        Self {
            sprite_name,
            grid_offset: GridDelta::new(0, 0, 0),
            offset: Vec3::ZERO,
            components_spawner: |_| {}, // Default: no extra components
        }
    }

    pub fn with_grid_offset(mut self, offset: GridDelta) -> Self {
        self.grid_offset = offset;
        self
    }
}

What’s -> Self?

In Rust, you must specify the return type of functions (unlike some languages that can infer it). The -> Self tells the compiler exactly what type the function returns, which helps catch errors at compile time. Self means “the same type as the struct this method belongs to” - so Self refers to SpawnableAsset here.

What’s |_| {}?

This is a closure (anonymous function) that does nothing. The |_| means “takes one parameter but ignores it” (the underscore means we don’t use the parameter), and {} is an empty function body.

We need this because our SpawnableAsset struct requires a components_spawner field (as we saw in the struct definition), but for basic sprites we don’t want to add any custom components. This empty closure serves as a “do nothing” default. We’ll learn how to use this field to add custom components in later chapters, but for now it’s just a placeholder that satisfies the struct’s requirements.

What’s a closure? What do you mean by anonymous function?

A closure is a function that can “capture” variables from its surrounding environment. An anonymous function means it doesn’t have a name - you define it inline where you need it, rather than declaring it separately like fn my_function().

Example usage

// Psuedo code warning, don't use
let mut player_health = 100;

// This closure captures 'player_health' by mutable reference
let mut take_damage = || {
    player_health -= 25;  // Modifies the original variable
    player_health
};

// The closure can modify the original variable
take_damage();  // player_health is now 75
take_damage();  // player_health is now 50

Why use closures here?

In our SpawnableAsset struct closure can be used to allow each sprite to have custom behavior when spawned. For example, a tree might need collision components, while a decorative flower might need different components. The closure can capture game state and configuration to customize spawning behavior for each sprite type.

Why is semicolon missing in the last line of these functions?

In Rust, the last expression in a function is automatically returned without needing a return keyword or semicolon. This makes it easier to specify what value should be returned - you just write the expression you want to return, and Rust handles the rest. This is Rust’s way of making code cleaner and more concise.

Why can’t you manipulate or retrieve grid_offset directly?

The fields of GridDelta are private (they have no pub keyword), which means they can only be accessed from within the module where GridDelta is defined. This is called “encapsulation” - it prevents developers from making mistakes by modifying the struct’s data directly, which could break the internal logic. We provide the public method with_grid_offset() to safely modify it while maintaining the struct’s integrity.

Now that we understand how to define our sprites with SpawnableAsset, how do we load and use these sprites in our game?

Loading Sprite Assets

Our game uses a sprite atlas - a single large image containing all our sprites. Bevy needs to know where each sprite is located within this image, and we need to avoid reloading the same image multiple times.

Create a folder tile_layers in your src/assets folder and place tilemap.png inside it, you can get it from this github repo.

The tilemap assets used in this example are based on 16x16 Game Assets by George Bailey, available on OpenGameArt under CC-BY 4.0 license. However, to follow this tutorial, please use tilemap.png provide from the chapter's github repo.

Now inside src/map folder create a file tilemap.rs. When you add a file inside map folder, ensure to register it in mod.rs by adding the line pub mod tilemap.

This is where our tilemap definition comes in - it acts as a “map” that tells Bevy the coordinates of every sprite in our atlas.

// src/map/tilemap.rs
use bevy::math::{URect, UVec2};

pub struct TilemapSprite {
    pub name: &'static str,
    pub pixel_x: u32,
    pub pixel_y: u32,
}

pub struct TilemapDefinition {
    pub tile_width: u32,
    pub tile_height: u32,
    pub atlas_width: u32,
    pub atlas_height: u32,
    pub sprites: &'static [TilemapSprite],
}

The TilemapSprite struct represents a single sprite within our atlas. It stores the sprite’s name (like “dirt” or “green_grass”) and its exact pixel coordinates within the atlas image.

The TilemapDefinition struct serves as the “blueprint” that Bevy uses to understand how to slice up our atlas image into individual sprites.

tile_width and tile_height - How big each individual sprite is (in our case, 32×32 pixels)
atlas_width and atlas_height - The total size of your entire sprite atlas image (the big image containing all sprites)
sprites - The list of all sprites in your atlas, each with its name and location

Though our tilemap stores sprite names and pixel coordinates, Bevy’s texture atlas system requires numeric indices and rectangular regions. These methods perform the necessary conversions.

Append the following code to your tilemap.rs.

// src/map/tilemap.rs

impl TilemapDefinition {
    pub const fn tile_size(&self) -> UVec2 {
        UVec2::new(self.tile_width, self.tile_height)
    }

    pub const fn atlas_size(&self) -> UVec2 {
        UVec2::new(self.atlas_width, self.atlas_height)
    }

    pub fn sprite_index(&self, name: &str) -> Option<usize> {
        self.sprites.iter().position(|sprite| sprite.name == name)
    }

    pub fn sprite_rect(&self, index: usize) -> URect {
        let sprite = &self.sprites[index];
        let min = UVec2::new(sprite.pixel_x, sprite.pixel_y);
        URect::from_corners(min, min + self.tile_size())
    }
}

The tile_size() method converts our tile dimensions into a UVec2 (unsigned 2D vector), which Bevy uses for size calculations. Similarly, atlas_size() provides the total atlas dimensions as a UVec2, which Bevy uses to create the texture atlas layout.

The sprite_index() method helps in finding sprites by name. When we want to render a “dirt” tile, this method searches through our sprite array and returns the index position of that sprite.

Finally, sprite_rect() takes a sprite index and calculates the exact rectangular region within our atlas that contains that sprite. It uses URect (unsigned rectangle) to define the boundaries, which Bevy’s texture atlas system requires to know which part of the large image to display.

Now let’s put our tilemap definition to use by adding our first sprite - the dirt tile.

Adding the Dirt Tile

Let’s start with a simple dirt tile to test our tilemap system. The dirt tile sits at pixel coordinates (128, 0) in our 256x320 atlas image. We’ll add more sprites later as we build out our game world.

Append this code to tilemap.rs

// src/map/tilemap.rs
pub const TILEMAP: TilemapDefinition = TilemapDefinition {
    tile_width: 32,
    tile_height: 32,
    atlas_width: 256,
    atlas_height: 320,
    sprites: &[
          TilemapSprite {
            name: "dirt",
            pixel_x: 128,
            pixel_y: 0,
        },
    ]
};

Notice how we’re using a const definition - this means all this sprite metadata is determined at compile time.

Connecting the Tilemap to Asset Loading

Now that we’ve defined our tilemap and sprites in tilemap.rs, we need to connect this to our asset loading system in assets.rs.

Let’s update the imports in assets.rs to bring in our TILEMAP definition:

// src/map/assets.rs
use bevy::prelude::*; 
use bevy_procedural_tilemaps::prelude::*;
use crate::map::tilemap::TILEMAP; // <--- line update alert

With the import in place, we can now build the three key functions that helps our procedural rendering system:

TilemapHandles - Container that holds our loaded atlas and layout data
prepare_tilemap_handles - Loads the atlas image from disk and creates the texture atlas layout defining each sprite’s rectangular region
load_assets - Converts sprite names into Sprite data structures ready for rendering

Let’s build these step by step.

Creating the TilemapHandles Struct

First, we need a way to hold references to both the atlas image and its layout. Go ahead and append this code into your assets.rs:

// src/map/assets.rs
#[derive(Clone)]
pub struct TilemapHandles {
    pub image: Handle<Image>,
    pub layout: Handle<TextureAtlasLayout>,
}

impl TilemapHandles {
    pub fn sprite(&self, atlas_index: usize) -> Sprite {
        Sprite::from_atlas_image(
            self.image.clone(),
            TextureAtlas::from(self.layout.clone()).with_index(atlas_index),
        )
    }
}

The TilemapHandles struct is a container for two handles: image points to our loaded sprite sheet file, while layout points to the atlas layout that tells Bevy how to slice that image into individual sprites.

The sprite(atlas_index) method is a convenience function that creates a ready-to-render Sprite by combining the image and layout with a specific index. For example, if the dirt tile is at index 0, calling tilemap_handles.sprite(0) gives us a Sprite configured to display just the dirt tile from our atlas.

Loading the Atlas from Disk

Now let’s create the function that actually loads the atlas image file and sets up the layout. We will be using our TILEMAP definition from earlier.

// src/map/assets.rs
pub fn prepare_tilemap_handles(
    asset_server: &Res<AssetServer>,
    atlas_layouts: &mut ResMut<Assets<TextureAtlasLayout>>,
    assets_directory: &str,
    tilemap_file: &str,
) -> TilemapHandles {
    let image = asset_server.load::<Image>(format!("{assets_directory}/{tilemap_file}"));
    let mut layout = TextureAtlasLayout::new_empty(TILEMAP.atlas_size());
    for index in 0..TILEMAP.sprites.len() {
        layout.add_texture(TILEMAP.sprite_rect(index));
    }
    let layout = atlas_layouts.add(layout);

    TilemapHandles { image, layout }
}

Breaking it down:

Load the image: asset_server.load() requests the atlas image file from disk
Create empty layout: TextureAtlasLayout::new_empty(TILEMAP.atlas_size()) creates a layout matching our 256x320 atlas
Register each sprite: The loop iterates through all sprites in TILEMAP, using TILEMAP.sprite_rect(index) to get each sprite’s coordinates and adding them to the layout
Store and return: The layout is added to Bevy’s asset system, and we return a TilemapHandles containing both handles

This is where TILEMAP.atlas_size() and TILEMAP.sprite_rect() from our tilemap definition come into play - they tell Bevy exactly how to slice up our atlas image!

This function loads the atlas into memory and sets up the layout structure, but it doesn't actually generate the game world yet. We're just preparing the tools that the procedural generator will use later to create the map.

Converting Sprite Names to Renderable Sprites

Finally, we need a way to convert sprite names (like “dirt”) into Sprite objects that can be rendered.

// src/map/assets.rs
pub fn load_assets(
    tilemap_handles: &TilemapHandles,
    assets_definitions: Vec<Vec<SpawnableAsset>>,
) -> ModelsAssets<Sprite> {
    let mut models_assets = ModelsAssets::<Sprite>::new();
    for (model_index, assets) in assets_definitions.into_iter().enumerate() {
        for asset_def in assets {
            let SpawnableAsset {
                sprite_name,
                grid_offset,
                offset,
                components_spawner,
            } = asset_def;

            let Some(atlas_index) = TILEMAP.sprite_index(sprite_name) else {
                panic!("Unknown atlas sprite '{}'", sprite_name);
            };

            models_assets.add(
                model_index,
                ModelAsset {
                    assets_bundle: tilemap_handles.sprite(atlas_index),
                    grid_offset,
                    world_offset: offset,
                    spawn_commands: components_spawner,
                },
            )
        }
    }
    models_assets
}

Why the two loops?

Some tiles are simple and need just one sprite (like dirt). Others are complex and need multiple sprites (like a tree that needs 4 parts).

The outer loop says “for each type of tile,” and the inner loop says “for each sprite that tile needs.”

Let’s walk through what happens when we load a dirt tile:

We have: SpawnableAsset { sprite_name: "dirt", ... }
The function asks TILEMAP: “Where is ‘dirt’?” → TILEMAP replies: “Index 0”
It then asks TilemapHandles: “Give me a Sprite for index 0” → Gets back a Sprite object
Finally, it packages everything together with the positioning info and stores it

What does the final data look like?

After load_assets completes, we have a collection of ModelAsset objects in memory. Here’s what the data structure looks like for a few tiles:

Model	Field	Value	What It Means
Dirt	`assets_bundle`	`Sprite(atlas_index: 0)`	Points to dirt sprite in atlas
	`grid_offset`	`(0, 0, 0)`	No grid offset needed
	`world_offset`	`(0, 0, 0)`	No world offset needed
Tree (bottom)	`assets_bundle`	`Sprite(atlas_index: 31)`	Points to tree bottom sprite
	`grid_offset`	`(0, 0, 0)`	Placed at base position
	`world_offset`	`(0, 0, 0)`	Centered
Tree (top)	`assets_bundle`	`Sprite(atlas_index: 30)`	Points to tree top sprite
	`grid_offset`	`(0, 1, 0)`	One tile up from bottom
	`world_offset`	`(0, 0, 0)`	Centered

Important: These are just data structures in memory - nothing is drawn on screen yet! The actual rendering happens later when the procedural generator uses these prepared ModelAsset objects to spawn entities.

Great Progress! You've made it through the foundation layer - sprites, tilemaps, and asset loading. Now we have the visual pieces (assets), but how does the generator know which tiles can be placed next to each other? That's where models and sockets come in!

From Tiles to Models

You already understand tiles - the individual visual pieces like grass, dirt, and water. Now we need to build models by adding sockets to these tiles and define connection rules so the generator can figure out valid placements.

How Models Expose Sockets

Models expose sockets - labeled connection points on each edge. Let’s look at a green grass model and see how it exposes sockets in different directions.

Horizontal Plane (x and y directions)

↑

      up (y_pos)

      grass.material
    
↓
←

        left (x_neg)

        grass.material
      
→

      GREEN
GRASS
    
←

        right (x_pos)

        grass.material
      
→
↑

      down (y_neg)

      grass.material
    
↓

Vertical Axis (z direction)

↑

      top (z_pos)

      grass.layer_up
    
↓

    GREEN
GRASS
  
↑

      bottom (z_neg)

      grass.layer_down
    
↓

How does z-axis make sense in a 2D game?

Even though we’re building a 2D game, the z-axis represents layering - Imagine stacking transparent sheets on top of each other. Here’s how it works with our yellow grass example:

The Layering System:

Dirt tiles form the base layer (ground level)
Green grass tiles can sit on top of dirt (one layer up)
Yellow grass tiles can sit on top of green grass (another layer up)

Building Models

Now that we understand how models expose sockets in all six directions, we need a way to create these models and link them to their visual sprites.

We’ll use a helper called TerrainModelBuilder that keeps models and sprites paired correctly as we build our world.

The TerrainModelBuilder

Create a new file models.rs inside the map folder, and don’t forget to add pub mod models; to your mod.rs.

// src/map/models.rs
use bevy_procedural_tilemaps::prelude::*;
use crate::map::assets::SpawnableAsset;

/// Utility wrapper that ensures model declarations and their asset bindings stay aligned.
pub struct TerrainModelBuilder {
    pub models: ModelCollection<Cartesian3D>,
    pub assets: Vec<Vec<SpawnableAsset>>,
}

The TerrainModelBuilder holds:

models: What the WFC algorithm uses
assets: The sprites for the respective model

Now let’s add these methods to the builder.

// src/map/models.rs
impl TerrainModelBuilder {
    pub fn new() -> Self {
        Self {
            models: ModelCollection::new(),
            assets: Vec::new(),
        }
    }

    pub fn create_model<T>(
        &mut self,
        template: T,
        assets: Vec<SpawnableAsset>,
    ) -> &mut Model<Cartesian3D>
    where
        T: Into<ModelTemplate<Cartesian3D>>,
    {
        let model_ref = self.models.create(template);
        self.assets.push(assets);
        model_ref
    }

    pub fn into_parts(self) -> (Vec<Vec<SpawnableAsset>>, ModelCollection<Cartesian3D>) {
        (self.assets, self.models)
    }
}

The new() method creates an empty builder to start with.

The create_model() method both a socket definition and the corresponding sprites, then adds them to their respective collections at the same index.

Finally, into_parts() splits the builder back into separate collections when you’re done building, so the assets can go to the renderer and the models can go to the WFC generator.

What’s doing in pub fn create_model?

The is Rust’s generic type parameter - it’s a placeholder that gets filled in with the actual type when you call the function. In our case, we might pass in different types of socket definitions (simple single-socket tiles or complex multi-socket tiles), but we want to perform the same operation on all of them.

Generics let us write one function that works with multiple types, as long as they can all be converted into a ModelTemplate. This is powerful because it means we can add new socket definition types in the future without changing our TerrainModelBuilder code.

What’s this where T: Into>?

This is a trait bound that tells Rust what capabilities the generic type T must have. The where clause says “T must be able to convert itself into a ModelTemplate (a 3D model template).”

Into is Rust’s way of saying “this type knows how to transform itself into that type” - like how a string can be converted into a number, or how our socket definitions can be converted into model templates. This means we can pass in any type that knows how to become a ModelTemplate - whether it’s simple single-socket tiles, complex multi-socket tiles, or even a custom socket type you create later.

This gives us flexibility while ensuring type safety. The compiler will catch any attempts to pass in a type that can’t be converted, preventing runtime errors!

Building the Foundation

Now that we understand how to keep models and assets synchronized, let’s start building our procedural world from the ground up. The dirt layer forms the foundation that everything else sits on.

Layers Make WFC Simpler

Without layers, we’d need to cram all our rules into a single layer: “water connects to water and grass”, “grass connects to grass and dirt”, “trees connect to grass”, “dirt connects to dirt” - plus all the edge cases and special connections.

This creates a massive web of interdependencies that makes the WFC algorithm struggle to find valid solutions.

By using layers, we break this complexity into manageable pieces. Each layer only needs to worry about its own connections, making the WFC algorithm much more likely to find valid solutions quickly.

Let’s create our dirt layer, make a new file sockets.rs inside the map folder, and don’t forget to add pub mod sockets; to your mod.rs.

// src/map/sockets.rs
use bevy_procedural_tilemaps::prelude::*;

pub struct TerrainSockets {
    pub dirt: DirtLayerSockets,
}

pub struct DirtLayerSockets {
    pub layer_up: Socket,      // What can sit on top of dirt
    pub layer_down: Socket,     // What dirt can sit on
    pub material: Socket,       // What dirt connects to horizontally
}

The dirt layer needs three types of sockets.

layer_up - This socket handles what can be placed in the layer above dirt. Remember layers are to separate rule cram concerns (water can be above grass without touching it).
layer_down - It handles what layer the dirt itself can be placed on. For the base layer, this will connect to void (empty space).
material - This takes care of horizontal connections between dirt tiles, ensuring they connect properly to form continuous ground.

Initializing the Sockets

Now we need to actually create these socket instances. Append this function to sockets.rs:

// src/map/sockets.rs
pub fn create_sockets(socket_collection: &mut SocketCollection) -> TerrainSockets {
    let mut new_socket = || -> Socket { socket_collection.create() };
    
    let sockets = TerrainSockets {
        dirt: DirtLayerSockets {
            layer_up: new_socket(),
            material: new_socket(),
            layer_down: new_socket(),
        },
    };
    sockets
}

The create_sockets function takes a SocketCollection and creates all our socket instances. The new_socket closure is a helper that calls socket_collection.create() to generate unique socket IDs. Each socket gets a unique identifier that the WFC algorithm uses to track compatibility rules.

Building the Dirt Layer

Now that we have our socket system defined and initialized, we need to create the rules that tell the WFC algorithm how to use these sockets. This is where we define models and how they connect to each other.

Create a new file rules.rs inside the map folder, and don’t forget to add pub mod rules; to your mod.rs.

// src/map/rules.rs
use crate::map::assets::SpawnableAsset;
use crate::map::models::TerrainModelBuilder;
use crate::map::sockets::*;
use bevy_procedural_tilemaps::prelude::*;

fn build_dirt_layer(
    terrain_model_builder: &mut TerrainModelBuilder,
    terrain_sockets: &TerrainSockets,
    socket_collection: &mut SocketCollection,
) {
    terrain_model_builder
        .create_model(
            SocketsCartesian3D::Simple {
                x_pos: terrain_sockets.dirt.material, // right
                x_neg: terrain_sockets.dirt.material, // left
                z_pos: terrain_sockets.dirt.layer_up, // top 
                z_neg: terrain_sockets.dirt.layer_down, // bottom
                y_pos: terrain_sockets.dirt.material, // up
                y_neg: terrain_sockets.dirt.material, // down
            },
            vec![SpawnableAsset::new("dirt")],
        )
        .with_weight(20.);

    socket_collection.add_connections(vec![(
        terrain_sockets.dirt.material,
        vec![terrain_sockets.dirt.material],
    )]);
}

Understanding the Dirt Layer Rules:

Creates a dirt model - Defines a tile that exposes sockets on all six sides
Exposes socket types - Horizontal sides expose dirt.material, vertical sides expose layer sockets
Assigns a sprite - SpawnableAsset::new("dirt") tells the renderer which sprite to use
Sets the weight - .with_weight(20.) makes dirt tiles 20 times more likely to be placed
Defines connection rules - add_connections tells WFC that dirt.material can connect to other dirt.material

This creates a simple but effective foundation layer that can form continuous ground while supporting other layers on top!

Now let’s append the build_world function that the generator will call to get all our dirt layer rules and models:

// src/map/rules.rs
pub fn build_world() -> (
    Vec<Vec<SpawnableAsset>>,
    ModelCollection<Cartesian3D>,
    SocketCollection,
) {
    let mut socket_collection = SocketCollection::new();
    let terrain_sockets = create_sockets(&mut socket_collection);

    let mut terrain_model_builder = TerrainModelBuilder::new();

    // Build dirt layer
    build_dirt_layer(
        &mut terrain_model_builder,
        &terrain_sockets,
        &mut socket_collection,
    );

    let (assets, models) = terrain_model_builder.into_parts();

    (assets, models, socket_collection)
}

What This Function Does:

Creates the socket collection - This is where all our socket connection rules are stored
Gets our socket definitions - Calls create_sockets() to get all the socket types we defined
Creates the model builder - This keeps our models and assets synchronized
Builds the dirt layer - Calls our build_dirt_layer function to create all the dirt models and rules
Returns the three collections - Assets for rendering, models for WFC rules, and socket collection for connections

This function is what the generator calls to get all the rules and models needed to create our procedural world!

Generating Dirt

Now that we have all our components - assets, models, sockets, and rules - we need to configure the procedural generation engine.

Create a new file generate.rs inside the map folder, and don’t forget to add pub mod generate; to your mod.rs.

// src/map/generate.rs
use bevy_procedural_tilemaps::prelude::*;
use bevy::prelude::*;

use crate::map::{
    assets::{load_assets, prepare_tilemap_handles},
    rules::build_world,
};

// -----------------  Configurable values ---------------------------
/// Modify these values to control the map size.
pub const GRID_X: u32 = 25;
pub const GRID_Y: u32 = 18;

// ------------------------------------------------------------------

const ASSETS_PATH: &str = "tile_layers";
const TILEMAP_FILE: &str = "tilemap.png";
/// Size of a block in world units (in Bevy 2d, 1 pixel is 1 world unit)
pub const TILE_SIZE: f32 = 32.;
/// Size of a grid node in world units
const NODE_SIZE: Vec3 = Vec3::new(TILE_SIZE, TILE_SIZE, 1.);

const ASSETS_SCALE: Vec3 = Vec3::ONE;
/// Number of z layers in the map, derived from the default terrain layers.
const GRID_Z: u32 = 1;

pub fn map_pixel_dimensions() -> Vec2 {
    Vec2::new(TILE_SIZE * GRID_X as f32, TILE_SIZE * GRID_Y as f32)
}

Understanding the Configuration Constants:

Let’s break down what each of these constants controls:

GRID_X and GRID_Y - These define the size of our generated world in tiles. A 25×18 grid means 450 total tiles (25 × 18 = 450). You can adjust these to create larger or smaller worlds, though larger grids may cause the WFC algorithm to struggle - we’ll address scaling issues in a later chapter.
TILE_SIZE - This is the size of each tile in world units. Since we’re using 32×32 pixel sprites, each tile takes up 32 world units. This affects how big your world appears on screen.
NODE_SIZE - This tells the generator how much space each grid cell occupies in the 3D world. Equal values = perfect tile fit, smaller NODE_SIZE = overlapping sprites, larger NODE_SIZE = gaps between tiles.
GRID_Z - This defines how many layers our world has. We’re currently using 1 layer for dirt, but we’ll add more layers later to stack different terrain types on top of each other (dirt, grass, yellow grass, water, props).
ASSETS_SCALE - This controls the size multiplier for sprites. Vec3::ONE means sprites render at their original size.

Now let’s append the setup_generator function that sets up our procedural generation engine:

// src/map/generate.rs
pub fn setup_generator(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
) {
    // 1. Rules Initialization - Get tile definitions and connection rules
    let (assets_definitions, models, socket_collection) = build_world();

    let rules = RulesBuilder::new_cartesian_3d(models, socket_collection)
        // Use ZForward as the up axis (rotation axis for models) since we are using Bevy in 2D
        .with_rotation_axis(Direction::ZForward)
        .build()
        .unwrap();

    // 2. Grid - Create 3D world space with wrapping behavior (false, false, false)
    let grid = CartesianGrid::new_cartesian_3d(GRID_X, GRID_Y, GRID_Z, false, false, false);

    // 3. Configuring the Algorithm - Set up WFC behavior
    let gen_builder = GeneratorBuilder::new()
        .with_rules(rules)
        .with_grid(grid.clone())
        .with_rng(RngMode::RandomSeed)
        .with_node_heuristic(NodeSelectionHeuristic::MinimumRemainingValue)
        .with_model_heuristic(ModelSelectionHeuristic::WeightedProbability);
    
    let generator = gen_builder.build().unwrap();

    // 4. Loading Assets - Load sprite atlas and convert to renderable assets
    let tilemap_handles =
        prepare_tilemap_handles(&asset_server, &mut atlas_layouts, ASSETS_PATH, TILEMAP_FILE);
    let models_assets = load_assets(&tilemap_handles, assets_definitions);

    // 5. Spawning the Generator - Create entity with Transform and NodesSpawner
    commands.spawn((
        Transform::from_translation(Vec3 {
            x: -TILE_SIZE * grid.size_x() as f32 / 2.,
            y: -TILE_SIZE * grid.size_y() as f32 / 2.,
            z: 0.,
        }),
        grid,
        generator,
        NodesSpawner::new(models_assets, NODE_SIZE, ASSETS_SCALE).with_z_offset_from_y(true),
    ));
}

Rules Initialization

This creates the constraint solver that the WFC algorithm uses. It takes our tile definitions and connection rules and converts them into a format the algorithm can understand.

Why Direction::ZForward?

Since we’re building a 2D game, we need to tell the system which axis to use for rotations. Direction::ZForward means tiles rotate around the Z-axis (pointing toward/away from the screen), which makes sense for a 2D top-down view.

Grid

This creates our world space where tiles will be placed. The three boolean parameters control wrapping behavior:

(false, false, false) - Most games like Minecraft, Terraria (hard boundaries)
(true, true, false) - Classic Asteroids or Pac-Man (wraps left-right and up-down)
(true, true, true) - Advanced simulations with infinite-feeling 3D worlds

Configuring the Algorithm

This is where we configure how the WFC algorithm behaves:

RngMode::RandomSeed - Uses random seeds (same seed = same world every time)
NodeSelectionHeuristic::MinimumRemainingValue - Always picks the most constrained cell (fewest valid tiles)
ModelSelectionHeuristic::WeightedProbability - Picks tiles based on their weights (higher weight = more likely)

Loading Assets and Spawning the Generator

prepare_tilemap_handles() loads our sprite atlas from disk, while load_assets() converts our sprite definitions into renderable assets.

The commands.spawn() creates the generator entity with a Transform that centers the world on screen and a NodesSpawner that handles the actual tile creation.

The with_z_offset_from_y(true) setting uses Y coordinates for Z-layer positioning - tiles higher up on screen render in front, creating natural depth ordering (e.g., tree at Y=10 appears in front of rock at Y=5).

Final Module Structure

Throughout this chapter, we’ve been building our procedural generation system across multiple files. Before we integrate everything into your main game, let’s make sure your src/map/mod.rs file includes all the modules we’ve created:

// src/map/mod.rs
pub mod generate;
pub mod assets;
pub mod models;
pub mod rules;
pub mod sockets;
pub mod tilemap;

Make sure your mod.rs file matches this structure before proceeding to the integration step.

Integrating the Generator into Your Game

Now that we’ve built our procedural generation system, we need to integrate it into our main game. We’ll update the main.rs file to include the procedural generation plugin and set up the window size to match our generated world.

Updating main.rs

We need to add the procedural generation plugin and configure the window size to match our generated world. Update your main.rs:

// src/main.rs
mod map;
mod player;

use bevy::{
    prelude::*,
    window::{Window, WindowPlugin, WindowResolution},
};

use bevy_procedural_tilemaps::prelude::*;

use crate::map::generate::{map_pixel_dimensions, setup_generator};
use crate::player::PlayerPlugin;

fn main() {
    let map_size = map_pixel_dimensions();

    App::new()
        .insert_resource(ClearColor(Color::WHITE))
        .add_plugins(
            DefaultPlugins
                .set(AssetPlugin {
                    file_path: "src/assets".into(),
                    ..default()
                })
                .set(WindowPlugin {
                    primary_window: Some(Window {
                        resolution: WindowResolution::new(map_size.x as u32, map_size.y as u32),
                        resizable: false,
                        ..default()
                    }),
                    ..default()
                })
                .set(ImagePlugin::default_nearest()),
        )
        .add_plugins(ProcGenSimplePlugin::<Cartesian3D, Sprite>::default())
        .add_systems(Startup, (setup_camera, setup_generator))
        .add_plugins(PlayerPlugin)
        .run();
}

fn setup_camera(mut commands: Commands) {
    commands.spawn(Camera2d);
}

What’s New:

Map module import - mod map; brings in our procedural generation code
Window sizing - map_pixel_dimensions() calculates the window size based on our grid dimensions
Procedural generation plugin - ProcGenSimplePlugin handles the WFC algorithm execution
Generator setup - setup_generator runs at startup to create our world
Image filtering - ImagePlugin::default_nearest() keeps pixel art crisp

Running Your Procedural World

Now run your game:

cargo run

You should see a procedurally generated world with dirt tiles following the rules we defined! The world will be centered on screen, and the window size will match your grid dimensions (25×18 tiles = 800×576 pixels).

Linux Users with Wayland: If you're seeing white lines appearing between tile rows in your tilemap, this is a known Bevy rendering issue that affects Linux systems using the Wayland display protocol. To resolve this, run your application using XWayland instead:

WINIT_UNIX_BACKEND=x11 WAYLAND_DISPLAY= cargo run

Where’s the player?

The player is actually there, but it’s rendering behind the dirt tiles.

We need to make the player render on top of other layers we have.

Add a Z position constant

// src/player.rs, please it below ANIM_DT const
const PLAYER_Z: f32 = 20.0; 

Update the spawn function to use this Z value and scale the player slightly down (for better visual proportion with our generated world).

// src/player.rs - Update the Transform line in spawn_player
Transform::from_translation(Vec3::new(0., 0., PLAYER_Z)).with_scale(Vec3::splat(0.8)),

Run your again:

cargo run

Your player renders in front of all tiles and looks proportional to the 32×32 tile world!

Adding the Grass Layer

Now that we have a working dirt foundation, let’s add grass on top. The grass layer will create patches of green grass that sit on the dirt, with proper edge tiles for smooth transitions.

Step 1: Adding Grass Sprites to the Tilemap

First, we need to add all the grass sprite coordinates to our tilemap. Append these sprites to the sprites array in tilemap.rs:

// src/map/tilemap.rs - Add these to the sprites array after the dirt sprite inside TilemapDefinition struct
TilemapSprite {
    name: "green_grass",
    pixel_x: 160,
    pixel_y: 0,
},
TilemapSprite {
    name: "green_grass_corner_in_tl",
    pixel_x: 192,
    pixel_y: 0,
},
TilemapSprite {
    name: "green_grass_corner_in_tr",
    pixel_x: 224,
    pixel_y: 0,
},
TilemapSprite {
    name: "green_grass_corner_in_bl",
    pixel_x: 192,
    pixel_y: 32,
},
TilemapSprite {
    name: "green_grass_corner_in_br",
    pixel_x: 224,
    pixel_y: 32,
},
TilemapSprite {
    name: "green_grass_corner_out_tl",
    pixel_x: 0,
    pixel_y: 64,
},
TilemapSprite {
    name: "green_grass_corner_out_tr",
    pixel_x: 32,
    pixel_y: 64,
},
TilemapSprite {
    name: "green_grass_corner_out_bl",
    pixel_x: 0,
    pixel_y: 96,
},
TilemapSprite {
    name: "green_grass_corner_out_br",
    pixel_x: 32,
    pixel_y: 96,
},
TilemapSprite {
    name: "green_grass_side_t",
    pixel_x: 64,
    pixel_y: 64,
},
TilemapSprite {
    name: "green_grass_side_r",
    pixel_x: 96,
    pixel_y: 64,
},
TilemapSprite {
    name: "green_grass_side_l",
    pixel_x: 64,
    pixel_y: 96,
},
TilemapSprite {
    name: "green_grass_side_b",
    pixel_x: 96,
    pixel_y: 96,
},

These sprites include the main grass tile, inner corners, outer corners, and side edges for smooth transitions between grass and dirt.

Step 2: Adding Grass Sockets

Now we need to define the sockets for the grass layer. Update your sockets.rs:

// src/map/sockets.rs - Add this struct after DirtLayerSockets
pub struct GrassLayerSockets {
    pub layer_up: Socket,
    pub layer_down: Socket,
    pub material: Socket,
    pub void_and_grass: Socket,
    pub grass_and_void: Socket,
    pub grass_fill_up: Socket,
}

Then update the TerrainSockets struct to include grass:

// src/map/sockets.rs - Update TerrainSockets
pub struct TerrainSockets {
    pub dirt: DirtLayerSockets,
    pub void: Socket, // line update alert
    pub grass: GrassLayerSockets, // line update alert
}

Finally, update the create_sockets function to initialize the grass sockets:

// src/map/sockets.rs - Update create_sockets function
pub fn create_sockets(socket_collection: &mut SocketCollection) -> TerrainSockets {
    let mut new_socket = || -> Socket { socket_collection.create() };
    
    let sockets = TerrainSockets {
        dirt: DirtLayerSockets {
            layer_up: new_socket(),
            material: new_socket(),
            layer_down: new_socket(),
        },
         // line update alert
        void: new_socket(), 
         // lines update alert
        grass: GrassLayerSockets {
            layer_up: new_socket(),
            material: new_socket(),
            layer_down: new_socket(),
            void_and_grass: new_socket(),
            grass_and_void: new_socket(),
            grass_fill_up: new_socket(),
        },
    };
    sockets
}

Why does grass need more sockets than dirt?

Dirt is simple - it fills the entire base layer, so every dirt tile connects to another dirt tile. Grass is different - it creates patches on top of dirt, which means grass tiles need to handle edges where grass meets empty space.

Here’s what each socket handles:

material - Connects grass to grass (like dirt’s material socket)
layer_up and layer_down - Vertical connections (like dirt)
void_and_grass - Transitions from empty space (left) to grass (right)
grass_and_void - Transitions from grass (left) to empty space (right)
grass_fill_up - Allows layers above to fill down into grass areas

These transition sockets (void_and_grass and grass_and_void) are what create smooth edges. Without them, grass patches would have hard, blocky borders instead of the curved corners and sides we want.

Step 3: Building the Grass Layer Rules

Now let’s create the function that builds the grass layer. Append this function to rules.rs:

// src/map/rules.rs - Add this function after build_dirt_layer
fn build_grass_layer(
    terrain_model_builder: &mut TerrainModelBuilder,
    terrain_sockets: &TerrainSockets,
    socket_collection: &mut SocketCollection,
) {
    // Void model - empty space above dirt where no grass exists
    terrain_model_builder.create_model(
        SocketsCartesian3D::Simple {
            x_pos: terrain_sockets.void,
            x_neg: terrain_sockets.void,
            z_pos: terrain_sockets.grass.layer_up,
            z_neg: terrain_sockets.grass.layer_down,
            y_pos: terrain_sockets.void,
            y_neg: terrain_sockets.void,
        },
        Vec::new(),
    );

    // Main grass tile
    terrain_model_builder
        .create_model(
            SocketsCartesian3D::Multiple {
                x_pos: vec![terrain_sockets.grass.material],
                x_neg: vec![terrain_sockets.grass.material],
                z_pos: vec![
                    terrain_sockets.grass.layer_up,
                    terrain_sockets.grass.grass_fill_up,
                ],
                z_neg: vec![terrain_sockets.grass.layer_down],
                y_pos: vec![terrain_sockets.grass.material],
                y_neg: vec![terrain_sockets.grass.material],
            },
            vec![SpawnableAsset::new("green_grass")],
        )
        .with_weight(5.);

    // Outer corner template
    let green_grass_corner_out = SocketsCartesian3D::Simple {
        x_pos: terrain_sockets.grass.void_and_grass,
        x_neg: terrain_sockets.void,
        z_pos: terrain_sockets.grass.layer_up,
        z_neg: terrain_sockets.grass.layer_down,
        y_pos: terrain_sockets.void,
        y_neg: terrain_sockets.grass.grass_and_void,
    }
    .to_template();

    // Inner corner template
    let green_grass_corner_in = SocketsCartesian3D::Simple {
        x_pos: terrain_sockets.grass.grass_and_void,
        x_neg: terrain_sockets.grass.material,
        z_pos: terrain_sockets.grass.layer_up,
        z_neg: terrain_sockets.grass.layer_down,
        y_pos: terrain_sockets.grass.material,
        y_neg: terrain_sockets.grass.void_and_grass,
    }
    .to_template();

    // Side edge template
    let green_grass_side = SocketsCartesian3D::Simple {
        x_pos: terrain_sockets.grass.void_and_grass,
        x_neg: terrain_sockets.grass.grass_and_void,
        z_pos: terrain_sockets.grass.layer_up,
        z_neg: terrain_sockets.grass.layer_down,
        y_pos: terrain_sockets.void,
        y_neg: terrain_sockets.grass.material,
    }
    .to_template();

    // Create rotated versions of outer corners
    terrain_model_builder.create_model(
        green_grass_corner_out.clone(),
        vec![SpawnableAsset::new("green_grass_corner_out_tl")],
    );
    terrain_model_builder.create_model(
        green_grass_corner_out.rotated(ModelRotation::Rot90, Direction::ZForward),
        vec![SpawnableAsset::new("green_grass_corner_out_bl")],
    );
    terrain_model_builder.create_model(
        green_grass_corner_out.rotated(ModelRotation::Rot180, Direction::ZForward),
        vec![SpawnableAsset::new("green_grass_corner_out_br")],
    );
    terrain_model_builder.create_model(
        green_grass_corner_out.rotated(ModelRotation::Rot270, Direction::ZForward),
        vec![SpawnableAsset::new("green_grass_corner_out_tr")],
    );

    // Create rotated versions of inner corners
    terrain_model_builder.create_model(
        green_grass_corner_in.clone(),
        vec![SpawnableAsset::new("green_grass_corner_in_tl")],
    );
    terrain_model_builder.create_model(
        green_grass_corner_in.rotated(ModelRotation::Rot90, Direction::ZForward),
        vec![SpawnableAsset::new("green_grass_corner_in_bl")],
    );
    terrain_model_builder.create_model(
        green_grass_corner_in.rotated(ModelRotation::Rot180, Direction::ZForward),
        vec![SpawnableAsset::new("green_grass_corner_in_br")],
    );
    terrain_model_builder.create_model(
        green_grass_corner_in.rotated(ModelRotation::Rot270, Direction::ZForward),
        vec![SpawnableAsset::new("green_grass_corner_in_tr")],
    );

    // Create rotated versions of side edges
    terrain_model_builder.create_model(
        green_grass_side.clone(),
        vec![SpawnableAsset::new("green_grass_side_t")],
    );
    terrain_model_builder.create_model(
        green_grass_side.rotated(ModelRotation::Rot90, Direction::ZForward),
        vec![SpawnableAsset::new("green_grass_side_l")],
    );
    terrain_model_builder.create_model(
        green_grass_side.rotated(ModelRotation::Rot180, Direction::ZForward),
        vec![SpawnableAsset::new("green_grass_side_b")],
    );
    terrain_model_builder.create_model(
        green_grass_side.rotated(ModelRotation::Rot270, Direction::ZForward),
        vec![SpawnableAsset::new("green_grass_side_r")],
    );

    // Add connection rules
    socket_collection.add_rotated_connection(
        terrain_sockets.dirt.layer_up,
        vec![terrain_sockets.grass.layer_down],
    );
    socket_collection.add_connections(vec![
        (terrain_sockets.void, vec![terrain_sockets.void]),
        (
            terrain_sockets.grass.material,
            vec![terrain_sockets.grass.material],
        ),
        (
            terrain_sockets.grass.void_and_grass,
            vec![terrain_sockets.grass.grass_and_void],
        ),
    ]);
}

Understanding the Grass Layer Function

This function does several things - let’s break it down step by step.

1. The Void Model - Empty Space

This creates an “invisible” tile - a spot where no grass grows. Notice Vec::new() means no sprite is rendered. The WFC algorithm needs this to create patches of grass rather than covering everything.

2. The Main Grass Tile

This is the center grass tile. All four horizontal sides use grass.material, meaning they connect to other grass tiles. The z_pos has two options - allowing either another layer above OR the special grass_fill_up socket for yellow grass later.

A template is a reusable socket pattern. Instead of writing the same socket configuration four times (once for each rotation), we create it once and rotate it. The .to_template() converts it into a format that can be rotated.

4. Understanding Rotation - What’s Actually Happening?

We’re rotating the socket pattern.

Each tile has a sprite (the visual) and sockets (the connection rules). When we rotate a template, the sockets shift to different edges.

How Socket Rotation Works

Original Template (0°)

Sockets:
Left: void
Right: void_and_grass
Forward: void
Backward: grass_and_void

After 90° Rotation

Sockets:
Left: void
Right: grass_and_void
Forward: void_and_grass
Backward: void

Notice: the sprites are different (top-left vs bottom-left corner), but the socket pattern shifted clockwise by 90°. The void_and_grass socket moved from the right edge to the forward edge.

This is powerful because we define one socket pattern and pair it with different sprites at different rotations. The result: four unique corner models from one template definition.

We do the same for corner inside and side edges of grass tiles as well.

5. How Simple Rules Create Coherent Shapes

Here’s where the magic happens. We define only three connection rules, yet they create complex, natural-looking grass patches. Let’s see how.

The Three Rules:

void connects to void - Empty space stays empty
grass.material connects to grass.material - Grass centers connect to each other
void_and_grass connects to grass_and_void - Transition sockets create smooth edges

That’s it! But how do these simple rules create coherent grass patches? Let’s visualize a 3×3 grass patch forming:

How a Grass Patch Forms

Why Every Edge Matches Perfectly:

Let’s trace through the top row to understand how sockets work. Remember: each tile has sockets on its edges that define what can connect to it.

Look at the grass tile on the top left - green_grass_corner_out_tl tile (second row, second column in the grid above). This tile has a socket called void_and_grass on its right edge

Now look at the green_grass_side_t tile immediately to its right. This tile has a socket called grass_and_void on its left edge. When these two tiles sit next to each other, their edges touch. The void_and_grass socket (from the corner) connects to the grass_and_void socket (from the side) because of Rule 3

The same pattern repeats across the entire grid. green_grass_side_t has grass_and_void on its right edge. green_grass_corner_out_tr has void_and_grass on its left edge. Where they touch, these sockets match perfectly!

The green_grass center tile has material sockets on all edges, so it connects to any adjacent grass tile that also has material on the touching edge.

The WFC algorithm uses these three simple rules to check every tile placement. Before placing a tile, it verifies that all its sockets match the sockets of neighboring tiles. The result: organic-looking grass patches with smooth, curved edges!

6. Layer Connections

This tells the WFC algorithm that grass can sit on top of dirt. The add_rotated_connection means this rule applies regardless of how the tiles are rotated - grass can always sit on dirt.

Step 4: Calling the Grass Layer Function

Now update the build_world function to call build_grass_layer:

// src/map/rules.rs - Update build_world function
pub fn build_world() -> (
    Vec<Vec<SpawnableAsset>>,
    ModelCollection<Cartesian3D>,
    SocketCollection,
) {
    let mut socket_collection = SocketCollection::new();
    let terrain_sockets = create_sockets(&mut socket_collection);

    let mut terrain_model_builder = TerrainModelBuilder::new();

    // Build dirt layer
    build_dirt_layer(
        &mut terrain_model_builder,
        &terrain_sockets,
        &mut socket_collection,
    );

    // Line update alert
    // Build grass layer
    build_grass_layer(
        &mut terrain_model_builder,
        &terrain_sockets,
        &mut socket_collection,
    );

    let (assets, models) = terrain_model_builder.into_parts();

    (assets, models, socket_collection)
}

Step 5: Updating Grid Layers

Finally, update generate.rs to use 2 layers instead of 1:

// src/map/generate.rs - Update GRID_Z constant
const GRID_Z: u32 = 2;

Now run your game:

cargo run

You should see patches of green grass growing on top of the dirt layer, with smooth edges and corners transitioning between grass and dirt!

Adding the Yellow Grass Layer

Now that we have green grass, let’s add yellow grass patches that can grow on top of it! Yellow grass creates visual variety and demonstrates how layers can stack.

Step 1: Add Yellow Grass Sprites to Tilemap

First, let’s add the yellow grass sprites to our tilemap definition. Open src/map/tilemap.rs and add these entries to the sprites array:

// src/map/tilemap.rs - Add these to the sprites array after the dirt sprite inside TilemapDefinition struct
TilemapSprite {
    name: "yellow_grass",
    pixel_x: 0,
    pixel_y: 256,
},
TilemapSprite {
    name: "yellow_grass_corner_in_tl",
    pixel_x: 32,
    pixel_y: 256,
},
TilemapSprite {
    name: "yellow_grass_corner_in_tr",
    pixel_x: 64,
    pixel_y: 256,
},
TilemapSprite {
    name: "yellow_grass_corner_in_bl",
    pixel_x: 32,
    pixel_y: 288,
},
TilemapSprite {
    name: "yellow_grass_corner_in_br",
    pixel_x: 64,
    pixel_y: 288,
},
TilemapSprite {
    name: "yellow_grass_corner_out_tl",
    pixel_x: 96,
    pixel_y: 256,
},
TilemapSprite {
    name: "yellow_grass_corner_out_tr",
    pixel_x: 128,
    pixel_y: 256,
},
TilemapSprite {
    name: "yellow_grass_corner_out_bl",
    pixel_x: 96,
    pixel_y: 288,
},
TilemapSprite {
    name: "yellow_grass_corner_out_br",
    pixel_x: 128,
    pixel_y: 288,
},
TilemapSprite {
    name: "yellow_grass_side_t",
    pixel_x: 160,
    pixel_y: 256,
},
TilemapSprite {
    name: "yellow_grass_side_r",
    pixel_x: 192,
    pixel_y: 256,
},
TilemapSprite {
    name: "yellow_grass_side_l",
    pixel_x: 160,
    pixel_y: 288,
},
TilemapSprite {
    name: "yellow_grass_side_b",
    pixel_x: 192,
    pixel_y: 288,
},

Step 2: Define Yellow Grass Sockets

Yellow grass has a special behavior - it sits on top of green grass, not on dirt. This means it needs different socket connections.

Add the socket structure to src/map/sockets.rs:

// src/map/sockets.rs - Add after GrassLayerSockets
pub struct YellowGrassLayerSockets {
    pub layer_up: Socket,
    pub layer_down: Socket,
    pub yellow_grass_fill_down: Socket,
}

Then update TerrainSockets to include yellow grass:

// src/map/sockets.rs - Update TerrainSockets
pub struct TerrainSockets {
    pub dirt: DirtLayerSockets,
    pub void: Socket,
    pub grass: GrassLayerSockets,
    pub yellow_grass: YellowGrassLayerSockets, // Add this line
}

Finally, initialize the yellow grass sockets in create_sockets:

// src/map/sockets.rs - Update create_sockets function
pub fn create_sockets(socket_collection: &mut SocketCollection) -> TerrainSockets {
    let mut new_socket = || -> Socket { socket_collection.create() };
    
    let sockets = TerrainSockets {
        dirt: DirtLayerSockets {
            layer_up: new_socket(),
            material: new_socket(),
            layer_down: new_socket(),
        },
        void: new_socket(),
        grass: GrassLayerSockets {
            layer_up: new_socket(),
            material: new_socket(),
            layer_down: new_socket(),
            void_and_grass: new_socket(),
            grass_and_void: new_socket(),
            grass_fill_up: new_socket(),
        },
        yellow_grass: YellowGrassLayerSockets {
            layer_up: new_socket(),
            layer_down: new_socket(),
            yellow_grass_fill_down: new_socket(),
        },
    };
    sockets
}

Why does yellow grass only need 3 sockets?

Unlike green grass, yellow grass doesn’t need void_and_grass transition sockets. Why? Because yellow grass reuses the green grass edges. When yellow grass meets empty space, the green grass layer below provides the edge tiles. Yellow grass only appears where green grass already exists, so it uses green grass’s material socket for horizontal connections.

The yellow_grass_fill_down socket is special - it connects to green grass’s grass_fill_up socket, allowing yellow grass to “fill down” into the green grass layer below.

Step 3: Building the Yellow Grass Layer Rules

Now let’s create the function that builds the yellow grass layer. Add this function to rules.rs:

// src/map/rules.rs - Add this function after build_grass_layer
fn build_yellow_grass_layer(
    terrain_model_builder: &mut TerrainModelBuilder,
    terrain_sockets: &TerrainSockets,
    socket_collection: &mut SocketCollection,
) {
    // Void model - empty space where no yellow grass exists
    terrain_model_builder.create_model(
        SocketsCartesian3D::Simple {
            x_pos: terrain_sockets.void,
            x_neg: terrain_sockets.void,
            z_pos: terrain_sockets.yellow_grass.layer_up,
            z_neg: terrain_sockets.yellow_grass.layer_down,
            y_pos: terrain_sockets.void,
            y_neg: terrain_sockets.void,
        },
        Vec::new(),
    );

    // Main yellow grass tile
    terrain_model_builder
        .create_model(
            SocketsCartesian3D::Simple {
                x_pos: terrain_sockets.grass.material,
                x_neg: terrain_sockets.grass.material,
                z_pos: terrain_sockets.yellow_grass.layer_up,
                z_neg: terrain_sockets.yellow_grass.yellow_grass_fill_down,
                y_pos: terrain_sockets.grass.material,
                y_neg: terrain_sockets.grass.material,
            },
            vec![SpawnableAsset::new("yellow_grass")],
        )
        .with_weight(5.);

    // Outer corner template
    let yellow_grass_corner_out = SocketsCartesian3D::Simple {
        x_pos: terrain_sockets.grass.void_and_grass,
        x_neg: terrain_sockets.void,
        z_pos: terrain_sockets.yellow_grass.layer_up,
        z_neg: terrain_sockets.yellow_grass.yellow_grass_fill_down,
        y_pos: terrain_sockets.void,
        y_neg: terrain_sockets.grass.grass_and_void,
    }
    .to_template();

    // Inner corner template
    let yellow_grass_corner_in = SocketsCartesian3D::Simple {
        x_pos: terrain_sockets.grass.grass_and_void,
        x_neg: terrain_sockets.grass.material,
        z_pos: terrain_sockets.yellow_grass.layer_up,
        z_neg: terrain_sockets.yellow_grass.yellow_grass_fill_down,
        y_pos: terrain_sockets.grass.material,
        y_neg: terrain_sockets.grass.void_and_grass,
    }
    .to_template();

    // Side edge template
    let yellow_grass_side = SocketsCartesian3D::Simple {
        x_pos: terrain_sockets.grass.void_and_grass,
        x_neg: terrain_sockets.grass.grass_and_void,
        z_pos: terrain_sockets.yellow_grass.layer_up,
        z_neg: terrain_sockets.yellow_grass.yellow_grass_fill_down,
        y_pos: terrain_sockets.void,
        y_neg: terrain_sockets.grass.material,
    }
    .to_template();

    // Create rotated versions of outer corners
    terrain_model_builder.create_model(
        yellow_grass_corner_out.clone(),
        vec![SpawnableAsset::new("yellow_grass_corner_out_tl")],
    );
    terrain_model_builder.create_model(
        yellow_grass_corner_out.rotated(ModelRotation::Rot90, Direction::ZForward),
        vec![SpawnableAsset::new("yellow_grass_corner_out_bl")],
    );
    terrain_model_builder.create_model(
        yellow_grass_corner_out.rotated(ModelRotation::Rot180, Direction::ZForward),
        vec![SpawnableAsset::new("yellow_grass_corner_out_br")],
    );
    terrain_model_builder.create_model(
        yellow_grass_corner_out.rotated(ModelRotation::Rot270, Direction::ZForward),
        vec![SpawnableAsset::new("yellow_grass_corner_out_tr")],
    );

    // Create rotated versions of inner corners
    terrain_model_builder.create_model(
        yellow_grass_corner_in.clone(),
        vec![SpawnableAsset::new("yellow_grass_corner_in_tl")],
    );
    terrain_model_builder.create_model(
        yellow_grass_corner_in.rotated(ModelRotation::Rot90, Direction::ZForward),
        vec![SpawnableAsset::new("yellow_grass_corner_in_bl")],
    );
    terrain_model_builder.create_model(
        yellow_grass_corner_in.rotated(ModelRotation::Rot180, Direction::ZForward),
        vec![SpawnableAsset::new("yellow_grass_corner_in_br")],
    );
    terrain_model_builder.create_model(
        yellow_grass_corner_in.rotated(ModelRotation::Rot270, Direction::ZForward),
        vec![SpawnableAsset::new("yellow_grass_corner_in_tr")],
    );

    // Create rotated versions of side edges
    terrain_model_builder.create_model(
        yellow_grass_side.clone(),
        vec![SpawnableAsset::new("yellow_grass_side_t")],
    );
    terrain_model_builder.create_model(
        yellow_grass_side.rotated(ModelRotation::Rot90, Direction::ZForward),
        vec![SpawnableAsset::new("yellow_grass_side_l")],
    );
    terrain_model_builder.create_model(
        yellow_grass_side.rotated(ModelRotation::Rot180, Direction::ZForward),
        vec![SpawnableAsset::new("yellow_grass_side_b")],
    );
    terrain_model_builder.create_model(
        yellow_grass_side.rotated(ModelRotation::Rot270, Direction::ZForward),
        vec![SpawnableAsset::new("yellow_grass_side_r")],
    );

    // Add connection rules
    socket_collection
        .add_rotated_connection(
            terrain_sockets.grass.layer_up,
            vec![terrain_sockets.yellow_grass.layer_down],
        )
        .add_rotated_connection(
            terrain_sockets.yellow_grass.yellow_grass_fill_down,
            vec![terrain_sockets.grass.grass_fill_up],
        );
}

Notice how the yellow grass models reuse green grass’s transition sockets (void_and_grass and grass_and_void) for horizontal connections. This is the clever part - yellow grass doesn’t define its own edges, it borrows them from green grass!

The connection rules establish two important relationships:

grass.layer_up connects to yellow_grass.layer_down - Yellow grass sits on top of green grass
yellow_grass_fill_down connects to grass_fill_up - This allows yellow grass to appear where green grass has the special “fill up” socket

Step 4: Calling the Yellow Grass Layer Function

Update build_world in rules.rs to call build_yellow_grass_layer:

// src/map/rules.rs - Update build_world function
pub fn build_world() -> (
    Vec<Vec<SpawnableAsset>>,
    ModelCollection<Cartesian3D>,
    SocketCollection,
) {
    let mut socket_collection = SocketCollection::new();
    let terrain_sockets = create_sockets(&mut socket_collection);

    let mut terrain_model_builder = TerrainModelBuilder::new();

    // Build dirt layer
    build_dirt_layer(
        &mut terrain_model_builder,
        &terrain_sockets,
        &mut socket_collection,
    );

    // Build grass layer
    build_grass_layer(
        &mut terrain_model_builder,
        &terrain_sockets,
        &mut socket_collection,
    );

    // Line update alert
    // Build yellow grass layer
    build_yellow_grass_layer(
        &mut terrain_model_builder,
        &terrain_sockets,
        &mut socket_collection,
    );

    let (assets, models) = terrain_model_builder.into_parts();

    (assets, models, socket_collection)
}

Step 5: Updating Grid Layers

We need one more layer for yellow grass. Update the constant in generate.rs:

// src/map/generate.rs - Update GRID_Z
const GRID_Z: u32 = 3; // Changed from 2 to 3

Now run your game:

cargo run

You should see yellow grass patches appearing on top of green grass, creating a beautiful layered terrain!

Adding the Water Layer

Water adds life to our procedural world! Unlike grass layers that stack on top of each other, water appears alongside yellow grass at the same layer level. This creates interesting terrain where water bodies can form near grassy areas.

Step 1: Add Water Sprites to Tilemap

First, let’s add the water sprites to our tilemap definition. Open src/map/tilemap.rs and add these entries to the sprites array:

// src/map/tilemap.rs - Add water sprites to the sprites array
TilemapSprite {
    name: "water",
    pixel_x: 32,
    pixel_y: 192,
},
TilemapSprite {
    name: "water_corner_in_tl",
    pixel_x: 64,
    pixel_y: 192,
},
TilemapSprite {
    name: "water_corner_in_tr",
    pixel_x: 96,
    pixel_y: 192,
},
TilemapSprite {
    name: "water_corner_in_bl",
    pixel_x: 64,
    pixel_y: 224,
},
TilemapSprite {
    name: "water_corner_in_br",
    pixel_x: 96,
    pixel_y: 224,
},
TilemapSprite {
    name: "water_corner_out_tl",
    pixel_x: 128,
    pixel_y: 192,
},
TilemapSprite {
    name: "water_corner_out_tr",
    pixel_x: 160,
    pixel_y: 192,
},
TilemapSprite {
    name: "water_corner_out_bl",
    pixel_x: 128,
    pixel_y: 224,
},
TilemapSprite {
    name: "water_corner_out_br",
    pixel_x: 160,
    pixel_y: 224,
},
TilemapSprite {
    name: "water_side_t",
    pixel_x: 192,
    pixel_y: 192,
},
TilemapSprite {
    name: "water_side_r",
    pixel_x: 224,
    pixel_y: 192,
},
TilemapSprite {
    name: "water_side_l",
    pixel_x: 192,
    pixel_y: 224,
},
TilemapSprite {
    name: "water_side_b",
    pixel_x: 224,
    pixel_y: 224,
},

Step 2: Define Water Sockets

Water goes on the next Z-layer above yellow grass. “Layer” here refers to the Z-coordinate in our 3D grid, not geological layers.

We’ve been stacking these: dirt at Z=0, green grass at Z=1, yellow grass at Z=2, and now water at Z=3.

At any grid position, you can have dirt at the bottom Z-level and water at a higher Z-level—they occupy the same X,Y position but different Z heights.

Add the socket structure to src/map/sockets.rs:

// src/map/sockets.rs - Add after YellowGrassLayerSockets
pub struct WaterLayerSockets {
    pub layer_up: Socket,
    pub layer_down: Socket,
    pub material: Socket,
    pub void_and_water: Socket,
    pub water_and_void: Socket,
    pub ground_up: Socket,
}

Then update TerrainSockets to include water:

// src/map/sockets.rs - Update TerrainSockets
pub struct TerrainSockets {
    pub dirt: DirtLayerSockets,
    pub void: Socket,
    pub grass: GrassLayerSockets,
    pub yellow_grass: YellowGrassLayerSockets,
    pub water: WaterLayerSockets, // Add this line
}

Finally, initialize the water sockets in create_sockets:

// src/map/sockets.rs - Update create_sockets function
pub fn create_sockets(socket_collection: &mut SocketCollection) -> TerrainSockets {
    let mut new_socket = || -> Socket { socket_collection.create() };
    
    let sockets = TerrainSockets {
        dirt: DirtLayerSockets {
            layer_up: new_socket(),
            material: new_socket(),
            layer_down: new_socket(),
        },
        void: new_socket(),
        grass: GrassLayerSockets {
            layer_up: new_socket(),
            material: new_socket(),
            layer_down: new_socket(),
            void_and_grass: new_socket(),
            grass_and_void: new_socket(),
            grass_fill_up: new_socket(),
        },
        yellow_grass: YellowGrassLayerSockets {
            layer_up: new_socket(),
            layer_down: new_socket(),
            yellow_grass_fill_down: new_socket(),
        },
        // Line update alert
        water: WaterLayerSockets {
            layer_up: new_socket(),
            layer_down: new_socket(),
            material: new_socket(),
            void_and_water: new_socket(),
            water_and_void: new_socket(),
            ground_up: new_socket(),
        },
    };
    sockets
}

Water has 6 sockets because it behaves like green grass - it creates patches with transitions:

material - Connects water to water (like grass’s material socket)
layer_up and layer_down - Vertical connections
void_and_water and water_and_void - Transition sockets for smooth edges
ground_up - Special socket that allows props above to know they’re not on water

Step 3: Building the Water Layer Rules

Now let’s create the function that builds the water layer. Add this function to rules.rs:

// src/map/rules.rs - Add this function after build_yellow_grass_layer
pub fn build_water_layer(
    terrain_model_builder: &mut TerrainModelBuilder,
    terrain_sockets: &TerrainSockets,
    socket_collection: &mut SocketCollection,
) {
    // Void model - represents land areas where no water exists
    terrain_model_builder.create_model(
        SocketsCartesian3D::Multiple {
            x_pos: vec![terrain_sockets.void],
            x_neg: vec![terrain_sockets.void],
            z_pos: vec![
                terrain_sockets.water.layer_up,
                terrain_sockets.water.ground_up,
            ],
            z_neg: vec![terrain_sockets.water.layer_down],
            y_pos: vec![terrain_sockets.void],
            y_neg: vec![terrain_sockets.void],
        },
        Vec::new(),
    );

    // Main water tile
    const WATER_WEIGHT: f32 = 0.02;
    terrain_model_builder
        .create_model(
            SocketsCartesian3D::Simple {
                x_pos: terrain_sockets.water.material,
                x_neg: terrain_sockets.water.material,
                z_pos: terrain_sockets.water.layer_up,
                z_neg: terrain_sockets.water.layer_down,
                y_pos: terrain_sockets.water.material,
                y_neg: terrain_sockets.water.material,
            },
            vec![SpawnableAsset::new("water")],
        )
        .with_weight(10. * WATER_WEIGHT);

    // Outer corner template
    let water_corner_out = SocketsCartesian3D::Simple {
        x_pos: terrain_sockets.water.void_and_water,
        x_neg: terrain_sockets.void,
        z_pos: terrain_sockets.water.layer_up,
        z_neg: terrain_sockets.water.layer_down,
        y_pos: terrain_sockets.void,
        y_neg: terrain_sockets.water.water_and_void,
    }
    .to_template()
    .with_weight(WATER_WEIGHT);

    // Inner corner template
    let water_corner_in = SocketsCartesian3D::Simple {
        x_pos: terrain_sockets.water.water_and_void,
        x_neg: terrain_sockets.water.material,
        z_pos: terrain_sockets.water.layer_up,
        z_neg: terrain_sockets.water.layer_down,
        y_pos: terrain_sockets.water.material,
        y_neg: terrain_sockets.water.void_and_water,
    }
    .to_template()
    .with_weight(WATER_WEIGHT);

    // Side edge template
    let water_side = SocketsCartesian3D::Simple {
        x_pos: terrain_sockets.water.void_and_water,
        x_neg: terrain_sockets.water.water_and_void,
        z_pos: terrain_sockets.water.layer_up,
        z_neg: terrain_sockets.water.layer_down,
        y_pos: terrain_sockets.void,
        y_neg: terrain_sockets.water.material,
    }
    .to_template()
    .with_weight(WATER_WEIGHT);

    // Create rotated versions of outer corners
    terrain_model_builder.create_model(
        water_corner_out.clone(),
        vec![SpawnableAsset::new("water_corner_out_tl")],
    );
    terrain_model_builder.create_model(
        water_corner_out.rotated(ModelRotation::Rot90, Direction::ZForward),
        vec![SpawnableAsset::new("water_corner_out_bl")],
    );
    terrain_model_builder.create_model(
        water_corner_out.rotated(ModelRotation::Rot180, Direction::ZForward),
        vec![SpawnableAsset::new("water_corner_out_br")],
    );
    terrain_model_builder.create_model(
        water_corner_out.rotated(ModelRotation::Rot270, Direction::ZForward),
        vec![SpawnableAsset::new("water_corner_out_tr")],
    );

    // Create rotated versions of inner corners
    terrain_model_builder.create_model(
        water_corner_in.clone(),
        vec![SpawnableAsset::new("water_corner_in_tl")],
    );
    terrain_model_builder.create_model(
        water_corner_in.rotated(ModelRotation::Rot90, Direction::ZForward),
        vec![SpawnableAsset::new("water_corner_in_bl")],
    );
    terrain_model_builder.create_model(
        water_corner_in.rotated(ModelRotation::Rot180, Direction::ZForward),
        vec![SpawnableAsset::new("water_corner_in_br")],
    );
    terrain_model_builder.create_model(
        water_corner_in.rotated(ModelRotation::Rot270, Direction::ZForward),
        vec![SpawnableAsset::new("water_corner_in_tr")],
    );

    // Create rotated versions of side edges
    terrain_model_builder.create_model(
        water_side.clone(),
        vec![SpawnableAsset::new("water_side_t")],
    );
    terrain_model_builder.create_model(
        water_side.rotated(ModelRotation::Rot90, Direction::ZForward),
        vec![SpawnableAsset::new("water_side_l")],
    );
    terrain_model_builder.create_model(
        water_side.rotated(ModelRotation::Rot180, Direction::ZForward),
        vec![SpawnableAsset::new("water_side_b")],
    );
    terrain_model_builder.create_model(
        water_side.rotated(ModelRotation::Rot270, Direction::ZForward),
        vec![SpawnableAsset::new("water_side_r")],
    );

    // Add connection rules
    socket_collection.add_connections(vec![
        (
            terrain_sockets.water.material,
            vec![terrain_sockets.water.material],
        ),
        (
            terrain_sockets.water.water_and_void,
            vec![terrain_sockets.water.void_and_water],
        ),
    ]);

    // Connect water layer to yellow grass layer
    socket_collection.add_rotated_connection(
        terrain_sockets.yellow_grass.layer_up,
        vec![terrain_sockets.water.layer_down],
    );
}

Key Points About Water:

Low Weight Values - Notice WATER_WEIGHT: f32 = 0.02. This makes water appear less frequently than grass, creating occasional water bodies instead of covering everything.
Multiple z_pos Options - The void model has two options for z_pos: water.layer_up (another water layer could go here) and water.ground_up (props can sit here). This prepares us for the props layer we’ll add next.
Same Pattern as Grass - Water uses the same template and rotation approach as grass, demonstrating how the WFC pattern scales to different terrain types.

Step 4: Calling the Water Layer Function

Update build_world in rules.rs to call build_water_layer:

// src/map/rules.rs - Update build_world function
pub fn build_world() -> (
    Vec<Vec<SpawnableAsset>>,
    ModelCollection<Cartesian3D>,
    SocketCollection,
) {
    let mut socket_collection = SocketCollection::new();
    let terrain_sockets = create_sockets(&mut socket_collection);

    let mut terrain_model_builder = TerrainModelBuilder::new();

    // Build dirt layer
    build_dirt_layer(
        &mut terrain_model_builder,
        &terrain_sockets,
        &mut socket_collection,
    );

    // Build grass layer
    build_grass_layer(
        &mut terrain_model_builder,
        &terrain_sockets,
        &mut socket_collection,
    );

    // Build yellow grass layer
    build_yellow_grass_layer(
        &mut terrain_model_builder,
        &terrain_sockets,
        &mut socket_collection,
    );

    // Line update alert
    // Build water layer
    build_water_layer(
        &mut terrain_model_builder,
        &terrain_sockets,
        &mut socket_collection,
    );

    let (assets, models) = terrain_model_builder.into_parts();

    (assets, models, socket_collection)
}

Step 5: Updating Grid Layers

We need one more layer for water. Update the constant in generate.rs:

// src/map/generate.rs - Update GRID_Z
const GRID_Z: u32 = 4; // Changed from 3 to 4

Now run your game:

cargo run

You should see water bodies forming on your terrain, creating lakes and ponds alongside the grass patches!

Adding the Props Layer

Props are the final layer that brings our world to life! Trees, rocks, plants, and stumps should appear on land but not in water.

This layer sits at the top of our Z-stack and uses special connection rules to ensure props only spawn on solid ground.

Step 1: Add Props Sprites to Tilemap

First, let’s add all the props sprites to our tilemap definition. Open src/map/tilemap.rs and add these entries to the sprites array:

// src/map/tilemap.rs - Add these after the water sprites
TilemapSprite {
    name: "big_tree_1_tl",
    pixel_x: 0,
    pixel_y: 0,
},
TilemapSprite {
    name: "big_tree_1_tr",
    pixel_x: 32,
    pixel_y: 0,
},
TilemapSprite {
    name: "big_tree_1_bl",
    pixel_x: 0,
    pixel_y: 32,
},
TilemapSprite {
    name: "big_tree_1_br",
    pixel_x: 32,
    pixel_y: 32,
},
TilemapSprite {
    name: "big_tree_2_tl",
    pixel_x: 64,
    pixel_y: 0,
},
TilemapSprite {
    name: "big_tree_2_tr",
    pixel_x: 96,
    pixel_y: 0,
},
TilemapSprite {
    name: "big_tree_2_bl",
    pixel_x: 64,
    pixel_y: 32,
},
TilemapSprite {
    name: "big_tree_2_br",
    pixel_x: 96,
    pixel_y: 32,
},
TilemapSprite {
    name: "plant_1",
    pixel_x: 128,
    pixel_y: 64,
},
TilemapSprite {
    name: "plant_2",
    pixel_x: 160,
    pixel_y: 64,
},
TilemapSprite {
    name: "plant_3",
    pixel_x: 192,
    pixel_y: 64,
},
TilemapSprite {
    name: "plant_4",
    pixel_x: 224,
    pixel_y: 64,
},
TilemapSprite {
    name: "rock_1",
    pixel_x: 0,
    pixel_y: 128,
},
TilemapSprite {
    name: "rock_2",
    pixel_x: 32,
    pixel_y: 128,
},
TilemapSprite {
    name: "rock_3",
    pixel_x: 64,
    pixel_y: 128,
},
TilemapSprite {
    name: "rock_4",
    pixel_x: 96,
    pixel_y: 128,
},
TilemapSprite {
    name: "small_tree_top",
    pixel_x: 128,
    pixel_y: 128,
},
TilemapSprite {
    name: "small_tree_bottom",
    pixel_x: 128,
    pixel_y: 160,
},
TilemapSprite {
    name: "tree_stump_1",
    pixel_x: 192,
    pixel_y: 128,
},
TilemapSprite {
    name: "tree_stump_2",
    pixel_x: 224,
    pixel_y: 128,
},
TilemapSprite {
    name: "tree_stump_3",
    pixel_x: 0,
    pixel_y: 192,
},

Step 2: Define Props Sockets

Props need special socket handling because they must only appear on land, never in water. They also include multi-tile objects like big trees that span multiple grid positions.

Add the socket structure to src/map/sockets.rs:

// src/map/sockets.rs - Add after WaterLayerSockets
pub struct PropsLayerSockets {
    pub layer_up: Socket,
    pub layer_down: Socket,
    pub props_down: Socket,
    pub big_tree_1_base: Socket,
    pub big_tree_2_base: Socket,
}

Then update TerrainSockets to include props:

// src/map/sockets.rs - Update TerrainSockets
pub struct TerrainSockets {
    pub dirt: DirtLayerSockets,
    pub void: Socket,
    pub grass: GrassLayerSockets,
    pub yellow_grass: YellowGrassLayerSockets,
    pub water: WaterLayerSockets,
    pub props: PropsLayerSockets, // Add this line
}

Finally, initialize the props sockets in create_sockets:

// src/map/sockets.rs - Update create_sockets function
pub fn create_sockets(socket_collection: &mut SocketCollection) -> TerrainSockets {
    let mut new_socket = || -> Socket { socket_collection.create() };
    
    let sockets = TerrainSockets {
        dirt: DirtLayerSockets {
            layer_up: new_socket(),
            material: new_socket(),
            layer_down: new_socket(),
        },
        void: new_socket(),
        grass: GrassLayerSockets {
            layer_up: new_socket(),
            material: new_socket(),
            layer_down: new_socket(),
            void_and_grass: new_socket(),
            grass_and_void: new_socket(),
            grass_fill_up: new_socket(),
        },
        yellow_grass: YellowGrassLayerSockets {
            layer_up: new_socket(),
            layer_down: new_socket(),
            yellow_grass_fill_down: new_socket(),
        },
        water: WaterLayerSockets {
            layer_up: new_socket(),
            layer_down: new_socket(),
            material: new_socket(),
            void_and_water: new_socket(),
            water_and_void: new_socket(),
            ground_up: new_socket(),
        },
        // Line update alert
        props: PropsLayerSockets {
            layer_up: new_socket(),
            layer_down: new_socket(),
            props_down: new_socket(),
            big_tree_1_base: new_socket(),
            big_tree_2_base: new_socket(),
        },
    };
    sockets
}

Understanding Props Sockets:

Props have 5 sockets with special purposes:

layer_up and layer_down - Standard vertical connections
props_down - Connects to water’s ground_up socket (ensures props only on land)
big_tree_1_base and big_tree_2_base - Special sockets for multi-tile trees that need to connect their base parts

Step 3: Building the Props Layer Rules

Now let’s create the function that builds the props layer. Add this function to rules.rs:

// src/map/rules.rs - Add this function after build_water_layer
pub fn build_props_layer(
    terrain_model_builder: &mut TerrainModelBuilder,
    terrain_sockets: &TerrainSockets,
    socket_collection: &mut SocketCollection,
) {
    // Void model - represents areas where no props exist
    terrain_model_builder.create_model(
        SocketsCartesian3D::Multiple {
            x_pos: vec![terrain_sockets.void],
            x_neg: vec![terrain_sockets.void],
            z_pos: vec![terrain_sockets.props.layer_up],
            z_neg: vec![terrain_sockets.props.layer_down],
            y_pos: vec![terrain_sockets.void],
            y_neg: vec![terrain_sockets.void],
        },
        Vec::new(),
    );

    // Weight constants for different prop types
    const PROPS_WEIGHT: f32 = 0.025;
    const ROCKS_WEIGHT: f32 = 0.008;
    const PLANTS_WEIGHT: f32 = 0.025;
    const STUMPS_WEIGHT: f32 = 0.012;

    // Base prop template - single tile props
    let prop = SocketsCartesian3D::Simple {
        x_pos: terrain_sockets.void,
        x_neg: terrain_sockets.void,
        z_pos: terrain_sockets.props.layer_up,
        z_neg: terrain_sockets.props.props_down,
        y_pos: terrain_sockets.void,
        y_neg: terrain_sockets.void,
    }
    .to_template()
    .with_weight(PROPS_WEIGHT);

    // Create different prop types with different weights
    let plant_prop = prop.clone().with_weight(PLANTS_WEIGHT);
    let stump_prop = prop.clone().with_weight(STUMPS_WEIGHT);
    let rock_prop = prop.clone().with_weight(ROCKS_WEIGHT);

    // Small tree (2 tiles high)
    terrain_model_builder.create_model(
        plant_prop.clone(),
        vec![
            SpawnableAsset::new("small_tree_bottom"),
            SpawnableAsset::new("small_tree_top").with_grid_offset(GridDelta::new(0, 1, 0)),
        ],
    );

    // Big tree 1 (2x2 tiles)
    terrain_model_builder
        .create_model(
            SocketsCartesian3D::Simple {
                x_pos: terrain_sockets.props.big_tree_1_base,
                x_neg: terrain_sockets.void,
                z_pos: terrain_sockets.props.layer_up,
                z_neg: terrain_sockets.props.props_down,
                y_pos: terrain_sockets.void,
                y_neg: terrain_sockets.void,
            },
            vec![
                SpawnableAsset::new("big_tree_1_bl"),
                SpawnableAsset::new("big_tree_1_tl").with_grid_offset(GridDelta::new(0, 1, 0)),
            ],
        )
        .with_weight(PROPS_WEIGHT);

    terrain_model_builder
        .create_model(
            SocketsCartesian3D::Simple {
                x_pos: terrain_sockets.void,
                x_neg: terrain_sockets.props.big_tree_1_base,
                z_pos: terrain_sockets.props.layer_up,
                z_neg: terrain_sockets.props.props_down,
                y_pos: terrain_sockets.void,
                y_neg: terrain_sockets.void,
            },
            vec![
                SpawnableAsset::new("big_tree_1_br"),
                SpawnableAsset::new("big_tree_1_tr").with_grid_offset(GridDelta::new(0, 1, 0)),
            ],
        )
        .with_weight(PROPS_WEIGHT);

    // Big tree 2 (2x2 tiles)
    terrain_model_builder
        .create_model(
            SocketsCartesian3D::Simple {
                x_pos: terrain_sockets.props.big_tree_2_base,
                x_neg: terrain_sockets.void,
                z_pos: terrain_sockets.props.layer_up,
                z_neg: terrain_sockets.props.props_down,
                y_pos: terrain_sockets.void,
                y_neg: terrain_sockets.void,
            },
            vec![
                SpawnableAsset::new("big_tree_2_bl"),
                SpawnableAsset::new("big_tree_2_tl").with_grid_offset(GridDelta::new(0, 1, 0)),
            ],
        )
        .with_weight(PROPS_WEIGHT);

    terrain_model_builder
        .create_model(
            SocketsCartesian3D::Simple {
                x_pos: terrain_sockets.void,
                x_neg: terrain_sockets.props.big_tree_2_base,
                z_pos: terrain_sockets.props.layer_up,
                z_neg: terrain_sockets.props.props_down,
                y_pos: terrain_sockets.void,
                y_neg: terrain_sockets.void,
            },
            vec![
                SpawnableAsset::new("big_tree_2_br"),
                SpawnableAsset::new("big_tree_2_tr").with_grid_offset(GridDelta::new(0, 1, 0)),
            ],
        )
        .with_weight(PROPS_WEIGHT);

    // Tree stumps
    terrain_model_builder.create_model(
        stump_prop.clone(),
        vec![SpawnableAsset::new("tree_stump_1")],
    );
    terrain_model_builder.create_model(
        stump_prop.clone(),
        vec![SpawnableAsset::new("tree_stump_2")],
    );
    terrain_model_builder.create_model(
        stump_prop.clone(),
        vec![SpawnableAsset::new("tree_stump_3")],
    );

    // Rocks
    terrain_model_builder.create_model(rock_prop.clone(), vec![SpawnableAsset::new("rock_1")]);
    terrain_model_builder.create_model(rock_prop.clone(), vec![SpawnableAsset::new("rock_2")]);
    terrain_model_builder.create_model(rock_prop.clone(), vec![SpawnableAsset::new("rock_3")]);
    terrain_model_builder.create_model(rock_prop.clone(), vec![SpawnableAsset::new("rock_4")]);

    // Plants
    terrain_model_builder.create_model(plant_prop.clone(), vec![SpawnableAsset::new("plant_1")]);
    terrain_model_builder.create_model(plant_prop.clone(), vec![SpawnableAsset::new("plant_2")]);
    terrain_model_builder.create_model(plant_prop.clone(), vec![SpawnableAsset::new("plant_3")]);
    terrain_model_builder.create_model(plant_prop.clone(), vec![SpawnableAsset::new("plant_4")]);

    // Add connection rules
    socket_collection.add_connections(vec![
        (
            terrain_sockets.props.big_tree_1_base,
            vec![terrain_sockets.props.big_tree_1_base],
        ),
        (
            terrain_sockets.props.big_tree_2_base,
            vec![terrain_sockets.props.big_tree_2_base],
        ),
    ]);

    // Connect props to water layer
    socket_collection
        .add_rotated_connection(
            terrain_sockets.water.layer_up,
            vec![terrain_sockets.props.layer_down],
        )
        .add_rotated_connection(
            terrain_sockets.props.props_down,
            vec![terrain_sockets.water.ground_up],
        );
}

Key Points About Props:

Multi-tile Objects - Big trees use GridDelta::new(0, 1, 0) to place the top half one tile up
Weight System - Different prop types have different spawn probabilities (rocks are rarer than plants)
Land-only Rule - props_down connects to water.ground_up, ensuring props never spawn in water
Base Sockets - Big trees use special base sockets to connect their left and right halves

Step 4: Calling the Props Layer Function

Update build_world in rules.rs to call build_props_layer:

// src/map/rules.rs - Update build_world function
pub fn build_world() -> (
    Vec<Vec<SpawnableAsset>>,
    ModelCollection<Cartesian3D>,
    SocketCollection,
) {
    let mut socket_collection = SocketCollection::new();
    let terrain_sockets = create_sockets(&mut socket_collection);

    let mut terrain_model_builder = TerrainModelBuilder::new();

    // Build dirt layer
    build_dirt_layer(
        &mut terrain_model_builder,
        &terrain_sockets,
        &mut socket_collection,
    );

    // Build grass layer
    build_grass_layer(
        &mut terrain_model_builder,
        &terrain_sockets,
        &mut socket_collection,
    );

    // Build yellow grass layer
    build_yellow_grass_layer(
        &mut terrain_model_builder,
        &terrain_sockets,
        &mut socket_collection,
    );

    // Build water layer
    build_water_layer(
        &mut terrain_model_builder,
        &terrain_sockets,
        &mut socket_collection,
    );

    // Line update alert
    // Build props layer
    build_props_layer(
        &mut terrain_model_builder,
        &terrain_sockets,
        &mut socket_collection,
    );

    let (assets, models) = terrain_model_builder.into_parts();

    (assets, models, socket_collection)
}

Step 5: Updating Grid Layers

We need one final layer for props. Update the constant in generate.rs:

// src/map/generate.rs - Update GRID_Z
const GRID_Z: u32 = 5; // Changed from 4 to 5

Now run your game:

cargo run

You should see a complete procedural world with dirt, grass, water, and props! Trees and rocks will only appear on land, never in water, creating a realistic and varied landscape.

Congratulations!

You’ve successfully built a complete procedural terrain generation system using Wave Function Collapse! Your world now has:

Dirt base layer - The foundation
Green grass patches - With smooth edges and corners
Yellow grass variety - Stacking on green grass
Water bodies - Creating lakes and ponds
Props - Trees, rocks, and plants that only appear on land

This demonstrates the power of WFC for creating coherent, natural-looking game worlds with just a few simple rules!

Wait, Just one more thing!

Go to rules.rs and change the water weight.

const WATER_WEIGHT: f32 = 0.07;

Now run your game:

cargo run

Woah, with a simple modification you are able to change the world to have more water! This demonstrates the power of procedural generation—by tweaking just a few numbers, you can create completely different landscapes.

Try experimenting with the weight values for different layers to see how dramatically you can transform your world.

Also notice our player can walk on water. We will work on collision detection and also on approaches to build larger maps in our upcoming chapters.

The Impatient Programmer’s Guide to Bevy and Rust: Chapter 1 - Let There Be a Player

2025-09-16T10:00:00+00:00

This is chapter 1 of my rust-bevy tutorial series “The Impatient Programmer’s Guide to Bevy and Rust: Build a 2D Game from Scratch”. I will be going in-depth into bevy and game development in this series, also cover NPCs powered by AI Agents. Join our community to be updated on new releases on this series. Source code for this chapter is available here.

Here’s what you will be able to achieve by the end of this tutorial.

Setup Instructions

If you haven’t setup rust yet, please follow the official guide to set it up.

Create a fresh project:
```
cargo new bevy_game
cd bevy_game
```
Open Cargo.toml and add Bevy:
```
[dependencies]
bevy = "0.18"
```

I am going to assume you have programming experience in any one language like javascript or python.

Thinking in Systems

What do we need to build a simple game that allows player to move from keyboard input?

World System: Create a game world where the player can move.
Input System: Monitor keyboard input and translate it into player movement.

We see the above pattern very common in building games, the pattern of create/setup and the pattern of monitoring game state changes and updating the game world entities.

Setup: Spawn enemy with different behaviors, load enemy sprites and animations, configure enemy health and damage values.
Update: Move enemies toward the player, check if enemies are hit by bullets, remove dead enemies and spawn new enemies at intervals.

At the core of Bevy, we have this simple setup and update system. This foundational pattern is what makes Bevy both powerful and easy to understand - once you grasp this concept, building with bevy becomes easier.

Setup System

Imagine a function called setup, that gives you “commands” as an argument, and it give you spawn ability to create or spawn anything you want. Well, bevy gives you exactly that.

// Pseudo code, doesn't compile
fn setup(mut commands: Commands) {
	// Create anything you want
	commands.spawn()
}

What’s mut?

mut is short for mutate. In Rust we need to explicitly mention that we are planning to change this value. By default, Rust treats declared values as read only. mut tells Rust we plan to change the value. Rust uses this knowledge to prevent a whole class of bugs.

And what’s this mut commands: Commands?

It’s from bevy library, that allows you to add things to your game world. Rust likes explicit types, so :Commands lets the compiler know this parameter is Bevy’s command interface. Skip the hint and Rust can’t be sure what shows up, so it blocks the build.

What’s a type?

A type tells Rust what kind of value you are handling—numbers, text, timers, Bevy commands, and so on. Once the compiler knows the type, it can check that every operation you perform on it actually makes sense.

Isn’t this too much work?

It prevents mistakes and helps you with performance, ex: If you try to add a string to a number, the compiler stops you before the game runs. On top of that, knowing the exact type lets Rust pack data tightly.

A Vec2 is just two numbers, so Rust stores exactly two numbers, no surprise extra space, which keeps things fast when you have thousands of game entities. These helps your game to be memory efficient.

When you create a Vec2 object in JavaScript or Python, you’re not just storing two numbers. The runtime adds type metadata, property information, and prototype references - turning your simple 8-byte data structure into ~48 bytes of memory.

Rust’s type system works at compile time. When you declare a Vec2 struct with two f32 fields, that’s exactly what gets stored - just 8 bytes, no extra metadata. The compiler already knows the types, so no runtime type information is needed.

With 1000 game entities, this difference becomes dramatic:

Language	Memory Usage	Overhead
Rust	8KB	None
Dynamic language	~48KB+	6x overhead

This isn’t just about memory usage - it’s about performance. Smaller, predictable memory layouts mean better CPU cache utilization, which directly translates to faster frame rates in games where you’re processing thousands of entities every frame. The compiler catches type errors before your game runs, and the tight memory packing keeps it running fast.

Setting up a Camera

What should we setup first?

We need a camera because nothing shows on screen without one. The world can exist in data, but the camera decides what actually gets drawn.

//Pseudo code, don't use this yet
fn setup(mut commands: Commands) {
	commands.spawn(Camera2d)
}

What’s Camera2d?

Camera2d is Bevy’s built-in 2D camera bundle. Spawn it and you get a ready-to-go view of your 2D scene.

What’s a bundle?

A bundle is just a group of components you often spawn together. For example, Bevy ships a SpriteBundle that packs position, texture, color tint, and visibility; spawning that bundle gives a sprite entity in one call.

Registering our setup function

We need to register our setup function with bevy to be triggered on Startup.

Update your src/main.rs with the following code.

// Replace your main.rs with the following code.
use bevy::prelude::*;

fn main() {
	App::new()
	.add_plugins(DefaultPlugins)
	.add_systems(Startup, setup)
	.run();
}

fn setup(mut commands: Commands) {
	commands.spawn(Camera2d);
}

What’s bevy::prelude?

bevy::prelude is like a starter kit, things you reach for constantly when building a game—App, Commands, components, math helpers, etc.

What’s App::new()…?

App::new() creates the game application, add_plugins(DefaultPlugins) loads rendering, input, audio, and other systems, add_systems(Startup, setup) registers our startup function, and run() hands control to Bevy’s main loop.

Why register a startup function? What does it do?

Startup systems run once before the first frame. We use them to set up cameras, players, and other things that should exist as soon as the window opens.

What’s bevy main loop?

After startup, Bevy enters its main loop: it polls input, runs your systems, updates the world, and renders a frame. That loop repeats until you quit the game.

Let’s run it

cargo run

A blank screen? Yup, we have only setup the camera, now let’s add our player.

Setting up the Player

Now let’s create our player! Remember our Setup System and Update System from earlier? Well, in Bevy, everything is an Entity with Components that systems can work with.

Think of an entity as a unique ID (like a social security number) and components as the data attached to it. For our player, we need components like movement speed, health, or special abilities. In Rust, the perfect way to create these components is with a struct.

struct is one of the core building blocks of rust. It groups similar data together. Here we declare an empty Player struct so the type itself acts as a tag we can attach to the player entity. Later we can add things like player health.

// Place this before main function in main.rs
#[derive(Component)]
struct Player;

Why tag?

Tag marks an entity for later lookup. Because Player is attached to only our hero, systems can ask Bevy, “give me the entity with the Player tag” and work with just that one.

What’s this #[derive(component)]?

derive tells Rust to attach the component macro code to this struct. A macro is Rust’s way of generating pre-defined template code for you. #[derive(Component)] automatically injects the boilerplate Bevy needs, so it can store and find Player entities, saving us from copying the same glue code everywhere. We’ll take a closer look at macros later in the series. This is the moment our player type becomes a component.

What’s a component, and why should the player be a component?

A component is a piece of data attached to an entity. Position, velocity, health, and even the idea of “this is the player” all live in components. By making Player a component we can query for that entity later, add more components (like health or inventory), and let Bevy’s systems pick out exactly the entities they need to update.

For now we will represent our character on screen using the “@” symbol. Modify the setup function.

// Replace existing setup function in main.rs with the following code
fn setup(mut commands: Commands) {
    commands.spawn(Camera2d);	
    
    // Code Update Alert
    // Append the following lines to your setup function.
    commands.spawn((
        Text2d::new("@"),
        TextFont {
            font_size: 12.0,	
            font: default(),
            ..default()
        },
        TextColor(Color::WHITE),
        Transform::from_translation(Vec3::ZERO),
        Player,
    ));
}

commands.spawn(( ... )) takes that tuple and treats it as a bundle of components. This single call adds the text we want to show, its font settings, the color, the position, and the Player tag that identifies the entity.

What’s a tuple?

A tuple is an ordered list of values written in parentheses. Rust keeps track of each position, so (Text2d::new("@"), TextColor(Color::WHITE)) holds two values side by side without needing to create a struct.

Whats an entity?

An entity is the unique ID Bevy uses to tie components together. By itself it holds no data, but once you attach components to it, that ID represents something in your game world.

Each bundle produces a new entity with a unique ID and the listed components, which you can picture like this:

Entity	Components it carries
#42	`Camera2d`
#43	`Text2d("@")`, `TextFont`, `TextColor`, `Transform`, `Player`

Once the queue flushes, those entities live in the world, ready for systems to discover them by the tags (components) they carry. We will be using this later when we want to do things like moving or animating them, or making them attack enemies, etc.

Implementing Player Movement

Now let’s create our Update System for player movement! Think about what we need to move a player:

Keyboard input - to know which keys are pressed
Time - to make movement smooth regardless of frame rate
Player position - to actually move the player

In other game engines, you’d spend time manually connecting these systems together. But here’s the magic of Bevy - you just ask for what you need in your function parameters, and Bevy automatically provides it!

Let’s write our move player function.

// Append this code to main.rs
fn move_player(
    // "Bevy, give me keyboard input"
    input: Res<ButtonInput<KeyCode>>,           
    // "Bevy, give me the game timer"
    time: Res<Time>,                            
    // "Bevy, give me the player's position"
    mut player_transform: Single<&mut Transform, With<Player>>, 
) {
    let mut direction = Vec2::ZERO;
    if input.pressed(KeyCode::ArrowLeft) {
        direction.x -= 1.0;
    }
    if input.pressed(KeyCode::ArrowRight) {
        direction.x += 1.0;
    }
    if input.pressed(KeyCode::ArrowUp) {
        direction.y += 1.0;
    }
    if input.pressed(KeyCode::ArrowDown) {
        direction.y -= 1.0;
    }

    if direction != Vec2::ZERO {
        let speed = 300.0; // pixels per second
        let delta = direction.normalize() * speed * time.delta_secs();
        player_transform.translation.x += delta.x;
        player_transform.translation.y += delta.y;
    }
}

What’s Res?

Res or Resources are pieces of game-wide information that are not tied to any single entity. For example, Res gives you the game’s master clock, so every system reads the same “time since last frame” value.

Explain Single<&mut Transform, With>?

Single<&mut Transform, With> asks Bevy for exactly one entity that has a Transform component and also carries the Player tag. The &mut Transform part means we intend to modify that transform or player position (Remember, we added transform component in the setup function). If more than one player existed, this extractor would complain, which is perfect for a single-hero game.

What’s Vec2::ZERO?

Vec2::ZERO is a two-dimensional vector with both values set to zero: Vec2 { x: 0.0, y: 0.0 }. We use it as the starting direction before reading keyboard input.

What’s this KeyCode::… pattern?

KeyCode::ArrowLeft, KeyCode::ArrowRight … are enums (will cover enums later) that represent specific keys on the keyboard. Checking input.pressed(KeyCode::ArrowLeft) simply asks Bevy whether that key is held down during the current frame.

We ignore zero direction so the player stands still when no keys are pressed. Once we have input, normalize() converts the vector to length 1 so diagonal movement isn’t faster than straight movement. speed says how many pixels per second to move, and time.delta_secs() returns the frame time—the number of seconds since the previous frame—so multiplying them gives the distance we should travel this update. Finally we add that delta to the player’s transform translation to move the sprite on screen.

Registering the Movement System

// Update main function
fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, setup)
        .add_systems(Update, move_player) // Line update alert
        .run();
}

Why is move_player added as Update? What’s Update?

move_player runs every frame, so we plug it into the Update schedule. Update is Bevy’s built-in stage that fires once per game loop after startup is done.

So does systems mean functions we want bevy to execute at a particular time, like initial setup or on every game loop update?

Exactly. A system is just a Rust function you hand to Bevy with a sticky note that says “run me during Startup” or “execute me on every Update,” and the engine dutifully obeys.

Let’s run it.

Adding Sprite Graphics

We’ll use the Universal LPC SpriteSheet Generator to give our character some personality. You can remix body parts, clothes, and colors at this link and export a full spritesheet.

For this project the spritesheet is already included in the repo. Drop the provided image files into src/assets so Bevy can find them when the game runs. You will need to create the assets directory inside the src folder.

Refactoring Code

We need to add more code and adding to main.rs will make hard to read and understand.

Update your main.rs file to the following, also create another file player.rs

mod player; pulls in the player.rs module, keeping our main file slim. Splitting code like this makes it easier to grow the project without one big file doing everything.

//main.rs
use bevy::prelude::*;

mod player;

fn main() {
    App::new()
        .insert_resource(ClearColor(Color::WHITE)) // We have updated the bg color to white
        .add_plugins(
            DefaultPlugins.set(AssetPlugin {
                // Our assets live in `src/assets` for this project
                file_path: "src/assets".into(),
                ..default()
            }),
        )
        .add_systems(Startup, setup_camera)
        .run();
}

fn setup_camera(mut commands: Commands) {
    commands.spawn(Camera2d);
}

.insert_resource(ClearColor(Color::WHITE)) drops a global setting into the app so every frame starts with a white background.

AssetPlugin is Bevy’s loader for textures, audio, and other assets. We tweak its file_path so it looks inside src/assets, which is where our sprites live.

Building the Player Module

Now that we have our basic app structure in place, it’s time to bring our character to life! We’ll create a dedicated player.rs module to handle everything related to our little adventurer. This keeps our code organized and makes it easier to add more features later.

This module will hold all the constants, components, and systems that make our player move, animate, and interact with the world.

Add following code in player.rs

// player.rs
use bevy::prelude::*;

// Atlas constants
const TILE_SIZE: u32 = 64; // 64x64 tiles
const WALK_FRAMES: usize = 9; // 9 columns per walking row
const MOVE_SPEED: f32 = 140.0; // pixels per second
const ANIM_DT: f32 = 0.1; // seconds per frame (~10 FPS)


#[derive(Component)]
struct Player; // Moved from main.rs to here

These constants give names to the numbers we reuse for the spritesheet and movement math: tile size, frames per row, walk speed, and how fast the animation advances. Moving the Player marker here keeps all player-specific types in one module.

Defining Player Directions

// Append these lines of code to player.rs
#[derive(Component, Debug, Clone, Copy, PartialEq, Eq)]
enum Facing {
    Up,
    Left,
    Down,
    Right,
}

What’s an enum?

An enum lists a handful of allowed values. Our character only ever faces four directions, so the Facing enum captures those options in one place.

Why can’t I use a struct here?

A struct would need a bunch of booleans like facing_up:true, facing_left:false, and you’d have to keep them in sync. That makes it complicated. Enum guarantees you only pick one direction.

When to decide between using enum and struct?

Use a struct when you need several fields, like a position with x and y, or player stats with health and stamina. Use an enum when you choose one option from a list, like which tool the player wields (sword, bow, wand) or which menu screen is active.

Why the purpose of adding Debug, Clone, Copy, PartialEq, Eq macros?

Debug lets us print the facing for logs, Clone and Copy make it trivial to duplicate the value, and PartialEq/Eq allow equality checks when we compare directions.

Why can’t I copy through simple assignment, why should I add these macros?

By default Rust moves values instead of copying them, so the compiler makes you opt in. Deriving Copy (and Clone as a helper) says “it’s cheap, go ahead and duplicate it.” PartialEq and Eq let us compare two facings directly, which is how we detect when the player changes direction.

What do you mean by rust moves values, instead of copying?

When you assign most values in Rust, the old variable stops owning it or in other words dies. Adding Copy keeps both variables valid.

Why does the old variable stop owning or die when assigned?

Rust enforces that each value has a single owner so memory can be freed safely. We’ll unpack the ownership rules and borrowing in later chapters.

This is a bit going over my head!

Yea, don’t worry, we have many more chapters to go and as you move through them, we will tackle this. It’s alright to not understand these concepts now.

Animation System Components

When we have a spritesheet with multiple frames (like our 9-frame walking animation), we need a way to control how fast those frames play. Without timing control, our character would either be frozen on one frame or cycling through frames so fast it looks like a blur!

Think of it like a flipbook - if you flip the pages too slowly, the animation looks choppy. If you flip too fast, you can’t see what’s happening. The AnimationTimer gives us precise control over this timing, ensuring our character’s walking animation looks smooth and natural at just the right speed.

AnimationTimer wraps a Bevy Timer so each player entity knows when to advance to the next animation frame. Each tick represents one slice of time; once the timer hits its interval we move to the next sprite in the sheet.

// Append these lines of code to player.rs
#[derive(Component, Deref, DerefMut)]
struct AnimationTimer(Timer);

#[derive(Component)]
struct AnimationState {
    facing: Facing,
    moving: bool,
    was_moving: bool,
}

What’s Deref, DerefMut macros doing?

Deref lets our wrapper pretend to be the inner Timer when we read from it, and DerefMut does the same for writes. That means we can just call timer.tick(time.delta()) on AnimationTimer without manually pulling out the inner value first.

So we are renaming the Timer to AnimationTimer?

We’re wrapping the timer, not renaming it. Think of AnimationTimer as a little box that holds a Timer, plus a label that says “this one belongs to the player animation.” When we spawn a player we create a fresh Timer and tuck it into that box, so each player could have its own timer if we needed multiple heroes.

So it’s an instance of AnimationTime?

Yes, AnimationTimer is a tuple struct that contains a Timer. We build one when we spawn the player so each entity can carry its own timer data. This pattern shows up whenever you want to attach extra meaning to an existing type without writing a brand-new API.

AnimationState remembers which way the player points, whether they are moving, and whether they just started or stopped. Systems read this to choose animation rows and reset frames when movement changes.

Spawning the Player

We load the spritesheet through the AssetServer, create a texture atlas layout so Bevy knows the grid, and pick the starting frame for a hero facing down. Then we spawn an entity with the sprite, transform at the origin, our marker components, and the timer that will drive animation.

// Append these lines of code to player.rs
fn spawn_player(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
    mut atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
) {
    // Load the spritesheet and build a grid layout: 64x64 tiles, 9 columns, 12 rows
    let texture = asset_server.load("male_spritesheet.png");
    let layout = atlas_layouts.add(TextureAtlasLayout::from_grid(
        UVec2::splat(TILE_SIZE),
        WALK_FRAMES as u32, // columns used for walking frames
        12,                  // at least 12 rows available
        None,
        None,
    ));

    // Start facing down (towards user), idle on first frame of that row
    let facing = Facing::Down;
    let start_index = atlas_index_for(facing, 0);

    commands.spawn((
        Sprite::from_atlas_image(
            texture,
            TextureAtlas {
                layout,
                index: start_index,
            },
        ),
        Transform::from_translation(Vec3::ZERO),
        Player,
        AnimationState { facing, moving: false, was_moving: false },
        AnimationTimer(Timer::from_seconds(ANIM_DT, TimerMode::Repeating)),
    ));
}

AnimationState { facing, moving: false, was_moving: false } sets the starting direction and flags that the character is idle right now and was idle last frame.

AnimationTimer(Timer::from_seconds(ANIM_DT, TimerMode::Repeating)) creates a repeating stopwatch that fires every ANIM_DT seconds to advance the spritesheet.

What’s an AssetServer?

The AssetServer is Bevy’s file loader and manager that handles loading and caching of game assets like images, sounds, and 3D models.

When you call asset_server.load("path/to/sprite.png"), it doesn’t immediately load the file into memory. Instead, it returns a handle that you can use later. This is called “lazy loading” - the actual file loading happens in the background, and Bevy will notify you when it’s ready.

This approach is efficient because:

Multiple entities can share the same sprite without loading it multiple times
Assets are only loaded when actually needed
Bevy can optimize and batch-load assets for better performance
If an asset fails to load, it won’t crash your entire game

In our case, asset_server.load("sprites/player.png") requests the spritesheet and returns a handle to track its loading status.

Movement System

Now that we have our player spawned with all the necessary components, we need to update our existing movement system to track which direction the player is facing. This is crucial for the animation system to know which row of the spritesheet to use - each direction (up, down, left, right) corresponds to a different row in our sprite atlas.

This updated system will detect the movement direction and update the AnimationState accordingly, so our animation system can pick the correct sprite row for walking animations in each direction.

// Append these lines of code to player.rs
fn move_player(
    input: Res<ButtonInput<KeyCode>>,
    time: Res<Time>,
    mut player: Query<(&mut Transform, &mut AnimationState), With<Player>>,
) {
    let Ok((mut transform, mut anim)) = player.single_mut() else {
        return;
    };

    let mut direction = Vec2::ZERO;
    if input.pressed(KeyCode::ArrowLeft) {
        direction.x -= 1.0;
    }
    if input.pressed(KeyCode::ArrowRight) {
        direction.x += 1.0;
    }
    if input.pressed(KeyCode::ArrowUp) {
        direction.y += 1.0;
    }
    if input.pressed(KeyCode::ArrowDown) {
        direction.y -= 1.0;
    }

    if direction != Vec2::ZERO {
        let delta = direction.normalize() * MOVE_SPEED * time.delta_secs();
        transform.translation.x += delta.x;
        transform.translation.y += delta.y;
        anim.moving = true;

        // Update facing based on dominant direction
        if direction.x.abs() > direction.y.abs() {
            anim.facing = if direction.x > 0.0 { Facing::Right } else { Facing::Left };
        } else {
            anim.facing = if direction.y > 0.0 { Facing::Up } else { Facing::Down };
        }
    } else {
        anim.moving = false;
    }
}

The query asks Bevy for the single entity tagged Player, giving us mutable access to its Transform and AnimationState. We build a direction vector from the pressed keys, normalize it so diagonal input isn’t faster, and move the player by speed × frame time. The facing logic compares horizontal vs vertical strength to decide which way the sprite should look. We record whether the player is moving now so later systems can detect when motion starts or stops.

Animation Implementation

Now we have all the pieces in place - our player can move in different directions, and we’re tracking which way they’re facing. The final piece is the animation system that actually updates the sprite frames to create the walking animation.

This system takes the direction information from our movement system and uses the animation timer to cycle through the sprite frames at the right speed. It handles the complex logic of switching between different animation rows when the player changes direction, and ensures smooth transitions between walking and idle states.

// Append these lines of code to player.rs
fn animate_player(
    time: Res<Time>,
    mut query: Query<(&mut AnimationState, &mut AnimationTimer, &mut Sprite), With<Player>>,
) {
    let Ok((mut anim, mut timer, mut sprite)) = query.single_mut() else {
        return;
    };

    let atlas = match sprite.texture_atlas.as_mut() {
        Some(a) => a,
        None => return,
    };

    // Compute the target row and current position in the atlas (column/row within the 9-column row)
    let target_row = row_zero_based(anim.facing);
    let mut current_col = atlas.index % WALK_FRAMES;
    let mut current_row = atlas.index / WALK_FRAMES;

    // If the facing changed (or we weren't on a walking row), snap to the first frame of the target row
    if current_row != target_row {
        atlas.index = row_start_index(anim.facing);
        current_col = 0;
        current_row = target_row;
        timer.reset();
    }

    let just_started = anim.moving && !anim.was_moving;
    let just_stopped = !anim.moving && anim.was_moving;

    if anim.moving {
        if just_started {
            // On tap or movement start, immediately advance one frame for visible feedback
            let row_start = row_start_index(anim.facing);
            let next_col = (current_col + 1) % WALK_FRAMES;
            atlas.index = row_start + next_col;
            // Restart the timer so the next advance uses a full interval
            timer.reset();
        } else {
            // Continuous movement: advance based on timer cadence
            timer.tick(time.delta());
            if timer.just_finished() {
                let row_start = row_start_index(anim.facing);
                let next_col = (current_col + 1) % WALK_FRAMES;
                atlas.index = row_start + next_col;
            }
        }
    } else if just_stopped {
        // Not moving: keep current frame to avoid snap. Reset timer on transition to idle.
        timer.reset();
    }

    // Update previous movement state
    anim.was_moving = anim.moving;
}


// Returns the starting atlas index for the given facing row
fn row_start_index(facing: Facing) -> usize {
    row_zero_based(facing) * WALK_FRAMES
}

fn atlas_index_for(facing: Facing, frame_in_row: usize) -> usize {
    row_start_index(facing) + frame_in_row.min(WALK_FRAMES - 1)
}

fn row_zero_based(facing: Facing) -> usize {
    match facing {
        Facing::Up => 8,
        Facing::Left => 9,
        Facing::Down => 10,
        Facing::Right => 11,
    }
}

let Ok((mut anim, mut timer, mut sprite)) = query.single_mut() else { return; }; both checks the result and names the pieces we need. If the query succeeds, the code binds anim, timer, and sprite so we can use them later. If it fails (no player, or more than one), we hit the else branch and exit immediately. Rust uses the Result type for this: Ok means “query returned exactly one result,” Err means “something about that query didn’t match.”

After that we match on an Option, which is Rust’s “maybe there is a value” type. Some(atlas) means the texture atlas exists and we can tweak it; None means it hasn’t loaded yet, so we skip and let the next frame try again. It’s the same pattern you’d use when checking a map or cache: only use the value when the lookup returns something.

animate_player pulls the animation state, timer, and sprite handle for the player. It figures out which row of the atlas matches the current facing, snaps to that row when direction changes, and uses the timer to step through columns at a steady pace. When movement stops we reset the timer so the animation rests on the last frame shown. The helper functions map a facing to the correct row and frame index so the math stays readable.

Creating the Player Plugin

// Append these lines of code to player.rs
pub struct PlayerPlugin;

impl Plugin for PlayerPlugin {
    fn build(&self, app: &mut App) {
        app.add_systems(Startup, spawn_player)
            .add_systems(Update, (move_player, animate_player));
    }
}

PlayerPlugin is our “player module” in plug form. In Bevy, a plugin is just a struct that knows how to register systems, resources, and assets. By implementing Plugin for PlayerPlugin, we give Bevy a checklist: whenever this plugin is added to the app, run the code inside to set up everything the player feature needs. This keeps main.rs from becoming a tangle of player-specific calls.

The build method is the checklist. Bevy passes us a mutable App, and we bolt on the systems we care about. spawn_player is scheduled in Startup so the sprite appears as soon as the game launches. move_player and animate_player go into the Update schedule so they execute every frame—handling input and animation in lockstep. With everything declared here, dropping PlayerPlugin into App::new() automatically wires up the entire player flow.

So this build function is an in-built structure, which I have to write?

Yes. The Plugin trait says “any plugin must provide a build(&self, app: &mut App) function.” We implement that trait, so Rust expects us to supply the body. Bevy calls this method when it loads the plugin, which is why we add all our systems inside it.

What’s a trait?

A trait is a contract describing what methods a type must provide. Bevy’s Plugin trait says “give me a build function so I can register your systems.” By implementing that trait for PlayerPlugin, we hook into Bevy’s startup process and inject our own setup code. Traits let different types share behavior, PlayerPlugin behaves like any other Bevy plugin, but it installs our player-specific systems.

Final Integration

// Update the main function in main.rs

use crate::player::PlayerPlugin;

fn main() {
    App::new()
        .insert_resource(ClearColor(Color::WHITE))
        .add_plugins(
            DefaultPlugins.set(AssetPlugin {
                file_path: "src/assets".into(),
                ..default()
            }),
        )
        .add_systems(Startup, setup_camera)
        .add_plugins(PlayerPlugin) // Update this line
        .run();
}

Let’s run it.

cargo run

AIBodh

The Impatient Programmer’s Guide to Bevy and Rust: Chapter 7 - Let There Be Enemies

What Makes an Enemy Different from a Player?

Thinking in Components

Creating the Enemy Module

Enemy Components

Making Enemies Follow You

Understanding A* Pathfinding

A* Pathfinding

Adding the Pathfinding Crate

How Waypoints Work

The EnemyPath Component

Extending CollisionMap for Pathfinding

Understanding the astar Function

The AI System with Pathfinding

Making Enemies Attack

Fixing Player Spawning

Updating the Plugin

Adding Enemy Configuration

Spawning Enemies

The Enemy Plugin

Fixing Enemy Depth Sorting

Preventing Entity Stacking

Integrating the Enemy Module

Optimizing Debug Builds

The Impatient Programmer’s Guide to Bevy and Rust: Chapter 6 - Let There Be Particles

Let’s Give Your Players Magic Powers

Understanding Particle Systems

Building the Particle System

Particle Components

Particle Emitter

Particle Configuration

Particle System Updates

The Shader

Custom Shader Material

Particles Module Plugin

Creating the Combat Module

Power Types

Player Combat Component

Combat Systems

Combat Module Plugin

Putting it all together

The Impatient Programmer’s Guide to Bevy and Rust: Chapter 5 - Let There Be Pickups

Building the Pickup System

The Pickup System

Configuring Pickup Radius

Building the Inventory System

Defining Item Types

Display Names

The Pickable Component

The Inventory Resource

Adding Items to Inventory

Pickup Detection System

Getting the Player Position

Collecting Items to Process

Processing Collected Items

Wiring It Together

Integrating the Plugin

Making Items Pickable

Updating the Asset Spawner

Making the Spawner Attach Components

Marking Props as Pickable

Zooming In and Following the Player

Updating the Config

Updating Map Generation

Building the Camera System

Camera Module

Integrating the Camera

The Impatient Programmer’s Guide to Bevy and Rust: Chapter 4 - Let There Be Collisions

Systems Running When They Shouldn’t

Systems That Run Only When Needed

State-Based Schedules

Implementing Game States

Defining Game States

Loading Screen

Pause Menu

State Plugin

Integrating StatePlugin

The State Pattern for Characters

Too Many Boolean Flags

Understanding the `astar` Function