class QueryBuilder
QueryBuilder
()
|
Signature
constructor() Returns |
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
|
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 |
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 |
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
|
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
attrID:
Int
|
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
|
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 |
has
()
|
Type-safe extension for has() with two components.
Example:
Query.where { has<Transform, Mesh>() }
Signature
inline fun <A : ComponentBase, B : ComponentBase> has(): QueryNode |
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 |
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 |
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 |
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 |
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
version:
ULong
|