class abstract

Base class for the Query-like DSL, a fluent, chainable query language for filtering entities or components.

The Query-like language

Capitalized methods (e.g. With, Except, Where, Or, Not) are the vocabulary of an embedded query language. They are named in PascalCase to distinguish them from ordinary Dart methods and to read naturally in a chain:

query
  .With<Position>()
  .With<Velocity>()
  .Except<Frozen>()
  .DoForEach((e) => ...);

The query is lazily evaluated: nothing is resolved until a terminal operation such as First, DoForEach, Collect, etc. is called.

Groups and boolean logic

Internally a query is a list of QueryGroups. Within a group, all filters are ANDed. Or starts a new group; results across groups are ORed (entity passes if any group passes). Not starts a new negated group (entity passes if it would fail all filters in that group).

// entities that have Burning OR have Wet
query.With<Burning>().Or().With<Wet>().Collect();

// entities that are NOT frozen
query.Not().With<Frozen>().Collect();

Type parameters

T the concrete App subclass (used for component type resolution).
E the element type being queried (Entity or Comp).
Q the concrete query subclass, used so that every builder method returns the right type and chains remain fluent.

Inheritance

Object
ECSBase<T>
QueryComponentManagable

Mixed-in types

Implementers

Constructors

QueryComponentManagable(T app)

Properties

app → T: final
backend → UnhingedBackend: Shorthand for App.backend.
no setterinherited
Count → int: Query-like Returns the number of matching elements.
no setter
draw → Drawers<T>: Shorthand for App.draw.
no setterinherited
Exists → bool: Query-like Alias for IsNotEmpty. true if at least one element matches.
no setter
First → E: Query-like Returns the first matching element. Throws if none exist.
no setter
FirstOrNull → E?: Query-like Returns the first matching element, or null if the result set is empty.
no setter
hashCode → int: The hash code for this object.
no setterinherited
id → int: Per-type unique identifier, auto-assigned in the constructor.
no setterinherited
input → InputSystem<T>: Shorthand for App.input.
no setterinherited
isClonable → bool: Check this before calling clone: if (obj.isClonable) obj.clone();
no setterinherited
isClone ↔ bool: Whether this object is a clone of another.
getter/setter pairinherited
isCloned ↔ bool: Whether this object has been cloned at least once.
getter/setter pairinherited
isCloning ↔ bool: Whether this object is currently mid-clone.
getter/setter pairinherited
IsEmpty → bool: Query-like true if no elements match.
no setter
IsNotEmpty → bool: Query-like true if at least one element matches.
no setter
isOriginal → bool: Whether this object is an original (not a clone).
no setterinherited
Last → E: Query-like Returns the last matching element. Throws if none exist.
no setter
LastOrNull → E?: Query-like Returns the last matching element, or null if the result set is empty.
no setter
name ↔ String: Human-readable name, defaults to <runtimeType>_<id>.
getter/setter pairinherited
namedId → String: Per-type unique String identifier, auto-assigned in the constructor. Defaults to <runtimeType>_<id>.
no setterinherited
parent ↔ ECSBase<T>?: The parent object in the ECS tree, if any.
getter/setter pairinherited
queryableList → Iterable<E>: The default pool of elements to query when no explicit From source is provided. Implemented by concrete subclasses.
no setter
renderer → Renderer<T>: Shorthand for App.renderer.
no setterinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
scene → Scene<T>: Shorthand for App.currentScene.
no setterinherited
sceneBounds → Bounds: no setterinherited
sceneHeight → double: no setterinherited
sceneSize → Vector2D: no setterinherited
sceneWidth → double: no setterinherited
screenHeight → double: Shorthand for App's height.
no setterinherited
screenSize → Vector2D: Shorthand for App.screenSize.
no setterinherited
screenWidth → double: Shorthand for App's width.
no setterinherited
self → Q: This object cast to T.
no setterinherited
time → AppTime<T>: Shorthand for App.time.
no setterinherited

Methods

And([Q? other]) → Q: Query-like Merges all groups from other into this query (AND at the group level).
callback(void callback()) → void: inherited
clone<X extends E>([Cloner<T>? cloner]) → X: Produces a clone of this object.
inherited
cloneInto<X extends E>(X target, [Cloner<T>? cloner]) → X: inherited
Collect<A extends E>() → Iterable<A>: Query-like Returns all matching elements as a lazy Iterable.
createClone(Q newInstance, [Cloner<T>? cloner]) → Q: Override to customize how state is copied into newInstance.
inherited
createInstance() → Q: Override to provide a fresh uninitialized instance of this type.
inherited
DoAll<A extends E>(void fn(Iterable<A> entities)) → void: Query-like Passes the full result Iterable to fn.
DoFirst<A extends E>(void fn(A entity)) → void: Query-like Calls fn with the first matching element. Does nothing if the result set is empty.
DoFirstWith<C extends Comp<T>>(void fn(E entity, C c)) → void: Query-like Calls fn with the first matching element and its C component. Does nothing if the result set is empty.
DoFirstWith2<A extends Comp<T>, B extends Comp<T>>(void fn(E entity, A a, B b)) → void: Query-like Calls fn with the first matching element and its A and B components. Does nothing if the result set is empty.
DoFirstWith3<A extends Comp<T>, B extends Comp<T>, C extends Comp<T>>(void fn(E entity, A a, B b, C c)) → void: Query-like Calls fn with the first matching element and its A, B, and C components. Does nothing if the result set is empty.
DoForEach<A extends E>(void fn(A entity)) → void: Query-like Calls fn once for each matching element.
DoForEachWith<C extends Comp<T>>(void fn(E entity, C a)) → void: Query-like For each element that has C, calls fn with the element and its C instance. Implicitly adds a With<C> filter.
DoForEachWith2<A extends Comp<T>, B extends Comp<T>>(void fn(E entity, A a, B b)) → void: Query-like For each element that has both A and B, calls fn with the element and both component instances. Implicitly adds a With2<A, B> filter.
DoForEachWith3<A extends Comp<T>, B extends Comp<T>, C extends Comp<T>>(void fn(E entity, A a, B b, C c)) → void: Query-like For each element that has A, B, and C, calls fn with the element and all three component instances. Implicitly adds a With3<A, B, C> filter.
DoLast<A extends E>(void fn(A entity)) → void: Query-like Calls fn with the last matching element. Does nothing if the result set is empty.
DoLastWith<C extends Comp<T>>(void fn(E entity, C c)) → void: Query-like Calls fn with the last matching element and its C component. Does nothing if the result set is empty.
DoLastWith2<A extends Comp<T>, B extends Comp<T>>(void fn(E entity, A a, B b)) → void: Query-like Calls fn with the last matching element and its A and B components. Does nothing if the result set is empty.
DoLastWith3<A extends Comp<T>, B extends Comp<T>, C extends Comp<T>>(void fn(E entity, A a, B b, C c)) → void: Query-like Calls fn with the last matching element and its A, B, and C components. Does nothing if the result set is empty.
Except<C extends Comp<T>>() → Q: Query-like Excludes elements that have component C.
Except2<A extends Comp<T>, B extends Comp<T>>() → Q: Query-like Excludes elements that have either A or B.
Except3<A extends Comp<T>, B extends Comp<T>, C extends Comp<T>>() → Q: Query-like Excludes elements that have any of A, B, or C.
FirstAs<X extends E>() → X: Query-like Returns the first element of type X, skipping any non-matching elements. Throws a StateError if no element of type X exists.
FirstAsOrNull<X extends E>() → X?: Query-like Returns the first element of type X, skipping any non-matching elements, or null if none exists.
From(List<E> entities) → Q: Query-like Restricts the query to a specific list of entities instead of the default queryableList.
getAncestors() → Iterable<ECSBase<T>>: Returns every ancestor of this component, from immediate parent up to the root.
inherited
getClones() → Iterable<Q>: Returns all clones produced from this object.
inherited
getDepth() → int: Returns the depth/level in the hierarchy.
inherited
getParentAs<P extends ECSBase<T>>() → P?: Returns parent cast to P, or null if the cast would fail.
inherited
getPath() → List<ECSBase<T>>: Returns the path from the root down to this one, inclusive.
inherited
hasParentOf<P extends ECSBase<T>>() → bool: Whether parent is of type P.
inherited
IndexOf(E e) → int: Query-like Returns the index of e in the resolved result list, or -1 if not found.
LastAs<X extends E>() → X: Query-like Returns the last element of type X, skipping any non-matching elements. Throws a StateError if no element of type X exists.
LastAsOrNull<X extends E>() → X?: Query-like Returns the last element of type X, skipping any non-matching elements, or null if none exists.
listenOnAfterClone(void fn(Q copy, [Cloner<T>? cloner])) → Q: Registers fn as an after-clone listener.
inherited
listenOnBeforeClone(bool fn(Q copy, [Cloner<T>? cloner])) → Q: Registers fn as a before-clone listener.
inherited
listenOnClone(void fn(Q copy, [Cloner<T>? cloner])) → Q: Registers fn as a clone listener.
inherited
Map<X>(X toElement(E e)) → Iterable<X>: Query-like Projects matching elements using toElement.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
Not() → Q: Query-like Opens a new negated filter group.
On<C extends E>() → Q: Query-like Keeps only elements whose runtime type is C.
onAfterClone(Q copy, [Cloner<T>? cloner]) → void: Override to react after cloning has completed.
inherited
onBeforeClone(Q copy, [Cloner<T>? cloner]) → bool: Override to cancel cloning from within the class.
inherited
onClone(Q copy, [Cloner<T>? cloner]) → void: Override to react when cloning is about to complete.
inherited
onCloned(Q original) → void: Called on the copy after cloning completes, with a reference to original.
inherited
onSelf(void fn(Q original)) → Q: Calls fn with self and returns self, for fluent chaining.
inherited
Or([Q? other]) → Q: Query-like Opens a new filter group (OR semantics between groups).
run(Task<T> task) → void: inherited
task(Task<T> task) → void: inherited
toString() → String: A string representation of this object.
inherited
uniqKey(String key) → String: Returns a key namespaced to this object's namedId.
inherited
whenClone(Q fn(Q newInstance, [Cloner<T>? cloner])) → Q: Registers fn as the clone factory, replacing the default clone behavior.
inherited
whenCloned(Q fn(Q self, Q copy)) → Q: Registers fn to run after the clone is produced.
inherited
whenCreateInstance(Q fn(Q self)) → Q: Registers fn as the instance factory used during cloning.
inherited
Where(bool fn(E entity)) → Q: Query-like Keeps only elements for which fn returns true.
WhereType<X>() → Q: Query-like Keeps only elements matching given type X.
With<C extends Comp<T>>() → Q: Query-like Keeps only elements that have component C attached.
With2<A extends Comp<T>, B extends Comp<T>>() → Q: Query-like Keeps only elements that have both components A and B.
With2Where<A extends Comp<T>, B extends Comp<T>>(bool fn(E entity, A a, B b)) → Q: Query-like Keeps only elements that have both A and B and for which fn returns true.
With3<A extends Comp<T>, B extends Comp<T>, C extends Comp<T>>() → Q: Query-like Keeps only elements that have all three components A, B, and C.
With3Where<A extends Comp<T>, B extends Comp<T>, C extends Comp<T>>(bool fn(E entity, A a, B b, C c)) → Q: Query-like Keeps only elements that have all three of A, B, and C and for which fn returns true.
WithAny<A extends Comp<T>, B extends Comp<T>>() → Q: Query-like Keeps only elements that have at least one of A or B.
WithWhere<C extends Comp<T>>(bool fn(E entity, C c)) → Q: Query-like Keeps only elements that have C and for which fn returns true given the entity and its C instance.

Operators

operator ==(Object other) → bool: The equality operator.
inherited