Query

A World contains entities which have components. The World is queryable and can be used to get entities with a specific set of components.

Methods

cached

Returns a cached version of the query. This is useful if you want to create a query that you can iterate multiple times.

function Query:cached(): Query -- Returns the cached Query

Example:

luau

local lerps = world:query(Lerp):cached() -- Ensure that you cache this outside a system so you do not create a new cache for a query every frame

local function system(dt)
	for entity, lerp in lerps do
		-- Do something
	end
end

typescript

const lerps = world.query(Lerp).cached()

function system(dt) {
	for (const [entity, lerp] of lerps) {
		// Do something
	}
}

with

Adds components (IDs) to query with, but will not use their data. This is useful for Tags or generally just data you do not care for.

function Query:with(
    ...: Entity -- The IDs to query with
): Query

Example:

luau

for id, position in world:query(Position):with(Velocity) do
    -- Do something
end

typescript

for (const [id, position] of world.query(Position).with(Velocity)) {
	// Do something
}

INFO

Put the IDs inside of world:query() instead if you need the data.

without

Removes entities with the provided components from the query.

function Query:without(
    ...: Entity -- The IDs to filter against.
): Query -- Returns the Query

Example:

luau

for entity, position in world:query(Position):without(Velocity) do
    -- Do something
end

typescript

for (const [entity, position] of world.query(Position).without(Velocity)) {
	// Do something
}

archetypes

Returns the matching archetypes of the query.

function Query:archetypes(): { Archetype }

Example:

for i, archetype in world:query(Position, Velocity):archetypes() do
    local field = archetype.columns_map
    local positions = field[Position]
    local velocities = field[Velocity]

    for row, entity in archetype.entities do
        local position = positions[row]
        local velocity = velocities[row]
        -- Do something
    end
end

INFO

This function is meant for people who want to really customize their query behaviour at the archetype-level

iter

In most cases, you can iterate over queries directly using for entity, ... in query do. The :iter() method is mainly useful if you are on the old solver, to get types for the returned values.

function Query:iter(): () -> (Entity, ...)

Example:

luau

local query = world:query(Position, Velocity)

-- Direct iteration (recommended)
for entity, position, velocity in query do
    -- Process entity
end

-- Using explicit iterator (when needed for the old solver)
local iterator = query:iter()
for entity, position, velocity in iterator do
    -- Process entity
end