bevy-procedural-generation

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.