Struct Query 

pub struct Query<'w, Q>
where
    Q: QueryData,
{ /* private fields */ }

The ECS: entities, components, queries, resources, commands. A query over a World, created by World::query.

struct Pos(f32);
struct Vel(f32);
struct Frozen;

let mut world = World::new();
world.spawn((Pos(0.0), Vel(1.0)));
world.spawn((Pos(0.0), Vel(1.0), Frozen));

world.query::<(&mut Pos, &Vel)>().without::<Frozen>().for_each(|(p, v)| p.0 += v.0);

let moved = world.query::<&Pos>().iter().filter(|p| p.0 > 0.0).count();
assert_eq!(moved, 1);

Implementations

impl<'w, Q> Query<'w, Q>

where Q: QueryData,

pub fn with<T>(self) -> Query<'w, Q>

where T: Component,

Only match entities that also have component T (without fetching it).

Panics

With more than 4 with filters on one query.

Examples found in repository

examples/physics.rs (line 123)

fn drop_things(ctx: &mut Ctx) {
    let at = ctx.mouse_world();
    if ctx.mouse_pressed(MouseButton::Left) {
        ctx.world.spawn((
            Transform2D::at(at),
            RigidBody::dynamic(),
            Collider::rect(vec2(30.0, 30.0)).friction(0.8),
        ));
    }
    if ctx.mouse_pressed(MouseButton::Right) {
        ctx.world.spawn((
            Transform2D::at(at),
            RigidBody::dynamic(),
            Collider::circle(12.0).restitution(0.6),
        ));
    }
    if ctx.mouse_pressed(MouseButton::Middle) {
        let rock: Vec<Vec2> = (0..5)
            .map(|i| Vec2::from_angle(i as f32 * std::f32::consts::TAU / 5.0) * 18.0)
            .collect();
        ctx.world.spawn((
            Transform2D::at(at),
            RigidBody::dynamic(),
            Collider::polygon(&rock).friction(0.7),
        ));
    }
    if ctx.key_pressed(Key::R) {
        let all: Vec<Entity> = ctx.world.query::<Entity>().with::<RigidBody>().iter().collect();
        for e in all {
            ctx.world.despawn(e);
        }
        build_level(ctx);
    }
    if ctx.key_pressed(Key::Escape) {
        ctx.quit();
    }
}

pub fn without<T>(self) -> Query<'w, Q>

where T: Component,

Skip entities that have component T.

Panics

With more than 4 without filters on one query.

pub fn for_each(&mut self, f: impl FnMut(<Q as QueryData>::Item<'_>))

Runs f for every matching entity. The fastest way to loop.

Examples found in repository

examples/3d.rs (lines 26-28)

fn spin(ctx: &mut Ctx) {
    let dt = ctx.dt();
    ctx.world.query::<(&mut Transform3D, &Spin)>().for_each(|(t, s)| {
        t.rotation *= Quat::from_rotation_y(s.0 * dt);
    });
}

examples/ribbons.rs (lines 9-11)

fn fly(ctx: &mut Ctx) {
    let t = ctx.time() as f32;
    ctx.world.query::<(&mut Transform3D, &Orbiting)>().for_each(|(at, _)| {
        at.position = vec3(t.cos() * 3.0, 1.0 + (t * 2.0).sin() * 0.5, t.sin() * 3.0);
    });
}

examples/tiles.rs (lines 130-134)

fn paint(ctx: &mut Ctx) {
    if !ctx.mouse_down(MouseButton::Left) || ctx.mouse_over_ui() {
        return;
    }
    let at = ctx.mouse_world();
    ctx.world.query::<(&Transform2D, &mut TileMap)>().for_each(|(t, map)| {
        if let Some(tile) = map.tile_at(t.position, at) {
            map.set(tile.x, tile.y, Some(STONE));
        }
    });
}

examples/scene_viewer.rs (lines 19-22)

fn extent(world: &mut World) -> (Vec3, f32) {
    let (mut min, mut max) = (Vec3::splat(f32::MAX), Vec3::splat(f32::MIN));
    world.query::<(&Transform3D, &Model)>().for_each(|(t, _)| {
        min = min.min(t.position);
        max = max.max(t.position);
    });
    if min.x > max.x {
        return (Vec3::ZERO, 10.0);
    }
    ((min + max) * 0.5, (max - min).max_element().max(10.0))
}

examples/ecs.rs (lines 52-62)

fn movement(ctx: &mut Ctx) {
    let dt = ctx.dt();
    let bounds = ctx.window_size();
    ctx.world.query::<(&mut Transform2D, &mut Vel)>().for_each(|(t, v)| {
        t.position += v.0 * dt;
        t.rotation = v.0.to_angle();
        if t.position.x < 0.0 || t.position.x > bounds.x {
            v.0.x = -v.0.x;
        }
        if t.position.y < 0.0 || t.position.y > bounds.y {
            v.0.y = -v.0.y;
        }
        t.position = t.position.clamp(Vec2::ZERO, bounds);
    });
}

/// Simulation: age, fade out, and despawn through commands.
fn aging(ctx: &mut Ctx) {
    let dt = ctx.dt();
    let commands = &mut ctx.commands;
    ctx.world
        .query::<(Entity, &mut Life, &mut Sprite)>()
        .for_each(|(e, life, sprite)| {
            life.0 -= dt;
            sprite.color = sprite.color.with_alpha((life.0 / LIFETIME).clamp(0.0, 1.0));
            if life.0 <= 0.0 {
                commands.despawn(e);
            }
        });
}

examples/editor.rs (lines 43-54)

fn walk(ctx: &mut Ctx) {
    let dt = ctx.dt();
    let bounds = ctx.window_size();
    ctx.world.query::<(&mut Transform2D, &mut Walker)>().for_each(|(t, w)| {
        let mut v = Vec2::from_angle(w.heading) * w.speed;
        t.position += v * dt;
        if !(0.0..=bounds.x).contains(&t.position.x) {
            v.x = -v.x;
        }
        if !(0.0..=bounds.y).contains(&t.position.y) {
            v.y = -v.y;
        }
        t.position = t.position.clamp(Vec2::ZERO, bounds);
        w.heading = v.to_angle();
    });
}

Additional examples can be found in:

• examples/ants.rs
• examples/ui_panel.rs
• examples/skinning.rs
• examples/bunnymark_ecs.rs
• examples/ffi_bench.rs
• examples/battle.rs

pub fn par_for_each( &mut self, f: impl Fn(<Q as QueryData>::Item<'_>) + Send + Sync, )

Like for_each, but spread over all CPU cores.

Each archetype is cut into chunks of rows, and the chunks run in parallel. Use it for heavy per-entity work over many entities; for a few thousand cheap updates, for_each is just as fast.

f can’t capture &mut state (it runs on many threads at once). To spawn or despawn, collect what you need and use commands afterwards.

struct Pos(f32);
struct Vel(f32);
let mut world = World::new();
world.spawn_batch((0..100_000).map(|i| (Pos(i as f32), Vel(1.0))));

world.query::<(&mut Pos, &Vel)>().par_for_each(|(p, v)| p.0 += v.0);

Examples found in repository

examples/tiles.rs (line 121)

fn wander(ctx: &mut Ctx) {
    let dt = ctx.dt();
    ctx.world
        .query::<(&mut Transform2D, &Wander)>()
        .par_for_each(|(t, w)| t.position += w.0 * dt);
}

examples/headless.rs (lines 21-27)

fn wander(ctx: &mut Ctx) {
    let dt = ctx.dt();
    ctx.world
        .query::<(&mut Transform2D, &mut Agent)>()
        .par_for_each(|(t, a)| {
            let p = &mut t.position;
            a.heading += (p.x * 0.013 + p.y * 0.007 + a.heading).sin() * 0.8 * dt;
            p.x = (p.x + a.heading.cos() * a.speed * dt).rem_euclid(WORLD);
            p.y = (p.y + a.heading.sin() * a.speed * dt).rem_euclid(WORLD);
            t.rotation = a.heading;
        });
}

examples/flow.rs (lines 103-118)

fn steer(ctx: &mut Ctx) {
    let dt = ctx.dt();
    let random = ctx.random();
    // Taken out for the query, which borrows the world, then put back.
    let paths = ctx.world.remove_resource::<Paths>().expect("paths");
    ctx.world
        .query::<(Entity, &mut Transform2D, &mut Agent)>()
        .par_for_each(|(e, t, a)| {
            let mut rng = random.of(e);
            let cell = paths.nav.cell_at(t.position);
            let slow = cell.and_then(|c| paths.nav.cost(c.x, c.y)).unwrap_or(1).max(1) as f32;
            let want = paths.flow.direction_at(t.position) * (SPEED / slow);
            a.vel = a.vel.lerp(want, 0.15) + rng.unit_vec2() * 3.0;
            // Slide along walls instead of walking into them.
            let next = t.position + a.vel * dt;
            if paths.nav.walkable(next) {
                t.position = next;
            } else if paths.nav.walkable(vec2(next.x, t.position.y)) {
                t.position.x = next.x;
            } else if paths.nav.walkable(vec2(t.position.x, next.y)) {
                t.position.y = next.y;
            }
        });
    ctx.world.insert_resource(paths);
}

examples/boids.rs (lines 45-65)

fn flocking(bounds: Vec2) -> impl FnMut(&mut Ctx) {
    let mut grid = SpatialGrid::with_data(RADIUS);
    move |ctx: &mut Ctx| {
        let dt = ctx.dt();
        // Keep boids that are close in space close in memory, so neighbor
        // lookups hit the cache (1M boids: 62 -> 40 ms/tick).
        if ctx.sim_tick().is_multiple_of(SPATIAL_SORT_EVERY) {
            ctx.world.sort_by::<Transform2D>(|t| spatial_key(t.position, RADIUS));
        }
        grid.rebuild_with_data(
            ctx.world
                .query::<(Entity, &Transform2D, &Vel)>()
                .iter()
                .map(|(e, t, v)| (e, t.position, v.0)),
        );
        let grid = &grid;
        ctx.world
            .query::<(Entity, &mut Transform2D, &mut Vel)>()
            .par_for_each(|(me, t, v)| {
                let (mut away, mut heading, mut center, mut n) = (Vec2::ZERO, Vec2::ZERO, Vec2::ZERO, 0.0);
                grid.for_each_in_radius(t.position, RADIUS, |o| {
                    if o.entity == me {
                        return;
                    }
                    let d = t.position - o.position;
                    away += d / d.length_squared().max(1.0);
                    heading += o.data;
                    center += o.position;
                    n += 1.0;
                });
                let mut steer = away * 900.0;
                if n > 0.0 {
                    steer += (heading / n - v.0) * 1.5 + (center / n - t.position) * 1.2;
                }
                let speed = (v.0 + steer * dt).length().clamp(MIN_SPEED, MAX_SPEED);
                v.0 = (v.0 + steer * dt).normalize_or(Vec2::X) * speed;
                t.position = (t.position + v.0 * dt).rem_euclid(bounds);
                t.rotation = v.0.to_angle();
            });
    }
}

examples/ants.rs (lines 136-180)

fn steer(bounds: Vec2) -> impl FnMut(&mut Ctx) {
    let mut food_grid = SpatialGrid::new(SIGHT);
    move |ctx: &mut Ctx| {
        let (dt, random) = (ctx.dt(), ctx.random());
        food_grid.rebuild_from(
            ctx.world
                .query::<(Entity, &Transform2D, &Food)>()
                .iter()
                .map(|(e, t, _)| (e, t.position)),
        );
        let field = ctx.world.remove_resource::<Field>().expect("field");
        let (grid, f) = (&food_grid, &field);
        ctx.world
            .query::<(Entity, &mut Transform2D, &mut Ant)>()
            .par_for_each(|(e, t, ant)| {
                let mut rng = random.of(e);
                let p = t.position;
                let target = if ant.carrying {
                    (p.distance(ant.home_at) < SIGHT * 3.0).then_some(ant.home_at)
                } else {
                    grid.nearest(p, SIGHT, |_| true).map(|food| food.position)
                };
                if let Some(target) = target {
                    ant.heading = (target - p).to_angle();
                } else {
                    let layer = if ant.carrying { &f.to_home } else { &f.to_food };
                    let smell = |angle: f32| {
                        let at = p + Vec2::from_angle(ant.heading + angle) * SENSE_DIST;
                        f.index(at).map_or(-1.0, |i| layer[i])
                    };
                    let (left, ahead, right) = (smell(-SENSE_ANGLE), smell(0.0), smell(SENSE_ANGLE));
                    if ant.carrying && left.max(ahead).max(right) < FAINT {
                        // No trail to follow: real ants keep track of where
                        // home is (path integration) and head that way.
                        let off = (ant.home_at - p).to_angle() - ant.heading;
                        let off = (off + std::f32::consts::PI).rem_euclid(std::f32::consts::TAU) - std::f32::consts::PI;
                        ant.heading += off.clamp(-2.0 * dt, 2.0 * dt);
                    } else if left > ahead && left > right {
                        ant.heading -= 4.0 * dt;
                    } else if right > ahead && right > left {
                        ant.heading += 4.0 * dt;
                    }
                }
                ant.heading += rng.range(-2.5, 2.5) * dt;
                let mut next = p + Vec2::from_angle(ant.heading) * SPEED * dt;
                // Bounce off the edges.
                if next.x < 0.0 || next.x >= bounds.x {
                    ant.heading = std::f32::consts::PI - ant.heading;
                    next.x = next.x.clamp(0.0, bounds.x - 0.01);
                }
                if next.y < 0.0 || next.y >= bounds.y {
                    ant.heading = -ant.heading;
                    next.y = next.y.clamp(0.0, bounds.y - 0.01);
                }
                t.position = next;
                t.rotation = ant.heading;
                ant.since += dt;
                ant.energy -= dt;
            });
        ctx.world.insert_resource(field);
    }
}

/// Every tick: ants mark where they walk. Searching ants lay "home is this
/// way", carrying ants lay "food is this way"; fresher trails are stronger.
fn lay_trails(ctx: &mut Ctx) {
    let mut field = ctx.world.remove_resource::<Field>().expect("field");
    ctx.world.query::<(&Transform2D, &Ant)>().for_each(|(t, ant)| {
        if let Some(i) = field.index(t.position) {
            let strength = (1.0 - ant.since / 30.0).max(0.0);
            let layer = if ant.carrying {
                &mut field.to_food
            } else {
                &mut field.to_home
            };
            layer[i] = layer[i].max(strength);
        }
    });
    ctx.world.insert_resource(field);
}

/// Every 4th tick: trails fade.
fn evaporate(ctx: &mut Ctx) {
    let keep = 0.985f32.powf(ctx.dt() * 60.0);
    let field = ctx.world.resource_mut::<Field>();
    for v in field.to_food.iter_mut().chain(field.to_home.iter_mut()) {
        *v *= keep;
    }
}

/// Ants take turns (each every 2nd tick) picking up food and dropping it at
/// their nest; starving ants die. Each ant decides on all cores and notes
/// what happened in its `event`; one quick pass then applies the events.
fn forage(ctx: &mut Ctx) {
    let turn = ctx.turns(2);
    let mut food_grid = SpatialGrid::new(8.0);
    food_grid.rebuild_from(
        ctx.world
            .query::<(Entity, &Transform2D, &Food)>()
            .iter()
            .map(|(e, t, _)| (e, t.position)),
    );
    let grid = &food_grid;
    ctx.world
        .query::<(Entity, &Transform2D, &mut Ant)>()
        .par_for_each(|(e, t, ant)| {
            ant.event = Event::None;
            if ant.energy <= 0.0 {
                ant.event = Event::Starved;
                return;
            }
            if !turn.includes(e) {
                return;
            }
            let at_home = t.position.distance(ant.home_at) < NEST_RADIUS;
            if ant.carrying {
                if at_home {
                    ant.carrying = false;
                    ant.since = 0.0;
                    ant.energy = LIFESPAN;
                    ant.heading += std::f32::consts::PI;
                    ant.event = Event::Delivered;
                }
            } else if at_home {
                ant.since = 0.0;
            } else if let Some(f) = grid.nearest(t.position, 4.0, |_| true) {
                ant.carrying = true;
                ant.since = 0.0;
                ant.heading += std::f32::consts::PI;
                ant.event = Event::PickedUp(f.entity);
            }
        });

    let (mut picked, mut delivered) = (Vec::new(), Vec::new());
    let cmds = &mut ctx.commands;
    ctx.world
        .query::<(Entity, &Ant)>()
        .for_each(|(e, ant)| match ant.event {
            Event::None => {}
            Event::Starved => cmds.despawn(e),
            Event::PickedUp(food) => picked.push(food),
            Event::Delivered => delivered.push(ant.home),
        });
    for f in picked {
        if let Some(food) = ctx.world.get_mut::<Food>(f) {
            food.amount = food.amount.saturating_sub(1);
            if food.amount == 0 {
                ctx.world.despawn(f);
            }
        }
    }
    for nest in delivered {
        if let Some(n) = ctx.world.get_mut::<Nest>(nest) {
            n.stored += 1;
            n.delivered += 1;
        }
    }
}

examples/battle.rs (lines 252-307)

fn fight() -> impl FnMut(&mut Ctx) {
    // Per team: a fine grid for friends (only the closest few matter) and a
    // coarse one for enemies (seen from afar). Marching armies far from the
    // enemy then cost almost nothing to search, however packed they are.
    let mut near = [
        SpatialGrid::new(PERSONAL_SPACE * 2.0),
        SpatialGrid::new(PERSONAL_SPACE * 2.0),
    ];
    let mut far = [SpatialGrid::new(SIGHT), SpatialGrid::new(SIGHT)];
    let mut positions: Vec<(Entity, Vec2, Team)> = Vec::new();
    move |ctx: &mut Ctx| {
        let (dt, random, look) = (ctx.dt(), ctx.random(), ctx.turns(4));
        let crowding = ctx.sim_tick().is_multiple_of(2);
        ctx.world
            .query::<(Entity, &Transform2D, &Unit)>()
            .par_collect_into(&mut positions, |(e, t, u)| (e, t.position, u.team));
        // The four grids are independent: build them at the same time.
        let [near_red, near_blue] = &mut near;
        let [far_red, far_blue] = &mut far;
        let all = &positions;
        let of = |team: Team| all.iter().filter(move |p| p.2 == team).map(|&(e, at, _)| (e, at));
        rayon::scope(|s| {
            if crowding {
                s.spawn(|_| near_red.rebuild_from(of(Team::Red)));
                s.spawn(|_| near_blue.rebuild_from(of(Team::Blue)));
            }
            s.spawn(|_| far_red.rebuild_from(of(Team::Red)));
            s.spawn(|_| far_blue.rebuild_from(of(Team::Blue)));
        });
        let over = ctx.world.resource::<Score>().winner.is_some();
        let battle = ctx.world.remove_resource::<Battle>().expect("battle");
        let (near, far, b) = (&near, &far, &battle);
        ctx.world
            .query::<(Entity, &mut Transform2D, &mut Unit)>()
            .par_for_each(|(e, t, unit)| {
                let mut rng = random.of(e);
                let me = t.position;
                unit.hit = None;
                unit.cooldown -= dt;
                if crowding {
                    let mut push = Vec2::ZERO;
                    near[unit.team.index()].for_each_in_radius(me, PERSONAL_SPACE, |other| {
                        if other.entity != e {
                            let away = me - other.position;
                            push += away / (away.length_squared() + 0.01);
                        }
                    });
                    unit.push = push.clamp_length_max(1.0);
                }
                let mut nearest = None;
                if unit.engaged || look.includes(e) {
                    let enemies = &far[unit.team.enemy().index()];
                    nearest = enemies
                        .nearest(me, REACH, |_| true)
                        .or_else(|| enemies.nearest(me, SIGHT, |_| true))
                        .map(|g| (g.position.distance_squared(me), g.entity, g.position));
                    unit.engaged = nearest.is_some();
                }
                let enemy_base = b.bases[unit.team.enemy().index()];
                let mut want = match nearest {
                    Some((d2, target, _)) if d2 < REACH * REACH => {
                        if unit.cooldown <= 0.0 {
                            unit.cooldown = COOLDOWN * rng.range(0.8, 1.2);
                            unit.hit = Some(Hit::Unit(target));
                        }
                        Vec2::ZERO
                    }
                    Some((_, _, at)) => (at - me).normalize_or_zero() * SPEED,
                    None if me.distance(enemy_base) < BASE_RADIUS + REACH => {
                        if unit.cooldown <= 0.0 && !over {
                            unit.cooldown = COOLDOWN;
                            unit.hit = Some(Hit::Base);
                        }
                        Vec2::ZERO
                    }
                    None => b.fields[unit.team.index()].direction_at(me) * SPEED,
                };
                let slow = b.nav.cell_at(me).and_then(|c| b.nav.cost(c.x, c.y)).unwrap_or(1).max(1) as f32;
                want = want / slow + unit.push * SPEED;
                unit.vel = unit.vel.lerp(want, 0.2) + rng.unit_vec2() * 2.0;
                // Slide along walls instead of walking into them.
                let next = me + unit.vel * dt;
                if b.nav.walkable(next) {
                    t.position = next;
                } else if b.nav.walkable(vec2(next.x, me.y)) {
                    t.position.x = next.x;
                } else if b.nav.walkable(vec2(me.x, next.y)) {
                    t.position.y = next.y;
                }
            });
        ctx.world.insert_resource(battle);
    }
}

pub fn par_for_each_indexed( &mut self, f: impl Fn(usize, <Q as QueryData>::Item<'_>) + Send + Sync, )

Like par_for_each, but also passes each entity’s position in the query, 0..count(), in the same order as for_each and iter.

Use it to fill a buffer from all cores: every entity writes its own slot, so the result comes out in a stable order.

use std::sync::atomic::{AtomicU32, Ordering};

struct Pos(f32);
let mut world = World::new();
world.spawn_batch((0..10_000).map(|i| (Pos(i as f32),)));

let mut query = world.query::<&Pos>();
let out: Vec<AtomicU32> = (0..query.count()).map(|_| AtomicU32::new(0)).collect();
query.par_for_each_indexed(|i, p| out[i].store(p.0 as u32 * 2, Ordering::Relaxed));
assert_eq!(out[1234].load(Ordering::Relaxed), 2468);

pub fn par_collect_into<R>( &mut self, out: &mut Vec<R>, f: impl Fn(<Q as QueryData>::Item<'_>) -> R + Send + Sync, )

where R: Send,

Replaces the contents of out with f of every matching entity, computed on all cores, in the same order as for_each. out keeps its memory between calls, so collecting every tick allocates nothing once it’s big enough.

struct Pos(f32);
let mut world = World::new();
world.spawn_batch((0..10_000).map(|i| (Pos(i as f32),)));

let mut doubled = Vec::new();
world.query::<&Pos>().par_collect_into(&mut doubled, |p| p.0 * 2.0);
assert_eq!(doubled[1234], 2468.0);

Examples found in repository

examples/battle.rs (line 233)

fn fight() -> impl FnMut(&mut Ctx) {
    // Per team: a fine grid for friends (only the closest few matter) and a
    // coarse one for enemies (seen from afar). Marching armies far from the
    // enemy then cost almost nothing to search, however packed they are.
    let mut near = [
        SpatialGrid::new(PERSONAL_SPACE * 2.0),
        SpatialGrid::new(PERSONAL_SPACE * 2.0),
    ];
    let mut far = [SpatialGrid::new(SIGHT), SpatialGrid::new(SIGHT)];
    let mut positions: Vec<(Entity, Vec2, Team)> = Vec::new();
    move |ctx: &mut Ctx| {
        let (dt, random, look) = (ctx.dt(), ctx.random(), ctx.turns(4));
        let crowding = ctx.sim_tick().is_multiple_of(2);
        ctx.world
            .query::<(Entity, &Transform2D, &Unit)>()
            .par_collect_into(&mut positions, |(e, t, u)| (e, t.position, u.team));
        // The four grids are independent: build them at the same time.
        let [near_red, near_blue] = &mut near;
        let [far_red, far_blue] = &mut far;
        let all = &positions;
        let of = |team: Team| all.iter().filter(move |p| p.2 == team).map(|&(e, at, _)| (e, at));
        rayon::scope(|s| {
            if crowding {
                s.spawn(|_| near_red.rebuild_from(of(Team::Red)));
                s.spawn(|_| near_blue.rebuild_from(of(Team::Blue)));
            }
            s.spawn(|_| far_red.rebuild_from(of(Team::Red)));
            s.spawn(|_| far_blue.rebuild_from(of(Team::Blue)));
        });
        let over = ctx.world.resource::<Score>().winner.is_some();
        let battle = ctx.world.remove_resource::<Battle>().expect("battle");
        let (near, far, b) = (&near, &far, &battle);
        ctx.world
            .query::<(Entity, &mut Transform2D, &mut Unit)>()
            .par_for_each(|(e, t, unit)| {
                let mut rng = random.of(e);
                let me = t.position;
                unit.hit = None;
                unit.cooldown -= dt;
                if crowding {
                    let mut push = Vec2::ZERO;
                    near[unit.team.index()].for_each_in_radius(me, PERSONAL_SPACE, |other| {
                        if other.entity != e {
                            let away = me - other.position;
                            push += away / (away.length_squared() + 0.01);
                        }
                    });
                    unit.push = push.clamp_length_max(1.0);
                }
                let mut nearest = None;
                if unit.engaged || look.includes(e) {
                    let enemies = &far[unit.team.enemy().index()];
                    nearest = enemies
                        .nearest(me, REACH, |_| true)
                        .or_else(|| enemies.nearest(me, SIGHT, |_| true))
                        .map(|g| (g.position.distance_squared(me), g.entity, g.position));
                    unit.engaged = nearest.is_some();
                }
                let enemy_base = b.bases[unit.team.enemy().index()];
                let mut want = match nearest {
                    Some((d2, target, _)) if d2 < REACH * REACH => {
                        if unit.cooldown <= 0.0 {
                            unit.cooldown = COOLDOWN * rng.range(0.8, 1.2);
                            unit.hit = Some(Hit::Unit(target));
                        }
                        Vec2::ZERO
                    }
                    Some((_, _, at)) => (at - me).normalize_or_zero() * SPEED,
                    None if me.distance(enemy_base) < BASE_RADIUS + REACH => {
                        if unit.cooldown <= 0.0 && !over {
                            unit.cooldown = COOLDOWN;
                            unit.hit = Some(Hit::Base);
                        }
                        Vec2::ZERO
                    }
                    None => b.fields[unit.team.index()].direction_at(me) * SPEED,
                };
                let slow = b.nav.cell_at(me).and_then(|c| b.nav.cost(c.x, c.y)).unwrap_or(1).max(1) as f32;
                want = want / slow + unit.push * SPEED;
                unit.vel = unit.vel.lerp(want, 0.2) + rng.unit_vec2() * 2.0;
                // Slide along walls instead of walking into them.
                let next = me + unit.vel * dt;
                if b.nav.walkable(next) {
                    t.position = next;
                } else if b.nav.walkable(vec2(next.x, me.y)) {
                    t.position.x = next.x;
                } else if b.nav.walkable(vec2(me.x, next.y)) {
                    t.position.y = next.y;
                }
            });
        ctx.world.insert_resource(battle);
    }
}

pub fn iter(&mut self) -> QueryIter<'_, Q>

An iterator over matching entities, for map/filter/sum and friends.

Convenient, but several times slower than for_each on tight math loops (the compiler can’t vectorize across archetypes). Use for_each for per-tick simulation work.

Examples found in repository

examples/hotpatch.rs (line 18)

fn spin(ctx: &mut Ctx) {
    let dt = ctx.dt();
    for t in ctx.world.query::<&mut Transform2D>().iter() {
        t.rotation += -6.0 * dt;
    }
}
// ANCHOR_END: spin

/// Crabs breathe. Try a bigger amplitude, or a different shape.
fn wobble(ctx: &mut Ctx) {
    let time = ctx.sim_time() as f32;
    for (t, crab) in ctx.world.query::<(&mut Transform2D, &Crab)>().iter() {
        let s = 1.0 + 0.15 * (time * 3.0 + crab.0).sin();
        t.scale = vec2(s, s);
    }
}

/// Prints the first crab's rotation once a second, so you can see that
/// state carries over a patch.
fn report(ctx: &mut Ctx) {
    let tick = ctx.sim_tick();
    if tick.is_multiple_of(60)
        && let Some(t) = ctx.world.query::<&Transform2D>().iter().next()
    {
        println!("tick {tick:>5}  rotation {:>7.2}", t.rotation);
    }
}

examples/physics.rs (line 65)

fn ring_the_bell(ctx: &mut Ctx) {
    let mut rang = false;
    for c in ctx.events.read::<CollisionStarted>() {
        rang |= c.sensor && [c.a, c.b].iter().any(|&e| ctx.world.has::<Bell>(e));
    }
    let dt = ctx.dt();
    for bell in ctx.world.query::<&mut Bell>().iter() {
        bell.rang = if rang { 1.0 } else { (bell.rang - dt * 2.0).max(0.0) };
    }
}
// ANCHOR_END: collisions

// ANCHOR: queries
fn blast(ctx: &mut Ctx) {
    if !ctx.key_pressed(Key::Space) {
        return;
    }
    let center = ctx.mouse_world();
    let mut near = Vec::new();
    ctx.physics.entities_in_circle(center, 200.0, &mut near);
    for e in near {
        let Some(t) = ctx.world.get::<Transform2D>(e) else {
            continue;
        };
        let away = (t.position - center).normalize_or(Vec2::NEG_Y);
        if let Some(mass) = ctx.physics.mass(e) {
            ctx.physics.apply_impulse(e, away * mass * 600.0);
        }
    }
}

/// What's under the mouse, straight down: a laser from the cursor.
fn laser(ctx: &mut Ctx) -> Option<RayHit> {
    ctx.physics.cast_ray(ctx.mouse_world(), vec2(0.0, 1.0), H)
}
// ANCHOR_END: queries

fn drop_things(ctx: &mut Ctx) {
    let at = ctx.mouse_world();
    if ctx.mouse_pressed(MouseButton::Left) {
        ctx.world.spawn((
            Transform2D::at(at),
            RigidBody::dynamic(),
            Collider::rect(vec2(30.0, 30.0)).friction(0.8),
        ));
    }
    if ctx.mouse_pressed(MouseButton::Right) {
        ctx.world.spawn((
            Transform2D::at(at),
            RigidBody::dynamic(),
            Collider::circle(12.0).restitution(0.6),
        ));
    }
    if ctx.mouse_pressed(MouseButton::Middle) {
        let rock: Vec<Vec2> = (0..5)
            .map(|i| Vec2::from_angle(i as f32 * std::f32::consts::TAU / 5.0) * 18.0)
            .collect();
        ctx.world.spawn((
            Transform2D::at(at),
            RigidBody::dynamic(),
            Collider::polygon(&rock).friction(0.7),
        ));
    }
    if ctx.key_pressed(Key::R) {
        let all: Vec<Entity> = ctx.world.query::<Entity>().with::<RigidBody>().iter().collect();
        for e in all {
            ctx.world.despawn(e);
        }
        build_level(ctx);
    }
    if ctx.key_pressed(Key::Escape) {
        ctx.quit();
    }
}

fn draw(ctx: &mut Ctx) {
    ctx.clear(Color::hex(0x1d2330));
    let shapes: Vec<(Transform2D, Collider, bool, f32)> = ctx
        .world
        .query::<(&Transform2D, &Collider, &RigidBody, Option<&Bell>)>()
        .iter()
        .map(|(t, c, b, bell)| (*t, *c, b.kind == BodyKind::Fixed, bell.map_or(0.0, |b| b.rang)))
        .collect();
    for (t, c, fixed, rang) in shapes {
        let color = if c.sensor {
            Color::rgba(1.0, 0.3 + 0.7 * (1.0 - rang), 0.3, 0.35)
        } else if fixed {
            Color::hex(0x4a5568)
        } else {
            Color::hex(0xf6ad55)
        };
        match c.shape {
            Shape::Circle { radius } => {
                ctx.draw_circle(t.position, radius, color);
                // A spoke shows the spin.
                let spoke = t.position + Vec2::from_angle(t.rotation) * radius;
                ctx.draw_line(t.position, spoke, 2.0, Color::hex(0x1d2330));
            }
            Shape::Rect { size } => {
                // Four corners turned with the body, drawn as edges.
                let (sin, cos) = t.rotation.sin_cos();
                let turn = |v: Vec2| t.position + vec2(v.x * cos - v.y * sin, v.x * sin + v.y * cos);
                let h = size / 2.0;
                let corners = [vec2(-h.x, -h.y), vec2(h.x, -h.y), vec2(h.x, h.y), vec2(-h.x, h.y)].map(turn);
                if fixed || c.sensor {
                    ctx.draw_rect(Rect::new(t.position.x - h.x, t.position.y - h.y, size.x, size.y), color);
                } else {
                    for i in 0..4 {
                        ctx.draw_line(corners[i], corners[(i + 1) % 4], 3.0, color);
                    }
                }
            }
            Shape::Capsule { height, radius } => {
                let up = Vec2::from_angle(t.rotation + std::f32::consts::FRAC_PI_2) * height / 2.0;
                ctx.draw_line(t.position - up, t.position + up, radius * 2.0, color);
            }
            Shape::Polygon { .. } => {
                let (sin, cos) = t.rotation.sin_cos();
                let turn = |v: Vec2| t.position + vec2(v.x * cos - v.y * sin, v.x * sin + v.y * cos);
                let corners: Vec<Vec2> = c.shape.points().iter().map(|&p| turn(p + c.offset)).collect();
                for i in 0..corners.len() {
                    ctx.draw_line(corners[i], corners[(i + 1) % corners.len()], 3.0, color);
                }
            }
            _ => {} // shapes added in later versions
        }
    }
    if let Some(hit) = laser(ctx) {
        ctx.draw_line(ctx.mouse_world(), hit.point, 1.0, Color::rgba(1.0, 0.2, 0.2, 0.8));
        ctx.draw_circle(hit.point, 4.0, Color::rgb(1.0, 0.2, 0.2));
    }
    let bodies = ctx.physics.body_count();
    ctx.draw_text(
        &format!(
            "{bodies} bodies  |  left click: crate  right click: ball  middle click: rock  space: blast  R: reset"
        ),
        vec2(30.0, 30.0),
        18.0,
        Color::WHITE,
    );
}

examples/gamepad.rs (line 42)

fn move_players(ctx: &mut Ctx) {
    let dt = ctx.dt();
    // Read the pads first: the query below borrows the world.
    let mut sticks = [Vec2::ZERO; MAX_GAMEPADS];
    let mut spins = [false; MAX_GAMEPADS];
    let mut grow = [0.0; MAX_GAMEPADS];
    for &pad in ctx.gamepads() {
        sticks[pad.slot()] = ctx.gamepad_stick(pad, GamepadStick::Left);
        spins[pad.slot()] = ctx.gamepad_pressed(pad, GamepadButton::South);
        grow[pad.slot()] = ctx.gamepad_axis(pad, GamepadAxis::RightTrigger);
    }
    for (t, player) in ctx.world.query::<(&mut Transform2D, &mut Player)>().iter() {
        let Some(slot) = player.slot else { continue };
        t.position += sticks[slot] * SPEED * dt;
        if spins[slot] {
            player.spin = std::f32::consts::TAU;
        }
        t.scale = Vec2::splat(1.0 + 2.0 * grow[slot]);
    }
}
// ANCHOR_END: gamepad

/// Arrow keys move the keyboard's crab.
fn move_keyboard_player(ctx: &mut Ctx) {
    let dt = ctx.dt();
    let mut dir = Vec2::ZERO;
    for (key, d) in [
        (Key::Left, -Vec2::X),
        (Key::Right, Vec2::X),
        (Key::Up, -Vec2::Y),
        (Key::Down, Vec2::Y),
    ] {
        if ctx.key_down(key) {
            dir += d;
        }
    }
    let spin = ctx.key_pressed(Key::Space);
    for (t, player) in ctx.world.query::<(&mut Transform2D, &mut Player)>().iter() {
        if player.slot.is_none() {
            t.position += dir.normalize_or_zero() * SPEED * dt;
            if spin {
                player.spin = std::f32::consts::TAU;
            }
        }
    }
}

/// One crab per connected pad: spawn on plug-in, despawn on unplug.
fn join_and_leave(ctx: &mut Ctx) {
    let mut connected = [false; MAX_GAMEPADS];
    for pad in ctx.gamepads() {
        connected[pad.slot()] = true;
    }
    let mut has_crab = [false; MAX_GAMEPADS];
    for (e, player) in ctx.world.query::<(Entity, &Player)>().iter() {
        if let Some(slot) = player.slot {
            if connected[slot] {
                has_crab[slot] = true;
            } else {
                ctx.commands.despawn(e);
            }
        }
    }
    for slot in (0..MAX_GAMEPADS).filter(|&s| connected[s] && !has_crab[s]) {
        let mut sprite = Sprite::new(ctx.load_texture("crab.png"));
        sprite.color = PLAYER_COLORS[slot];
        let at = vec2(200.0 + slot as f32 * 120.0, 360.0);
        ctx.world.spawn((
            Transform2D::at(at),
            sprite,
            Player {
                slot: Some(slot),
                spin: 0.0,
            },
        ));
    }
}

/// Spins play out over half a second.
fn spin(ctx: &mut Ctx) {
    let dt = ctx.dt();
    for (t, player) in ctx.world.query::<(&mut Transform2D, &mut Player)>().iter() {
        let step = player.spin.min(4.0 * std::f32::consts::TAU * dt);
        t.rotation += step;
        player.spin -= step;
    }
}

examples/ffi_bench.rs (line 35)

fn main() {
    let mut world = World::new();
    world.spawn_batch((0..1_000_000).map(|_| (Pos { x: 0.0, y: 0.0 }, Vel { x: 1.0, y: 2.0 })));
    let mut samples = Vec::with_capacity(200);
    for i in 0..210 {
        let start = Instant::now();
        world.query::<(&mut Pos, &Vel)>().for_each(|(p, v)| {
            p.x += v.x;
            p.y += v.y;
        });
        black_box(&world);
        let elapsed = start.elapsed().as_secs_f64() * 1000.0;
        if i >= 10 {
            samples.push(elapsed);
        }
    }
    samples.sort_by(f64::total_cmp);
    let checksum: f64 = world
        .query::<&Pos>()
        .iter()
        .map(|p| f64::from(p.x) + f64::from(p.y))
        .sum();
    assert_eq!(checksum, 630_000_000.0);
    println!(
        "Rust: 1000000 entities, median {:.6} ms/update, checksum {checksum:.0}",
        (samples[99] + samples[100]) / 2.0
    );
}

examples/navmesh3d.rs (line 34)

fn main() {
    // ANCHOR: query
    let nav = navigation();
    let start = nav.sample_position(vec3(-8.0, 1.0, 0.0), 2.0).unwrap();
    let destination = vec3(8.0, 0.0, 0.0);
    let corners = nav.find_path(start, destination).unwrap();
    assert!(corners.len() >= 3);
    // ANCHOR_END: query

    // ANCHOR: agents
    let mut world = Game::new("Navigation server", 1, 1)
        .fixed_hz(60)
        .sim_system(step_navmesh3d)
        .run_headless(600, |ctx| {
            ctx.world.insert_resource(nav);
            let mut agent = NavAgent3D::default();
            agent.destination = Some(destination);
            ctx.world.spawn((Transform3D::at(start), agent));
            // World-space AABB; move its center or despawn it to reopen polygons.
            ctx.world
                .spawn((NavObstacle3D::new(vec3(0.0, 1.0, 8.0), vec3(1.0, 1.0, 1.0)),));
        });
    let position = world.query::<&Transform3D>().iter().next().unwrap().position;
    assert!(position.distance(destination) < 0.3);
    // ANCHOR_END: agents
}

examples/lockstep.rs (line 62)

fn move_crabs(ctx: &mut Ctx) {
    let pads: Vec<Pad> = (0..ctx.net.players())
        .map(|p| ctx.net.input::<Pad>(p).unwrap_or_default())
        .collect();
    let dt = ctx.dt();
    let crabs: Vec<(Entity, Vec2, u32)> = ctx
        .world
        .query::<(Entity, &Transform2D, &Crab)>()
        .iter()
        .map(|(e, t, c)| (e, t.position, c.player))
        .collect();
    for &(e, at, player) in &crabs {
        let pad = &pads[player as usize];
        if pad.shove {
            for &(other, other_at, _) in &crabs {
                if other != e && at.distance(other_at) < 120.0 {
                    ctx.world.get_mut::<Crab>(other).unwrap().push += (other_at - at).normalize_or_zero() * 900.0;
                }
            }
        }
        let crab = *ctx.world.get::<Crab>(e).unwrap();
        let t = ctx.world.get_mut::<Transform2D>(e).unwrap();
        t.position += (pad.dir.normalize_or_zero() * 250.0 + crab.push) * dt;
        t.position = t.position.clamp(vec2(40.0, 40.0), vec2(760.0, 560.0));
        ctx.world.get_mut::<Crab>(e).unwrap().push = crab.push * 0.9;
    }
}
// ANCHOR_END: simulate

fn draw(ctx: &mut Ctx) {
    ctx.clear(Color::hex(0x20304a));
    let crabs: Vec<(Vec2, u32)> = ctx
        .world
        .query::<(&Transform2D, &Crab)>()
        .iter()
        .map(|(t, c)| (t.position, c.player))
        .collect();
    for (at, player) in crabs {
        let color = [Color::hex(0xf56565), Color::hex(0x63b3ed)][player as usize % 2];
        ctx.draw_circle(at, 30.0, color);
    }
    let net = &ctx.net;
    let status = match net.state() {
        NetState::Connecting => "waiting for the other player...".to_string(),
        NetState::Running => format!(
            "you are player {} ({}), tick {}{}",
            net.player() + 1,
            ["red", "blue"][net.player() % 2],
            ctx.sim_tick(),
            net.desync().map_or(String::new(), |d| format!("  DESYNC: {d}"))
        ),
        NetState::Lost => format!("connection lost: {}", net.error().unwrap_or("?")),
        NetState::Offline => "offline".into(),
        _ => String::new(),
    };
    ctx.draw_text(&status, vec2(20.0, 20.0), 20.0, Color::WHITE);
    #[cfg(feature = "steam")]
    if ctx.net.state() == NetState::Connecting
        && let Some(lobby) = ctx.net.steam_lobby()
    {
        let text = format!("Steam lobby {}: press I to invite a friend", lobby.raw());
        ctx.draw_text(&text, vec2(20.0, 50.0), 20.0, Color::WHITE);
        if ctx.key_pressed(Key::I) {
            ctx.net.steam_invite();
        }
    }
    if ctx.key_pressed(Key::Escape) {
        ctx.quit();
    }
}

Additional examples can be found in:

• examples/boids.rs
• examples/ants.rs
• examples/scene_viewer.rs

pub fn count(&mut self) -> usize

Number of matching entities (doesn’t visit them one by one).

Examples found in repository

examples/flow.rs (line 229)

fn hud(ctx: &mut Ctx) {
    let panel = Rect::new(12.0, 12.0, 260.0, 104.0);
    ctx.ui_panel(panel);
    let at = panel.min + ctx.ui_style.padding;
    let agents = ctx.world.query::<&Agent>().count();
    let ms = ctx.world.resource::<Paths>().compute_ms;
    let text = format!(
        "{agents} agents, {:.0} FPS\nfield: {}x{} cells, {ms:.2} ms\nclick: new goal   H: distances",
        ctx.fps(),
        MAP.x,
        MAP.y
    );
    ctx.ui_label(at, &text);
}

examples/ants.rs (line 305)

fn grow(bounds: Vec2) -> impl FnMut(&mut Ctx) {
    move |ctx: &mut Ctx| {
        let mut rng = ctx.random().stream(0);
        let sprite = ctx.world.resource::<AntLook>().0;
        let mut counts = std::collections::HashMap::new();
        ctx.world
            .query::<&Ant>()
            .for_each(|a| *counts.entry(a.home).or_insert(0u32) += 1);
        let mut nests = Vec::new();
        ctx.world
            .query::<(Entity, &Transform2D, &mut Nest)>()
            .for_each(|(e, t, n)| {
                n.ants = counts.get(&e).copied().unwrap_or(0);
                let born = n.stored.min(n.max_ants.saturating_sub(n.ants));
                n.stored -= born;
                nests.push((e, t.position, born));
            });
        for &(home, at, born) in &nests {
            for _ in 0..born {
                spawn_ant(&mut ctx.commands, sprite, home, at, rng.angle());
            }
        }
        let piles = ctx.world.query::<&Food>().count();
        let homes: Vec<Vec2> = nests.iter().map(|n| n.1).collect();
        for _ in piles..food_piles(bounds) {
            spawn_food(&mut ctx.commands, &mut rng, bounds, &homes);
        }
    }
}

// -------------------------------------------------------------------- setup

fn food_piles(bounds: Vec2) -> usize {
    ((bounds.x * bounds.y) / 60_000.0).ceil() as usize
}

fn spawn_ant(cmds: &mut Commands, sprite: Option<Texture>, home: Entity, at: Vec2, heading: f32) {
    let ant = Ant {
        home,
        home_at: at,
        heading,
        carrying: false,
        since: 0.0,
        energy: LIFESPAN,
        event: Event::None,
    };
    let t = Transform2D::at(at).rotated(heading);
    match sprite {
        Some(tex) => cmds.spawn((t, ant, Sprite::new(tex).with_color(Color::hex(0xD4553A)))),
        None => cmds.spawn((t, ant)),
    }
}

fn spawn_food(cmds: &mut Commands, rng: &mut Rng, bounds: Vec2, nests: &[Vec2]) {
    // Not too close to any nest, so trails have to form.
    let p = loop {
        let p = vec2(rng.range(20.0, bounds.x - 20.0), rng.range(20.0, bounds.y - 20.0));
        if nests.iter().all(|n| p.distance(*n) > 180.0) {
            break p;
        }
    };
    cmds.spawn((Transform2D::at(p), Food { amount: 400 }));
}

/// The simulation, shared by the windowed and headless runs.
fn colonies(game: Game, bounds: Vec2) -> Game {
    game.sim_system(steer(bounds))
        .sim_system(lay_trails)
        .sim_system(forage)
        .sim_system_every(4, evaporate)
        .sim_system_every(30, grow(bounds))
}

/// Nests on a grid, one per `NEST_AREA`; ants and food around them.
fn setup(ctx: &mut Ctx, bounds: Vec2, ants: usize, sprite: Option<Texture>) {
    ctx.world.reflect::<Ant>();
    ctx.world.reflect::<Nest>();
    ctx.world.reflect::<Food>();
    ctx.world.insert_resource(Field::new(bounds));
    ctx.world.insert_resource(AntLook(sprite));
    let mut rng = ctx.random().stream(1);
    let (cols, rows) = ((bounds.x / NEST_AREA.x) as usize, (bounds.y / NEST_AREA.y) as usize);
    let (cols, rows) = (cols.max(1), rows.max(1));
    let per_nest = (ants / (cols * rows)).max(1);
    let mut homes = Vec::new();
    for row in 0..rows {
        for col in 0..cols {
            let at = (vec2(col as f32, row as f32) + 0.5) * bounds / vec2(cols as f32, rows as f32);
            let nest = Nest {
                stored: 0,
                delivered: 0,
                max_ants: per_nest as u32 * 2,
                ants: per_nest as u32,
            };
            let home = ctx.world.spawn((Transform2D::at(at), nest));
            homes.push(at);
            for _ in 0..per_nest {
                spawn_ant(&mut ctx.commands, sprite, home, at, rng.angle());
            }
        }
    }
    for _ in 0..food_piles(bounds) {
        spawn_food(&mut ctx.commands, &mut rng, bounds, &homes);
    }
}

fn delivered(world: &mut World) -> u64 {
    world.query::<&Nest>().iter().map(|n| n.delivered).sum()
}

// ------------------------------------------------------------------ drawing

fn controls(ctx: &mut Ctx) {
    if ctx.key_pressed(Key::Space) {
        if ctx.is_paused() { ctx.resume() } else { ctx.pause() }
    }
    if ctx.key_pressed(Key::Period) {
        ctx.step();
    }
    for (key, speed) in [(Key::Num1, 1.0), (Key::Num2, 4.0), (Key::Num3, 16.0), (Key::Num4, 64.0)] {
        if ctx.key_pressed(key) {
            ctx.set_sim_speed(speed);
        }
    }
    if ctx.key_pressed(Key::Escape) {
        ctx.quit();
    }
}

/// Colony stats and sim controls, in a panel on top of the world.
fn hud(ctx: &mut Ctx) {
    let ants = ctx.world.query::<&Ant>().count();
    let nests = ctx.world.query::<&Nest>().count();
    let food = delivered(&mut ctx.world);
    let panel = Rect::new(12.0, 12.0, 260.0, 156.0);
    ctx.ui_panel(panel);
    let mut at = panel.min + ctx.ui_style.padding;
    let speed = if ctx.is_paused() {
        "paused".to_string()
    } else {
        format!("{}x", ctx.sim_speed())
    };
    let stats = format!(
        "{ants} ants in {nests} colonies\n{food} food delivered\nspeed {speed}, {:.0} FPS",
        ctx.fps()
    );
    at.y += ctx.ui_label(at, &stats).y + 8.0;
    let pause = if ctx.is_paused() { "Run" } else { "Pause" };
    if ctx.ui_button(Rect::new(at.x, at.y, 72.0, 30.0), pause) {
        if ctx.is_paused() { ctx.resume() } else { ctx.pause() }
    }
    for (i, speed) in [1.0f32, 4.0, 16.0].into_iter().enumerate() {
        let r = Rect::new(at.x + 80.0 + i as f32 * 54.0, at.y, 48.0, 30.0);
        if ctx.ui_button(r, &format!("{speed}x")) {
            ctx.set_sim_speed(speed);
            ctx.resume();
        }
    }
}

/// Draws the pheromone field (one texture, updated every frame), the food
/// piles and the nests. Ants are sprites, drawn by the engine.
fn draw_world(bounds: Vec2) -> impl FnMut(&mut Ctx) {
    let mut pixels = Vec::new();
    let mut dots: Vec<(Vec2, f32, Color)> = Vec::new();
    let mut field_texture = None;
    move |ctx: &mut Ctx| {
        let (w, h) = {
            let f = ctx.world.resource::<Field>();
            (f.w, f.h)
        };
        let field_tex =
            *field_texture.get_or_insert_with(|| ctx.create_texture(w as u32, h as u32, &vec![0; w * h * 4]));
        let field = ctx.world.resource::<Field>();
        pixels.clear();
        pixels.extend(field.to_food.iter().zip(&field.to_home).flat_map(|(&food, &home)| {
            let g = (food.sqrt() * 200.0) as u8;
            let b = (home.sqrt() * 120.0) as u8;
            [g / 3, g, b.max(g / 4), 255]
        }));
        ctx.update_texture(&field_tex, &pixels);
        ctx.clear(Color::BLACK);
        let scale = bounds / vec2(w as f32, h as f32);
        ctx.draw_ex(
            &field_tex,
            bounds * 0.5,
            DrawParams {
                scale,
                z: -10.0,
                ..Default::default()
            },
        );

        dots.clear();
        ctx.world.query::<(&Transform2D, &Food)>().for_each(|(t, f)| {
            dots.push((t.position, 2.0 + (f.amount as f32).sqrt() / 2.0, Color::hex(0x7BD389)));
        });
        ctx.world.query::<(&Transform2D, &Nest)>().for_each(|(t, _)| {
            dots.push((t.position, NEST_RADIUS, Color::hex(0x8E5A3C)));
        });
        for &(p, radius, color) in &dots {
            ctx.draw_circle(p, radius, color);
        }
    }
}

fn main() {
    let ants = env_number("ANTS", ANTS_PER_NEST as f64) as usize;
    let seed = env_number("SEED", DEFAULT_SEED as f64) as u64;
    // One colony's worth of space per ANTS_PER_NEST ants.
    let nests = (ants as f32 / ANTS_PER_NEST as f32).max(1.0);
    let side = nests.sqrt().ceil();
    let bounds = NEST_AREA * vec2(side, (nests / side).ceil());

    if env_number("HEADLESS", 0.0) != 0.0 {
        let ticks = env_number("TICKS", 600.0) as u64;
        let mut start = Instant::now();
        let mut world = colonies(Game::new("ants", 1, 1).seed(seed), bounds).run_headless(ticks, |ctx| {
            setup(ctx, bounds, ants, None);
            start = Instant::now();
        });
        let secs = start.elapsed().as_secs_f64();
        println!(
            "{ticks} ticks: {:.2} ms/tick ({:.0} ticks/s). {} ants, {} food delivered",
            secs * 1e3 / ticks as f64,
            ticks as f64 / secs,
            world.query::<&Ant>().count(),
            delivered(&mut world)
        );
        return;
    }

    colonies(Game::new("Crabby Engine: ants", 1280, 720).seed(seed), bounds)
        .system(controls)
        .system(camera_controls)
        .system(draw_world(bounds))
        .system(hud)
        .run(move |ctx| {
            let sprite = ctx.create_texture(3, 2, &[255; 3 * 2 * 4]);
            setup(ctx, bounds, ants, Some(sprite));
            // Start with the whole world in view.
            let fit = ctx.window_size() / bounds;
            ctx.camera.zoom = fit.x.min(fit.y);
            ctx.camera.look_at(bounds / 2.0);
            let mut next = 1.0;
            move |ctx: &mut Ctx| {
                if ctx.time() >= next {
                    next += 1.0;
                    let sim_ms: f32 = ctx.system_timings().iter().filter(|t| t.sim).map(|t| t.avg_ms).sum();
                    println!(
                        "ants: {}  delivered: {}  fps: {:.0}  sim: {sim_ms:.2} ms/frame  tick: {}",
                        ctx.world.query::<&Ant>().count(),
                        delivered(&mut ctx.world),
                        ctx.fps(),
                        ctx.sim_tick()
                    );
                }
            }
        });
}

pub fn get(&mut self, e: Entity) -> Option<<Q as QueryData>::Item<'_>>

The query’s item for one entity, or None if it’s dead or doesn’t match.