Queries

FIND YOUR FOXES!

Queries are your lens into the World – fast, reactive views that match Entities by their Component signatures.

Each Query is a view into a World, representing a subset of its Entities. Queries are incredibly fast and update automatically whenever entities spawn or their component structure changes.

Quick Reference

Topic	Description
`World.Query()``	Get a QueryBuilder to add predicates like .Has<C>() and .Compile()
World.Query<...>()	QueryBuilder with pre-defined types for easy conversion via .Stream()

What is a Query?

A Query maintains a collection of all Archetypes it matches. When iterating Components or enumerating Entities, the Query does so for each matched Archetype in deterministic order.

(expand to see World diagram)

A World contains Entities and their Components, as well as their structure and Relations.

Three Main Purposes

1. Matching & Filtering Entities

Queries use Match Expressions to define which Entities they contain ("match"). A Query remains associated with a specific World and cannot bridge multiple Worlds.

// Match all entities with Position and Velocity components
var movers = world.Query<Position, Velocity>().Stream();

2. Processing Data (through Stream Views)

The most powerful feature of Queries is that they provide a Stream View that can run code on all matched Entities, providing mutable references to component data.

// Update all positions based on velocity
movers.For((ref pos, ref vel) =>
{
    pos.X += vel.X * deltaTime;
    pos.Y += vel.Y * deltaTime;
});

3. Bulk CRUD Operations

Queries expose methods to operate quickly on all matched entities – read more!

// Despawn all matched entities
query.Despawn();

// Or truncate to a specific size
query.Truncate(100, TruncateMode.KeepFirst);

Cleaning Up Queries

MEMORY MANAGEMENT

Queries have a modest memory footprint, but in Worlds with many fragmented Archetypes, the cost of Query update notifications can add up!

Call Query.Dispose() to de-register a query from its World and free its resources.

query.Dispose();