# Bevy Ecs Queries

> Use when writing `Query<D, F>` with filters like `With`/`Without`/`Or`, detecting changes with `Changed<T>`/`Added<T>`, parallelising with `par_iter`/`par_iter_mut`, building a query lens with `transmute_lens`, or hitting the new 0.18 `ArchetypeQueryData` bound. Covers Bevy 0.18 query patterns.

- **Type:** Skill
- **Install:** `agentstack add skill-chrisgliddon-bevy-skills-bevy-ecs-queries`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [chrisgliddon](https://agentstack.voostack.com/s/chrisgliddon)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [chrisgliddon](https://github.com/chrisgliddon)
- **Source:** https://github.com/chrisgliddon/bevy-skills/tree/main/skills/bevy-ecs-queries

## Install

```sh
agentstack add skill-chrisgliddon-bevy-skills-bevy-ecs-queries
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Bevy 0.18 — ECS Queries

## When to use this skill

- Reading or writing components from a system.
- Filtering by presence (`With`/`Without`), alternation (`Or`), or change detection (`Changed`/`Added`).
- Parallelising over a large entity set with `par_iter_mut`.
- Borrowing a subset of a query via a lens (`transmute_lens`).
- Compiler error mentioning `ArchetypeQueryData` (new bound in 0.18).

## Canonical pattern

```rust
use bevy::prelude::*;

#[derive(Component, Default)]
struct Health(f32);

#[derive(Component, Default)]
struct Velocity(Vec3);

#[derive(Component)]
struct Player;

#[derive(Component)]
struct Enemy;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Update, (
            move_things,
            on_health_changed,
            damage_visible_enemies,
            integrate_in_parallel,
        ))
        .run();
}

// Sequential iteration. `&` for read, `&mut` for write.
fn move_things(time: Res, mut q: Query) {
    let dt = time.delta_secs();
    for (vel, mut tf) in &mut q {
        tf.translation += vel.0 * dt;
    }
}

// Change detection. `Changed` triggers on insert OR mutation.
// `Added` triggers only on insert.
fn on_health_changed(q: Query>) {
    for (entity, hp) in &q {
        info!("entity {:?} now has {} hp", entity, hp.0);
    }
}

// Combined filters. `With`/`Without` constrain entities;
// `Or` alternates over filters (not components).
fn damage_visible_enemies(
    mut q: Query, Without, Or, Changed)>)>,
) {
    for mut hp in &mut q {
        hp.0 -= 1.0;
    }
}

// Parallel iteration. Use when N is large (>10k) and per-entity work is non-trivial.
// Cannot use `Commands` or external mutable state — task pool runs items in parallel.
fn integrate_in_parallel(mut q: Query) {
    q.par_iter_mut().for_each(|(vel, mut tf)| {
        tf.translation += vel.0 * 0.016;
    });
}

// Query lens: temporarily view a query as a narrower one. Useful for
// passing a stricter query into a helper without re-binding the system's
// SystemParam list.
#[allow(dead_code)]
fn use_lens(mut q: Query) {
    // Read-only narrowed view of just the Transform column.
    let mut lens = q.transmute_lens::();
    let _read_only: Query = lens.query();
}
```

## Gotchas (0.18)

- **`ArchetypeQueryData`** is a new trait that bounds query data types where the exact item count must be known at compile time (e.g. `for_each`-style ergonomics). If you get a "trait `ArchetypeQueryData` not implemented" error, you're using a dynamic query (`FilteredEntityRef`/`FilteredEntityMut`) where a static one is required. Re-shape the query.
- **`EntityMut::get_components_mut::()`** is the safe way to grab two `&mut`s out of one entity in 0.18 — returns `Result`. Don't reach for `unsafe` `World::get_mut` aliasing tricks.
- **`Query::get`/`get_mut` returns `Result`, not `Option`**. The error type carries the entity, so don't swallow it with `.ok()` if you actually need to know why a lookup missed.
- **`Or, With)>`** — `Or` alternates over **filters**, not raw component types. `Or` does not compile.
- **`Changed`/`Added` are tick-based.** A system that runs every other frame can miss changes only seen in the skipped frame. If you must not miss a change, use observers or a buffered queue.
- **Don't pair `par_iter_mut` with `Commands`.** Spawn/despawn from a sequential system that consumes a `Resource` queue written by the parallel one.

## See also

- `bevy-ecs-components` — declaring the components queried here.
- `bevy-ecs-systems` — using queries inside `SystemParam` and run conditions.
- `bevy-migration-0-17-to-0-18` — `EntityMut::get_components_mut` and tick-type move.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [chrisgliddon](https://github.com/chrisgliddon)
- **Source:** [chrisgliddon/bevy-skills](https://github.com/chrisgliddon/bevy-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-chrisgliddon-bevy-skills-bevy-ecs-queries
- Seller: https://agentstack.voostack.com/s/chrisgliddon
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.