EntityGroup<T extends App<T>, E extends Entity<T>> class

A logical group of related Entity objects managed as a single unit.

An EntityGroup is itself an Entity, so it participates in the scene lifecycle normally. It additionally maintains an ordered entities list whose members receive update, draw, and event calls immediately after the group itself.

Transform management

When an entity is added via addEntity, _ensureLocalPosition reconciles whichever transform style the entity was given:

  • World transform only (CTransform) => converted to a CLocalTransform offset relative to the group's world position.
  • Local transform only (CLocalTransform) => a matching CTransform is created at the correct world position.
  • Both => left untouched; the caller is assumed to know what they're doing.
  • Neither => left as-is; the propagation system will skip it.
Inheritance
Mixed-in types
Implementers

Constructors

EntityGroup(T app)

Properties

app → T
finalinherited
backend → UnhingedBackend
Shorthand for App.backend.
no setterinherited
bounds → Bounds?
An axis-aligned bounding box derived from the entity's collider or visual component, or null if neither is present.
no setteroverride
collider → CCollider<T>?
no setterinherited
draw → Drawers<T>
Shorthand for App.draw.
no setterinherited
entity → Entity<T>
no setterinherited
eventHistory → List<Event<T>>
no setterinherited
eventHistoryRetention → double?
How long (in sim-scaled seconds) to retain events before pruning. Null = keep forever.
no setterinherited
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
isActive → bool
Whether this object is currently active.
no setterinherited
isAdded → bool
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
isDisabled → bool
Whether this object is currently disabled.
no setterinherited
isOriginal → bool
Whether this object is an original (not a clone).
no setterinherited
isRemoved ↔ bool
Whether this object has been removed.
getter/setter pairinherited
localPosition → Vector2D
The entity's position relative to its parent.
no setterinherited
localTransform → CLocalTransform<T>?
no setterinherited
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
persistentId ↔ String
getter/setter pairinherited
persistentTypeId → String
no setteroverride
physicsBody → CPhysicsBody<T>?
no setterinherited
populateDefaults ↔ bool
getter/setter pairinherited
QueryComp → QueryEntityComponent<T>
Returns a fresh QueryEntityComponent scoped to this entity's direct components.
no setterinherited
QueryCompDeep → QueryEntityComponentDeep<T>
Returns a fresh QueryEntityComponentDeep that searches all components recursively, including those on child components.
no setterinherited
QueryEntity → QueryEntities<T, EntityGroup<T, E>>
Returns a fresh QueryEntities scoped to this entity group.
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 → EntityGroup<T, E>
no setterinherited
time → AppTime<T>
Shorthand for App.time.
no setterinherited
transform → CTransform<T>?
no setterinherited
velocity → CVelocity<T>?
no setterinherited
worldPosition → Vector2D
The entity's position in scene space.
no setterinherited

Methods

addComp<C extends Comp<T>>(C component) → Entity<T>
Adds component as a new top-level component.
inherited
addCompIfNotExists<C extends Comp<T>>(C component) → Entity<T>
Adds component only if no top-level component of type C already exists.
inherited
addEntity(E entity) → bool
Registers entity and runs the full add lifecycle.
override
bookmarkState(String name) → AnyEntitySnapshot<T>
inherited
callback(void callback()) → void
inherited
captureSnapshot() → AnyEntityGroupSnapshot<T>
override
captureSnapshotAs<X extends S>() → X
inherited
clearEventHistory() → void
Clears history of recorded events.
inherited
clone<X extends E>([EntityCloner<T>? cloner]) → X
Produces a clone of this object.
inherited
cloneInto<X extends E>(X target, [EntityCloner<T>? cloner]) → X
inherited
containsComp<C extends Comp<T>>() → bool
Whether a component of type C exists anywhere in this subtree.
inherited
countAllComps<C extends Comp<T>>() → int
Recursively counts every component of type C in this subtree.
inherited
createClone(Entity<T> newInstance, [EntityCloner<T>? cloner]) → Entity<T>
Override to customize how state is copied into newInstance.
inherited
createInstance() → EntityGroup<T, E>
Override to provide a fresh uninitialized instance of this type.
override
createSnapshot() → AnyEntityGroupSnapshot<T>
override
decVar<V extends num>(VarKey<V> key, [V? amount]) → V
inherited
disableComp<C extends Comp<T>>() → Entity<T>
Deactivates every top-level component of type C.
inherited
disableComps() → Entity<T>
Deactivates all top-level components (not nested).
inherited
disableDraw() → void
Prevents any render loop from drawing this entity.
inherited
disableEverything() → Entity<T>
Recursively deactivates every component, including nested ones.
inherited
disableSceneLevelDraw() → void
Prevents the scene's render loop from drawing this entity.
inherited
dispatch(Event<T> event, {EventScope scope = .local}) → void
inherited
emit(Event<T> event, {EventScope scope = .local}) → void
inherited
enableComp<C extends Comp<T>>() → Entity<T>
Activates every top-level component of type C.
inherited
enableComps() → Entity<T>
Activates all top-level components.
inherited
enableEverything() → Entity<T>
Recursively activates every component, including nested ones.
inherited
findAllComps<C extends Comp<T>>() → Iterable<C>
Recursively finds every component of type C in this subtree.
inherited
findAllCompsWith<C extends Comp<T>>() → Iterable<Comp<T>>
Recursively finds every component that itself contains a nested component of type C (i.e. returns the containing components, not the matches themselves).
inherited
findComp<C extends Comp<T>>() → C?
Recursively finds the first component of type C in this subtree.
inherited
findCompInChildren<C extends Comp<T>>() → C?
Finds the first direct child component of type C (non-recursive).
inherited
findCompInParent<C extends Comp<T>>() → C?
Walks up the hierarchy and returns the nearest ancestor component of type C, if any.
inherited
findCompNearest<C extends Comp<T>>() → C?
Finds the closest component of type C via breadth-first search.
inherited
findCompSiblings<C extends Comp<T>>() → Iterable<C>
Returns sibling components at the same level as this one.
inherited
findCompWhere<C extends Comp<T>>(bool predicate(C)) → C?
Recursively finds the first component of type C satisfying predicate.
inherited
forEachCompRecursive<C extends Comp<T>>(void callback(C)) → void
Recursively invokes callback on every component of type C in this subtree.
inherited
get<C extends Comp<T>>() → C?
Returns the first top-level component matching type C, or null.
inherited
getAll<C extends Comp<T>>() → List<C>
Returns all top-level components matching type C.
inherited
getAncestors() → Iterable<ECSBase<T>>
Returns every ancestor of this component, from immediate parent up to the root.
inherited
getClones() → Iterable<Entity<T>>
Returns all clones produced from this object.
inherited
getCompLeaves() → Iterable<Comp<T>>
Returns every leaf component in this subtree (components with no children).
inherited
getComponents() → Iterable<Comp<T>>
Returns the top-level components attached directly to this entity/component (does not recurse into nested components).
inherited
getDepth() → int
Returns the depth/level in the hierarchy.
inherited
getEntities() → Set<E>
Returns all entities currently registered.
inherited
getEverything() → List<Comp<T>>
Recursively collects every component in this subtree, including nested ones.
inherited
getOrSetVar<V>(VarKey<V> key, V fallback) → V
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
getPersistableData({bool force = false}) → MapData
override
getRecordedEvents({double? duration, ECSBase<T>? origin, bool filter(Event<T> event)?}) → List<Event<T>>
Events dispatched within the last duration sim-scaled seconds, optionally filtered to a specific origin.
inherited
getVar<V>(VarKey<V> key) → V?
inherited
getVarSafe<V>(VarKey<V> key, V fallback) → V
inherited
has<C extends Comp<T>>() → bool
Whether a top-level component of type C exists.
inherited
has2<A extends Comp<T>, B extends Comp<T>>() → bool
Whether top-level components of BOTH type A and type B exist.
inherited
has2ByType(Type a, Type b) → bool
Whether top-level components whose runtimeType matches both a and b exist.
inherited
has3<A extends Comp<T>, B extends Comp<T>, C extends Comp<T>>() → bool
Whether top-level components of types A, B, and C all exist.
inherited
has3ByType(Type a, Type b, Type c) → bool
Whether top-level components whose runtimeType matches a, b, and c all exist.
inherited
hasAny<A extends Comp<T>, B extends Comp<T>>() → bool
Whether a top-level component of type A OR type B exists.
inherited
hasByType(Type type) → bool
Whether a top-level component whose runtimeType == type exists.
inherited
hasParentOf<P extends ECSBase<T>>() → bool
Whether parent is of type P.
inherited
hasVar(VarKey key) → bool
inherited
incVar<V extends num>(VarKey<V> key, [V? amount]) → V
inherited
listenHandleInput(void fn(Entity<T> self)) → Entity<T>
Registers fn to be called during the input handling phase.
inherited
listenOnActivate(void fn(Entity<T> self)) → Entity<T>
Registers fn to be called whenever the active state changes.
inherited
listenOnAdd(void fn(Entity<T> self, ECSBase<T> parent)) → Entity<T>
Registers fn as an add listener.
inherited
listenOnAfterAdd(void fn(Entity<T> self, ECSBase<T> parent)) → Entity<T>
Registers fn as an after-add listener.
inherited
listenOnAfterClone(void fn(Entity<T> copy, [EntityCloner<T>? cloner])) → Entity<T>
Registers fn as an after-clone listener.
inherited
listenOnAfterCompAdd(void fn(Entity<T> self, Comp<T> component)) → Entity<T>
inherited
listenOnAfterCompClone(void fn(Entity<T> self, Comp<T> component)) → Entity<T>
inherited
listenOnAfterCompRemove(void fn(Entity<T> self, Comp<T> component)) → Entity<T>
inherited
listenOnAfterEntityAdd(void fn(EntityGroup<T, E> self, E entity)) → EntityGroup<T, E>
Registers fn as an after-add listener.
inherited
listenOnAfterEntityRemove(void fn(EntityGroup<T, E> self, E entity)) → EntityGroup<T, E>
Registers fn as an after-remove listener.
inherited
listenOnAfterRemove(void fn(Entity<T> self)) → Entity<T>
Registers fn as an after-remove listener.
inherited
listenOnBeforeAdd(bool fn(Entity<T> self, ECSBase<T> parent)) → Entity<T>
Registers fn as a before-add listener.
inherited
listenOnBeforeClone(bool fn(Entity<T> copy, [EntityCloner<T>? cloner])) → Entity<T>
Registers fn as a before-clone listener.
inherited
listenOnBeforeCompAdd(bool fn(Entity<T> self, Comp<T> component)) → Entity<T>
inherited
listenOnBeforeCompClone(bool fn(Entity<T> self, Comp<T> component)) → Entity<T>
inherited
listenOnBeforeCompRemove(bool fn(Entity<T> self, Comp<T> component)) → Entity<T>
inherited
listenOnBeforeEntityAdd(bool fn(EntityGroup<T, E> self, E entity)) → EntityGroup<T, E>
Registers fn as a before-add listener.
inherited
listenOnBeforeEntityRemove(bool fn(EntityGroup<T, E> self, E entity)) → EntityGroup<T, E>
Registers fn as a before-remove listener.
inherited
listenOnBeforeEvent(bool fn(Entity<T> self, Event<T> event)) → Entity<T>
Registers fn as a before-event listener.
inherited
listenOnBeforeEventRecorded(bool fn(Entity<T> self, Event<T> event)) → Entity<T>
Registers fn as a before-event-record listener.
inherited
listenOnBeforeRemove(bool fn(Entity<T> self)) → Entity<T>
Registers fn as a before-remove listener.
inherited
listenOnBeforeStorePersistable(bool fn(Entity<T> self)) → Entity<T>
Registers fn as a before-persistence listener.
inherited
listenOnClone(void fn(Entity<T> copy, [EntityCloner<T>? cloner])) → Entity<T>
Registers fn as a clone listener.
inherited
listenOnCompAdd(void fn(Entity<T> self, Comp<T> component)) → Entity<T>
inherited
listenOnCompClone(void fn(Entity<T> self, Comp<T> component)) → Entity<T>
inherited
listenOnCompRemove(void fn(Entity<T> self, Comp<T> component)) → Entity<T>
inherited
listenOnDispose(void fn(Entity<T> self)) → Entity<T>
Registers fn to be called at the disposal of the owned ECS object.
inherited
listenOnDraw(void fn(Entity<T> self, double dt)) → Entity<T>
Registers fn to be called during the draw phase each frame.
inherited
listenOnEntityAdd(void fn(EntityGroup<T, E> self, E entity)) → EntityGroup<T, E>
Registers fn as an add listener.
inherited
listenOnEntityRemove(void fn(EntityGroup<T, E> self, E entity)) → EntityGroup<T, E>
Registers fn as a remove listener.
inherited
listenOnEvent(void fn(Entity<T> self, Event<T> event)) → Entity<T>
Registers fn to be called for every incoming event.
inherited
listenOnEventRecorded(void fn(Entity<T> self, Event<T> event)) → Entity<T>
Registers fn to be called for every event recorded.
inherited
listenOnRemove(void fn(Entity<T> self)) → Entity<T>
Registers fn as a remove listener.
inherited
listenOnStorePersistable(MapData fn(Entity<T> self, MapData data)) → Entity<T>
Registers fn as an store persistable listener.
inherited
listenOnUpdate(void fn(Entity<T> self, double dt)) → Entity<T>
Registers fn to be called during the update phase each frame.
inherited
mergeCompsInto<X extends IsAnyComponentManagable<T>>(X into, {Cloner<T>? cloner, bool replaceComponents = true}) → void
inherited
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
on<C extends Comp<T>>(void callback(C)) → Entity<T>
Invokes callback with the first top-level component matching type C, if one exists.
inherited
on2<A extends Comp<T>, B extends Comp<T>>(void callback(A, B)) → Entity<T>
Invokes callback with the first top-level components matching types A and B, if both exist.
inherited
on3<A extends Comp<T>, B extends Comp<T>, C extends Comp<T>>(void callback(A, B, C)) → Entity<T>
Invokes callback with the first top-level components matching types A, B, and C, if all three exist.
inherited
onActivate() → void
Override to react when the active state changes.
inherited
onAdd(ECSBase<T> parent) → void
Override to react when the add is about to complete.
inherited
onAfterAdd(ECSBase<T> parent) → void
Override to react after the add has completed.
inherited
onAfterClone(Entity<T> copy, [EntityCloner<T>? cloner]) → void
Override to react after cloning has completed.
inherited
onAfterCompAdd(Comp<T> component) → void
inherited
onAfterCompClone(Comp<T> copy) → void
inherited
onAfterCompRemove(Comp<T> component) → void
inherited
onAfterEntityAdd(E entity) → void
Override to react after an entity add has completed.
inherited
onAfterEntityRemove(E entity) → void
Override to react after an entity remove has completed.
inherited
onAfterRemove() → void
Override to react after removal has completed.
inherited
onAll<C extends Comp<T>>(void callback(List<C> components)) → Entity<T>
Invokes callback with every top-level component matching type C.
inherited
onBeforeAdd(ECSBase<T> parent) → bool
Override to cancel the add from within the class.
inherited
onBeforeClone(Entity<T> copy, [EntityCloner<T>? cloner]) → bool
Override to cancel cloning from within the class.
inherited
onBeforeCompAdd(Comp<T> component) → bool
inherited
onBeforeCompClone(Comp<T> copy) → bool
inherited
onBeforeCompRemove(Comp<T> component) → bool
inherited
onBeforeEntityAdd(E entity) → bool
Override to cancel an entity add from within the class.
inherited
onBeforeEntityRemove(E entity) → bool
Override to cancel an entity remove from within the class.
inherited
onBeforeEvent(Event<T> event) → bool
Override to cancel an event handling from within the class.
inherited
onBeforeEventRecorded(Event<T> event) → bool
Override to cancel an event handling from within the class.
inherited
onBeforeRemove() → bool
Override to cancel removal from within the class.
inherited
onBeforeStorePersistable() → bool
Override to cancel the persistence from within the class.
inherited
onBounds(void fn(Bounds bounds)) → Entity<T>
inherited
onClone(Entity<T> copy, [EntityCloner<T>? cloner]) → void
Override to react when cloning is about to complete.
inherited
onCloned(Entity<T> original) → void
Called on the copy after cloning completes, with a reference to original.
inherited
onCollider(void fn(CCollider<T> v)) → Entity<T>
inherited
onCompAdd(Comp<T> component) → void
inherited
onCompClone(Comp<T> copy) → void
inherited
onCompRemove(Comp<T> component) → void
inherited
onDispose() → void
Override to react at the disposal.
inherited
onDraw(double dt) → void
Override to react during the draw phase each frame.
inherited
onEntityAdd(E entity) → void
Override to react when an entity add is about to complete.
inherited
onEntityRemove(E entity) → void
Override to react when an entity remove is about to complete.
inherited
onEvent(Event<T> event) → void
Override to handle incoming events within the class.
inherited
onEventRecorded(Event<T> event) → void
Override to handle incoming events within the class.
inherited
onInput() → void
Override to handle input within the class.
inherited
onLocalTransform(void fn(CLocalTransform<T> v)) → Entity<T>
inherited
onPhysicsBody(void fn(CPhysicsBody<T> v)) → Entity<T>
inherited
onRemove() → void
Override to react when removal is about to complete.
inherited
onRestorePersistableData(MapTraversable data, {String? id}) → void
Override to react during the restoration of persistable data.
inherited
onSelf(void fn(Entity<T> self)) → Entity<T>
Calls fn with self and returns self, for fluent chaining.
inherited
onStorePersistable(MapData data) → MapData
Override to react when the persistence is about to complete.
inherited
onTransform(void fn(CTransform<T> t)) → Entity<T>
inherited
onUpdate(double dt) → void
Override to react during the update phase each frame.
inherited
onVelocity(void fn(CVelocity<T> v)) → Entity<T>
inherited
persistAutoLoad({int? slot}) → void
inherited
persistAutoSave({required double interval, required int slots}) → AnyEntitySnapshot<T>?
inherited
removeComp<C extends Comp<T>>() → Entity<T>
Removes the first top-level component matching type C.
inherited
removeCompByType(Type type) → Entity<T>
Removes the first top-level component whose runtimeType == type.
inherited
removeCompExact(Comp<T> component) → Entity<T>
Removes the exact component.
inherited
removeCompNested<C extends Comp<T>>() → void
Recursively removes every component of type C from this subtree.
inherited
removeComps<C extends Comp<T>>() → Entity<T>
Removes all top-level components matching type C.
inherited
removeEntity(E entity) → bool
Unregisters entity and runs the full remove lifecycle.
inherited
removeEverything() → Entity<T>
Removes every top-level component.
inherited
removeThis() → Entity<T>
Schedules removal of this entity from its scene via the callback queue.
inherited
replaceComp(Comp<T> component) → Entity<T>
Replaces the first top-level component whose runtimeType == component.runtimeType with component.
inherited
replayRecordedEvents({double? fromTime, ECSBase<T>? origin, bool filter(Event<T> event)?}) → void
Re-dispatches events from fromTime sim-scaled seconds ago to now.
inherited
restoreBookmarkedState(String name, {SnapshotMissingPolicy onMissing = .skip, SnapshotExtraPolicy onExtra = .keep}) → void
inherited
restorePersistableData(MapTraversable data, {String? id}) → void
override
restoreSnapshot(covariant AnyEntityGroupSnapshot<T> snapshot) → void
override
run(Task<T> task) → void
inherited
setActive(bool active) → Entity<T>
Sets the active state to active and fires the activation hook.
inherited
setVar<V>(VarKey<V> key, V value) → Entity<T>
inherited
storePersistable() → MapData?
inherited
swapComp<A extends Comp<T>>(Comp<T> newC) → Entity<T>
Replaces the first top-level component of type A with newC. No-op if no component of type A exists.
inherited
swapComps<A extends Comp<T>>(Comp<T> newC) → Entity<T>
Removes all the top-level components of type A and adds newC. No-op if no component of type A exists.
inherited
task(Task<T> task) → void
inherited
toggleActive() → Entity<T>
Toggles the active state and fires the activation hook.
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(Entity<T> fn(Entity<T> newInstance, [EntityCloner<T>? cloner])) → Entity<T>
Registers fn as the clone factory, replacing the default clone behavior.
inherited
whenCloned(Entity<T> fn(Entity<T> self, Entity<T> copy)) → Entity<T>
Registers fn to run after the clone is produced.
inherited
whenCreateInstance(Entity<T> fn(Entity<T> self)) → Entity<T>
Registers fn as the instance factory used during cloning.
inherited

Operators

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

Constants

typeId → const String