Bevy Genre Metroidvania Agent Skill

Bevy Metroidvania

Genre router. Domain work lives in the Bevy skills below.

When to use

Load this for ability-gated exploration and a map of rooms.

ECS shape

• Components hold the genre's per-entity flags as plain data. This file does not name new engine types.
• Resources hold run-wide counters (score, wave index, seed) via bevy-data-resources.
• Systems read those components on Update or the fixed timestep from bevy-master. Order them with .chain() when a later system must see the result.
• Schedule: gameplay mode changes go through bevy-state-machines. Ability flags, visited cells, and the map fog below are components plus one resource.

Examples

[dependencies]
bevy = "0.20"

Traversal is a set of flags on the player. A gate stores the flag it needs. The map stores which cells are revealed. Input, gate checks, and fog share AbilitySet and MapFog, so those systems chain.

#[derive(Clone, Copy, PartialEq, Eq)]
enum Ability {
    Dash,
    WallClimb,
    DoubleJump,
}

#[derive(Component)]
struct AbilitySet {
    owned: [bool; 3],
}

impl AbilitySet {
    fn has(&self, ability: Ability) -> bool {
        self.owned[ability as usize]
    }

    fn grant(&mut self, ability: Ability) {
        self.owned[ability as usize] = true;
    }
}

#[derive(Component)]
struct Gate {
    requires: Ability,
    open: bool,
}

#[derive(Component)]
struct MapCell {
    x: i32,
    y: i32,
    visited: bool,
}

#[derive(Resource, Default)]
struct MapFog {
    revealed: u32,
}

fn boot(mut commands: Commands) {
    commands.insert_resource(MapFog { revealed: 0 });
    commands.spawn(AbilitySet {
        owned: [false, false, false],
    });
    commands.spawn(Gate {
        requires: Ability::Dash,
        open: false,
    });
    commands.spawn(MapCell {
        x: 0,
        y: 0,
        visited: false,
    });
}

fn grant_dash(keys: Res<ButtonInput<KeyCode>>, mut players: Query<&mut AbilitySet>) {
    if !keys.just_pressed(KeyCode::KeyE) {
        return;
    }
    for mut set in &mut players {
        set.grant(Ability::Dash);
    }
}

fn open_gates(players: Query<&AbilitySet>, mut gates: Query<&mut Gate>) {
    let Some(player) = players.iter().next() else {
        return;
    };
    for mut gate in &mut gates {
        gate.open = player.has(gate.requires);
    }
}

fn reveal_cell(mut cells: Query<&mut MapCell>, mut fog: ResMut<MapFog>) {
    for mut cell in &mut cells {
        if cell.x == 0 && cell.y == 0 && !cell.visited {
            cell.visited = true;
            fog.revealed = fog.revealed.saturating_add(1);
        }
    }
}

fn install(app: &mut App) {
    app.add_systems(Startup, boot).add_systems(
        Update,
        (grant_dash, open_gates, reveal_cell).chain(),
    );
}

A shortcut opens once the player holds both dash and wall climb.

#[derive(Clone, Copy)]
enum Ability {
    Dash,
    WallClimb,
    DoubleJump,
}

#[derive(Component)]
struct AbilitySet {
    owned: [bool; 3],
}

impl AbilitySet {
    fn has(&self, ability: Ability) -> bool {
        self.owned[ability as usize]
    }
}

fn shortcut_open(players: Query<&AbilitySet>) -> bool {
    players.iter().any(|set| set.has(Ability::Dash) && set.has(Ability::WallClimb))
}

Scene shape

| Piece | Bevy idiom |

| --- | --- |

| Genre content | Entities plus the domain skills linked below |

| Run-wide director | A Resource |

| Loop notices | bevy-events-messaging |

Routing

• bevy-ability-system - Traversal abilities.
• bevy-character-movement - Motion.
• bevy-save-load - Map flags.
• bevy-mechanic-secrets - Optional rooms.

Scope

• Ability flags live on AbilitySet. Gates and visited cells are components. MapFog counts revealed cells. Bevy has no map-graph type; the example above is the data.

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 | One script that owns the whole tree |

| 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 foreign-engine types in Bevy code. WHY: Bevy code stays idiomatic ECS and uses only documented Bevy APIs.
• No invented genre APIs. WHY: Bevy code stays idiomatic ECS and uses only documented Bevy APIs.
• Do not pick a physics or net crate here. WHY: Bevy code stays idiomatic ECS and uses only documented Bevy APIs.

Reference

Official pages stay on unversioned permalinks. The library pin on bevy-master stays 0.20.

Official Documentation

• Assets - Official asset catalog. No third-party crate was selected.
• Examples - Example tree on the latest branch.
• ECS - Component, systems, Query, Startup, Update, and .chain().
• Plugins - Plugin, DefaultPlugins, MinimalPlugins, and add_plugins.

Related Skills

Prerequisites

• bevy-master - ECS ownership and schedules.
• bevy-ecs-composition - Spawn and query shape.

Complements

• godot-genre-metroidvania - Peer skill for the same genre.
• bevy-ability-system - Traversal abilities.
• bevy-character-movement - Motion.
• bevy-save-load - Map flags.
• bevy-mechanic-secrets - Optional rooms.

Downstream / consumers

• None. This router does not own a second implementation.

Master

• bevy-master - Bevy router.