API reference
API reference
Select your platform
No SDKs available
No versions available

QueryBuilder Class

Modifiers: final
A class used to build a query tree.

Signature

class QueryBuilder

Constructors

QueryBuilder ()
Signature
constructor()

Functions

changed ( componentTypes )
Creates a query that checks if an entity has specific components that have changed in the last tick.
This is useful for reactive systems that need to respond to component changes. A component is considered "changed" if it was added, removed, or modified in the last tick.
Example:
// Find entities whose Transform component has changed
val query = Query.where { changed(Transform.id) }
// Find entities that have Grabbable and either Transform or Panel has changed in the last tick
val query = Query.where { has(Grabbable.id) and (changed(Transform.id) or changed(Panel.id)) }

Signature
fun changed(vararg componentTypes: Int): QueryNode
Parameters
componentTypes: Int
  The IDs of components to check for.
Returns
  A new query node that represents the "has" query.
changed ()
Type-safe extension for changed() using reified generics.
Creates a query that checks if a component has changed in the last tick.
Example:
// Instead of: Query.where { changed(Transform.id) }
Query.where { changed<Transform>() }

Signature
inline fun <T : ComponentBase> changed(): QueryNode
Returns
  A new query node that represents the "changed" query.
changed ()
Type-safe extension for changed() with two components.
Creates a query that checks if either component has changed.
Example:
Query.where { changed<Transform, Velocity>() }

Signature
inline fun <A : ComponentBase, B : ComponentBase> changed(): QueryNode
Returns
  A new query node that represents the "changed" query for both components.
changedSince ( componentType , version )
This is an advanced query and requires knowledge of the ordering of systems. It checks changes that occur within a tick and is especially useful if you want to remove one tick lag. At the same time, it introduces more complexity to manage, so please use it with caution.
Creates a query that checks if an entity has specific components that have changed since a particular datamodel version. This allows for more precise tracking of changes over time compared to the standard changed() query which only checks for changes in the last tick.
Example:
// Find entities whose Transform component has changed since the last tick
val query = Query.where { changedSince(Transform.id, lastUpdateVersion) }
lastUpdateVersion = EntityContext.getDataModel()!!.getLastUpdateVersion()

Signature
fun changedSince(componentType: Int, version: ULong): QueryNode
Parameters
componentType: Int
version: ULong
  The datamodel version to check against.
Returns
  A new query node that represents the "has" query.
childrenOf ( ent , attrID )
Creates a query node that finds all entities that are children of a specific parent entity.
This function is used to query for entities that have a reference to the specified parent entity through a specific entity attribute. It's particularly useful for hierarchical data structures where entities can have parent-child relationships.
The function works by finding all entities that have an entity attribute (specified by attrID) that references the given parent entity. These are considered "children" of the parent entity.
Example usage:
// Find all entities that reference parentEntity through the TransformParent.entityId attribute
val childEntities = Query.where { childrenOf(parentEntity, TransformParent.entityId) }.eval(dm)

Note: The DataModel must have the attribute registered as a linked entity attribute using <code>registerLinkedEntityAttribute(attrID)</code> before this query will work correctly.
Signature
fun childrenOf(ent: Entity, attrID: Int): QueryNode
Parameters
ent: Entity
  The entity to check for.
attrID: Int
  The attribute ID to check against for children
Returns
  A new query node that represents the "has" query.
has ( componentTypes )
Creates a query that checks if an entity has specific components.
This is a fundamental query operation that filters entities based on whether they have all of the specified components.
Example:
// Find entities with both Transform and Mesh components
val query = Query.where { has(Transform.id, Mesh.id) }

Signature
fun has(vararg componentTypes: Int): QueryNode
Parameters
componentTypes: Int
  The IDs of components to check for.
Returns
  A new query node that represents the "has" query.
has ()
Type-safe extension for has() using reified generics.
This allows you to write type-safe queries without needing to reference component IDs directly.
Example:
// Instead of: Query.where { has(Transform.id) }
Query.where { has<Transform>() }
// Combining with other queries:
Query.where { has<Transform>() and has<Mesh>() }

Signature
inline fun <T : ComponentBase> has(): QueryNode
Returns
  A new query node that represents the "has" query.
has ()
Type-safe extension for has() with two components.
Example:
Query.where { has<Transform, Mesh>() }

Signature
inline fun <A : ComponentBase, B : ComponentBase> has(): QueryNode
Returns
  A new query node that represents the "has" query for both components.
has ()
Type-safe extension for has() with three components.
Example:
Query.where { has<Transform, Mesh, Grabbable>() }

Signature
inline fun <A : ComponentBase, B : ComponentBase, C : ComponentBase> has(): QueryNode
Returns
  A new query node that represents the "has" query for all three components.
has ()
Type-safe extension for has() with four components.
Example:
Query.where { has<Transform, Mesh, Grabbable, Physics>() }

Signature
inline fun <A : ComponentBase, B : ComponentBase, C : ComponentBase, D : ComponentBase> has(): QueryNode
Returns
  A new query node that represents the "has" query for all four components.
hasChanged ()
Convenience function combining has and changed for a common pattern.
Matches entities that have the component AND it changed in the last tick. This is equivalent to <code>has<T>() and changed<T>()</code>.
Example:
// These are equivalent:
Query.where { hasChanged<Transform>() }
Query.where { has<Transform>() and changed<Transform>() }

Signature
inline fun <T : ComponentBase> hasChanged(): QueryNode
Returns
  A new query node representing <code>has<T>() and changed<T>()</code>.
hasChanged ()
Convenience function combining has and changed for two components.
Matches entities that have both components AND at least one changed.
Example:
Query.where { hasChanged<Transform, Velocity>() }

Signature
inline fun <A : ComponentBase, B : ComponentBase> hasChanged(): QueryNode
Returns
  A new query node representing the combined has/changed query.
hasChangedSince ( componentTypes , version )
Creates a query that checks if an entity has ALL specified components AND at least one of them has changed since a particular datamodel version. This is more efficient than constructing an equivalent OR query with multiple changedSince and has clauses.
This is an advanced query useful for incremental update patterns where you want to find entities that match a component set AND have had some change to any tracked component.
Example:
// Find entities with Transform, Mesh, and Grabbable where at least one changed since version
val query = Query.where { hasChangedSince(Transform.id, Mesh.id, Grabbable.id, version = lastVersion) }

This is equivalent to but more efficient than:
(changedSince(Transform.id, v) and has(Mesh.id, Grabbable.id)) or
(changedSince(Mesh.id, v) and has(Transform.id, Grabbable.id)) or
(changedSince(Grabbable.id, v) and has(Transform.id, Mesh.id))

Signature
fun hasChangedSince(vararg componentTypes: Int, version: ULong): QueryNode
Parameters
componentTypes: Int
  The IDs of components to check for (must have all, at least one changed).
version: ULong
  The datamodel version to check against.
Returns
  A new query node that represents the "hasChangedSince" query.
Did you find this page helpful?