Entity<T extends App<T>> class

A single actor in the ECS, the fundamental building block of a Scene.

An Entity owns a set of Comp components and participates in the full ECS lifecycle: input handling, update, draw, and event propagation. All three passes (input → update → draw) are forwarded to every attached component before the entity's own override hooks are called.

Lifecycle order (per frame)

_doHandleInput()  →  components → onInput()
_doUpdate(dt)     →  components → listeners → onUpdate(dt)
_doDraw(dt)       →  components → listeners → onDraw(dt)

Disabled entities skip all three passes entirely.

Querying components

Two Query-like entry points are available:

entity.Query      // direct components only
entity.QueryDeep  // all components, including those on child components

Position

worldPosition and localPosition are derived from whichever transform component is present (CTransform for world-space, CLocalTransform for parent-relative). bounds is derived from the first collider or visual component found.

Removal

Call removeThis to schedule removal via the scene's callback queue rather than removing the entity mid-iteration.

Inheritance

Object
ECSBase<T>
Entity

Mixed-in types

Self<Entity<T>>
HasSceneAccess<T>
HasEntityAccess<T>
HasVars<T, Entity<T>>
IsActivatable<T, Entity<T>>
IsAddable<T, Entity<T>>
IsClonable<T, Entity<T>, EntityCloner<T>>
IsDisposable<T, Entity<T>>
IsDrawable<T, Entity<T>>
IsEventEmittable<T, Entity<T>>
IsEventHistoryHolder<T, Entity<T>>
IsInputHandleable<Entity<T>>
IsRemovable<T, Entity<T>>
IsUpdatable<T, Entity<T>>
IsComponentManagable<T, Entity<T>>
IsStateHolder<T, Entity<T>, AnyEntitySnapshot<T>>
IsPersistable<T, Entity<T>, AnyEntitySnapshot<T>>

Implementers

EntityGroup

Constructors

Entity(T app, {bool populateDefaults = true})

Properties

app → T: final
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 setter
collider → CCollider<T>?: no setter
draw → Drawers<T>: Shorthand for App.draw.
no setterinherited
entity → Entity<T>: no setteroverride
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 setter
localTransform → CLocalTransform<T>?: 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
persistentId ↔ String: getter/setter pairinherited
persistentTypeId → String: no setteroverride
physicsBody → CPhysicsBody<T>?: no setter
populateDefaults ↔ bool: getter/setter pairinherited
QueryComp → QueryEntityComponent<T>: Returns a fresh QueryEntityComponent scoped to this entity's direct components.
no setter
QueryCompDeep → QueryEntityComponentDeep<T>: Returns a fresh QueryEntityComponentDeep that searches all components recursively, including those on child components.
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 → Entity<T>: This object cast to T.
no setterinherited
time → AppTime<T>: Shorthand for App.time.
no setterinherited
transform → CTransform<T>?: no setter
velocity → CVelocity<T>?: no setter
worldPosition → Vector2D: The entity's position in scene space.
no setter

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
bookmarkState(String name) → AnyEntitySnapshot<T>: inherited
callback(void callback()) → void: inherited
captureSnapshot() → AnyEntitySnapshot<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() → Entity<T>: Override to provide a fresh uninitialized instance of this type.
override
createSnapshot() → AnyEntitySnapshot<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.
disableEverything() → Entity<T>: Recursively deactivates every component, including nested ones.
inherited
disableSceneLevelDraw() → void: Prevents the scene's render loop from drawing this entity.
dispatch(Event<T> event, {EventScope scope = .local}) → void: Dispatches an event immediately and synchronously, bypassing the central event queue.
inherited
emit(Event<T> event, {EventScope scope = .local}) → void: Queues an event into the central application event queue for asynchronous processing.
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
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
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
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
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
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
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>
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>
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
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>
onPhysicsBody(void fn(CPhysicsBody<T> v)) → Entity<T>
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>
onUpdate(double dt) → void: Override to react during the update phase each frame.
inherited
onVelocity(void fn(CVelocity<T> v)) → Entity<T>
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
removeEverything() → Entity<T>: Removes every top-level component.
inherited
removeThis() → Entity<T>: Schedules removal of this entity from its scene via the callback queue.
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 AnyEntitySnapshot<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