Bevy Procedural Generation Agent Skill

Bevy procedural generation

When to use

Load this when a level, loot table, or map should be reproducible from a seed, and you need the ECS shape. Spawning the finished layout uses Commands on Startup or a later schedule you already use. Saving the seed belongs on bevy-save-load.

ECS shape

• Components: cell facts you define, spawned with Commands.
• Resources: one RunSeed for the whole run. The generator reads it; it does not invent a Bevy RNG type. rand 0.9 supplies StdRng.
• Systems: insert the seed on Startup, then spawn from that data. .chain() so the spawn system sees the seed.
• Schedule: Startup for a one-shot map. A streaming map is a later Update system that still reads the same seed.

[dependencies]
bevy = "0.20"
rand = "0.9"

The seed is a resource. The walk is plain data. Entities are spawned only after the seed exists.

use rand::rngs::StdRng;
use rand::{Rng, SeedableRng};

#[derive(Resource)]
struct RunSeed(u64);

#[derive(Component, Clone, Copy)]
struct FloorCell {
    x: i32,
    y: i32,
}

fn insert_seed(mut commands: Commands) {
    commands.insert_resource(RunSeed(42));
}

fn spawn_walk(mut commands: Commands, seed: Res<RunSeed>) {
    let mut rng = StdRng::seed_from_u64(seed.0);
    let mut x = 0;
    let mut y = 0;
    for _ in 0..24 {
        commands.spawn((
            FloorCell { x, y },
            Transform::from_xyz(x as f32, y as f32, 0.0),
        ));
        match rng.random_range(0..4) {
            0 => x += 1,
            1 => x -= 1,
            2 => y += 1,
            _ => y -= 1,
        }
    }
}

pub struct DungeonPlugin;

impl Plugin for DungeonPlugin {
    fn build(&self, app: &mut App) {
        app.add_systems(Startup, (insert_seed, spawn_walk).chain());
    }
}

Height samples stay in a resource. The same seed always rebuilds the same grid. Sampling happens once, not every frame.

#[derive(Resource)]
struct HeightGrid {
    width: i32,
    samples: Vec<f32>,
}

#[derive(Resource)]
struct RunSeed(u64);

fn hash_unit(x: i32, y: i32, seed: u64) -> f32 {
    let mut n = seed
        .wrapping_mul(0x9E37_79B9_7F4A_7C15)
        ^ (x as u64).wrapping_mul(0xBF58_476D_1CE4_E5B9)
        ^ (y as u64).wrapping_mul(0x94D0_49BB_1331_11EB);
    n = (n ^ (n >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
    n = (n ^ (n >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
    n ^= n >> 31;
    (n >> 40) as f32 / (1u32 << 24) as f32
}

fn build_heights(mut commands: Commands, seed: Res<RunSeed>) {
    let width = 16;
    let mut samples = Vec::with_capacity((width * width) as usize);
    for y in 0..width {
        for x in 0..width {
            samples.push(hash_unit(x, y, seed.0));
        }
    }
    commands.insert_resource(HeightGrid { width, samples });
}

Rooms are rectangles carved into a grid you own. Spawn markers only for floor cells.

struct Room {
    x: i32,
    y: i32,
    w: i32,
    h: i32,
}

fn carve(width: i32, rooms: &[Room]) -> Vec<bool> {
    let mut floor = vec![false; (width * width) as usize];
    for room in rooms {
        for y in room.y..room.y + room.h {
            for x in room.x..room.x + room.w {
                if (0..width).contains(&x) && (0..width).contains(&y) {
                    floor[(y * width + x) as usize] = true;
                }
            }
        }
    }
    floor
}

#[derive(Component, Clone, Copy)]
struct FloorCell {
    x: i32,
    y: i32,
}

fn spawn_rooms(mut commands: Commands) {
    let rooms = [
        Room { x: 1, y: 1, w: 4, h: 3 },
        Room { x: 8, y: 6, w: 5, h: 4 },
    ];
    let width = 16;
    for (i, open) in carve(width, &rooms).into_iter().enumerate() {
        if open {
            let x = (i as i32) % width;
            let y = (i as i32) / width;
            commands.spawn(FloorCell { x, y });
        }
    }
}

Choose the owner

| Need | Owner |

| --- | --- |

| Seeded run | A Resource holding a seed you define |

| Chunk or dungeon grid | Your components, spawned with Commands |

| Hash, rooms, or walk | Your functions over a RunSeed. rand::rngs::StdRng is the seeded generator. |

| Floor cells | Entities spawned from the grid. Tilemaps belong on the tile skill. |

| Nav bake after generation | Nav bake after generation belongs on bevy-navigation. |

Scope

• Seeded walks and room carves above use rand 0.9 and your own grid. Bevy does not ship a dungeon solver.
• Build the grid on the main schedule, then spawn. Commands stay on the system that runs there.
• Navigation rebake after a generated map belongs on bevy-navigation.

Expert Knowledge Delta

Target: Bevy 0.20+.

Core ECS types: Component, Resource, Query, Commands, Startup, Update, Fixed / FixedMain (bevy::time), .chain(), Plugin, DefaultPlugins, MinimalPlugins. Messages and observers are an ownership slot. See bevy-events-messaging for their APIs. Systems run in parallel unless .chain() orders the ones that conflict.

Who owns state

| Piece | Owner | Who may mutate | Schedule |

| --- | --- | --- | --- |

| Data on one entity | Component | One system via Query | Update or FixedMain |

| One value for the whole app | Resource | One system | Startup to insert, then the schedule that reads it |

| Spawn | Commands | The spawning system | Startup for the initial world; later schedules for runtime spawn |

| Order that must not race | .chain() | The chained systems only | Same schedule |

| Plugin boundary | Plugin | build registers systems and resources | Before the app runs |

Borrow rule: two systems that both mutably query the same component must be ordered (.chain()) or split so only one writes. Unrelated systems stay parallel. That is the ECS page rule, not a guess at a system-set API.

Decision

| If you need | Do this | Do not |

| --- | --- | --- |

| Per-entity data | Component + Query | A value that is not a component |

| App-wide config or clock | Resource | Copy the value onto every entity |

| Stable simulation step | FixedMain and the Fixed clock | Tie simulation to raw frame Update |

| Startup spawn | Commands in Startup | Spawn from a render system |

| Cross-system notice that is not shared state | Message or observer slot in bevy-events-messaging | A new event type invented in this file |

| An API outside the documented set | Check the official docs first | A made-up crate or API |

Load references/ecs-ownership.md for the ownership table.

NEVER

• Do not pin /0.20.0/ in docs URLs. WHY: links stay on latest; the 0.20 target is stated once in prose.
• Do not mutably query the same component from two unordered systems. WHY: the schedule runs systems in parallel unless .chain() orders them.
• Do not invent a physics, navigation, networking, or XR crate here. WHY: this skill only names documented Bevy crates and modules.

• No Godot noise, tile, or thread-pool types. WHY: Bevy code stays idiomatic ECS and uses only documented Bevy APIs.
• No invented noise, wave-function, or chunk APIs. WHY: Bevy code stays idiomatic ECS and uses only documented Bevy APIs.
• No named third-party generation crate as the chosen tool. WHY: Bevy code stays idiomatic ECS and uses only documented Bevy APIs.

Reference

The library pin on bevy-master stays 0.20.0.

Official Documentation

• Assets - Official asset catalog.
• Examples - Example tree on the latest branch.
• ECS - Component, Commands, Startup, and .chain().
• Resources - App-wide seed state. API limits are on bevy-data-resources.

Related Skills

Prerequisites

• bevy-master - ECS ownership.
• bevy-data-resources - Resource versus Component.
• bevy-ecs-composition - Spawn tuples and .chain().

Complements

• bevy-asset-scenes - Spawn a scene asset. Not a generator.
• bevy-save-load - Seed persistence.
• bevy-navigation - No bake after a generated map.
• godot-procedural-generation - Equivalent Godot skill.

Downstream / consumers

• None yet.

Master

• bevy-master - Bevy router.