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.
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 registerLinkedEntityAttribute(attrID) 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.
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?