Use the DSL builder pattern with Query.where { ... } to create queries. The query DSL allows you to specify conditions on entities, such as having specific components or having changed components. You can also combine conditions with logical operators (and, or) to create complex queries.

Example - Find all entities with a specific component:

val entities = Query.where { has(Transform.id) }.eval()

Example - Find entities with multiple components:

val entities = Query.where { has(Transform.id, Mesh.id) }.eval()

Example - Find entities with components that have changed in the last tick:

val entities = Query.where { changed(Transform.id) }.eval()

Example - Combining queries with logical operators:

val entities = Query.where { (has(Transform.id) and has(Mesh.id)) or has(Panel.id) }.eval()

Example - Using filters with queries:

val entities = Query.where { has(TestComponent.id) }
                    .filter { by(TestComponent.intVarData).isEqualTo(1) }
                    .eval()

Example - Using sort with queries:

val entities = Query.where { has(TestComponent.id) }
                    .sort {
                      with {
                        by(TestComponent.intVarData)
                      }
                    }.eval()

Signature

class Query

Properties

prev_ : Query? [Get][Set]	Signature var prev_: Query?
query_ : IntArray [Get][Set]	Signature var query_: IntArray

Functions

any ()	Checks if any entity matches the query. Example: if (Query.where { has<Player>() }.any()) { // player exists } Signature fun any(): Boolean Returns Boolean True if at least one entity matches.
build ()	Evaluates the query for a specific DataModel and returns the a built query. Signature fun build(): BuiltQuery Returns BuiltQuery A BuiltQuery that can be used later.
count ()	Counts the number of entities matching the query. Example: val enemyCount = Query.where { has<Enemy>() }.count() Signature fun count(): Int Returns Int The number of matching entities.
eval ()	Evaluates the query and returns a sequence of entities that match the query criteria. This method executes the query against the current DataModel and returns matching entities. The result is a lazy sequence, so operations on it are only performed as needed. Example: // Find all entities with a Transform component and iterate through them Query.where { has(Transform.id) } .eval() .forEach { entity -> // Process each entity val transform = entity.getComponent<Transform>() // ... } Signature fun eval(): Sequence<Entity> Returns Sequence<Entity> A sequence of entities that match the query criteria.
eval ( dm )	Evaluates the query against a specific DataModel and returns matching entities. In a Spatial app, there is only one DataModel, so this method is rarely used. Use eval() instead to evaluate the query against the current DataModel. Example: // Evaluate a query against a specific DataModel val customDataModel = DataModel.create() val entities = Query.where { has(Transform.id) }.eval(customDataModel) Signature fun eval(dm: DataModel): Sequence<Entity> Parameters dm: DataModel The DataModel to evaluate the query against. Returns Sequence<Entity> A sequence of entities that match the query criteria.
filter ( initializer )	Specifies the filter criteria for the query. Example: // Find all entities with a TestComponent component and filter by the intVarData field val entities = Query.where { has(TestComponent.id) } .filter { by(TestComponent.intVarData).isEqualTo(1) } .eval() Signature fun filter(initializer: FilterBuilder.() -> Unit): Query Parameters initializer: Function1 A receiver function of the FilterBuilder. Returns Query The Query object.
first ()	Finds the first entity matching the query and returns it with its component. Example: val result = Query.where { has<Player>() }.first<Player>() if (result != null) { val (entity, player) = result // use entity and player } Signature inline fun <T : ComponentBase> first(): Pair<Entity, T>? Returns Pair<Entity, T>? A pair of the entity and component, or null if no match.
first ()	Finds the first entity matching the query and returns it with two components. Signature inline fun <A : ComponentBase, B : ComponentBase> first(): Triple<Entity, A, B>? Returns Triple<Entity, A, B>? A triple of the entity and components, or null if no match.
forEach ( action )	Evaluates the query and iterates over each entity with its component. This is a convenience method that combines query evaluation with component access, eliminating boilerplate code. Example: // Instead of: Query.where { has<Transform>() }.eval().forEach { entity -> val transform = entity.getComponent<Transform>() // process transform } // You can write: Query.where { has<Transform>() }.forEach<Transform> { entity, transform -> // process transform directly } Signature inline fun <T : ComponentBase> forEach(action: (Entity, T) -> Unit) Parameters action: Function2 The action to perform on each entity and its component.
forEach ( action )	Evaluates the query and iterates over each entity with two components. Example: Query.where { has<Transform, Velocity>() }.forEach<Transform, Velocity> { entity, t, v -> t.transform = t.transform.copy(t = t.transform.t + v.direction) entity.setComponent(t) } Signature inline fun <A : ComponentBase, B : ComponentBase> forEach(action: (Entity, A, B) -> Unit) Parameters action: Function3 The action to perform on each entity and its components.
forEach ( action )	Evaluates the query and iterates over each entity with three components. Signature inline fun <A : ComponentBase, B : ComponentBase, C : ComponentBase> forEach(action: (Entity, A, B, C) -> Unit) Parameters action: Function4 The action to perform on each entity and its components.
map ( transform )	Evaluates the query and maps each entity with its component to a result. Example: val positions = Query.where { has<Transform>() } .map<Transform, Vector3> { entity, transform -> transform.transform.t } Signature inline fun <T : ComponentBase, R> map(crossinline transform: (Entity, T) -> R): List<R> Parameters transform: Function2 The transformation to apply to each entity and component. Returns List A list of transformed results.
map ( transform )	Evaluates the query and maps each entity with two components to a result. Signature inline fun <A : ComponentBase, B : ComponentBase, R> map(crossinline transform: (Entity, A, B) -> R): List<R> Parameters transform: Function3 The transformation to apply. Returns List A list of transformed results.
none ()	Checks if no entity matches the query. Example: if (Query.where { has<Enemy>() }.none()) { // no enemies - level complete! } Signature fun none(): Boolean Returns Boolean True if no entities match.
sort ( initializer )	Specifies the sort order for the query. Example: // Find all entities with a TestComponent component and sort by the intVarData field val entities = Query.where { has(TestComponent.id) } .sort { with { by(TestComponent.intVarData) } } .eval() Signature fun sort(initializer: SortBuilder.() -> Unit): Query Parameters initializer: Function1 A receiver function of the SortBuilder. Returns Query The Query object.

Companion Object

Companion Object Functions

eval ( preBuiltQuery )	Evaluates a pre-built query and returns a sequence of entities that match the query. Signature fun eval(preBuiltQuery: BuiltQuery): Sequence<Entity> Parameters preBuiltQuery: BuiltQuery The pre-built query to evaluate. Returns Sequence<Entity> A sequence of entities that match the query.
eval ( dm , preBuiltQuery )	Evaluates a pre-built query on a specific DataModel and returns a sequence of entities that match the query. Signature fun eval(dm: DataModel, preBuiltQuery: BuiltQuery): Sequence<Entity> Parameters dm: DataModel The DataModel to evaluate the query against. preBuiltQuery: BuiltQuery The pre-built query to evaluate. Returns Sequence<Entity> A sequence of entities that match the query.
where ( initializer )	DSL for building queries. The DSL provides an interface for building complex queries with logical operations. Example: // Find entities that have both Transform and Mesh components val query = Query.where { has(Transform.id) and has(Mesh.id) } // Find entities that have either changed Transform or changed Mesh components val query = Query.where { changed(Transform.id) or changed(Mesh.id) } // Find entities that have a Controller component and are local val query = Query.where { has(Controller.id) } .filter { isLocal() } .eval() // Find entities with a specific component that have changed in the last tick val query = Query.where { has(Grabbable.id) and changed(Transform.id) } Signature fun where(initializer: QueryBuilder.() -> Unit): Query Parameters initializer: Function1 DSL receiver function that builds the query Returns Query Query object ready for evaluation or further refinement