CStateMachine<T extends App<T>> class

WARNING: CStateMachine cannot be fully restored from persistable data because its states and transitions contain closures (onEnter, onExit, onUpdate, and when).

Either:

  • Extend this class and override onRestorePersistableData to set up states and transitions there.

  • Listen on factories.comp (see App.factories, ECSFactoryRegistry.comp) and rebuild states/transitions when the restored instance matches your type.

MyApp(super.backend) {
  factories.comp.listen((typeId, instance) {
    if (instance is MyStateMachine) {
      instance
        ..addState('idle', onEnter: ...)
        ..transition('idle', 'moving', when: ...)
        ..start('idle');
    }
  });
}
Inheritance

Constructors

CStateMachine(T app, {bool populateDefaults = true, Map<String, CStateMachineStateDef>? states, List<CStateMachineTransition>? transitions})

Properties

app → T
finalinherited
backend → UnhingedBackend
Shorthand for App.backend.
no setterinherited
currentState → String?
no setter
draw → Drawers<T>
Shorthand for App.draw.
no setterinherited
entity ↔ Entity<T>
getter/setter pairinherited
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
hasStarted → bool
no setter
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
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
populateDefaults ↔ bool
getter/setter pairinherited
QueryComp → QueryComponentComponent<T>
Returns a fresh QueryComponentComponent scoped to this component's direct children.
no setterinherited
QueryCompDeep → QueryComponentComponentDeep<T>
Returns a fresh QueryComponentComponentDeep that searches all descendant components recursively, including those on nested child components.
no setterinherited
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 → Comp<T>
This object cast to T.
no setterinherited
time → AppTime<T>
Shorthand for App.time.
no setterinherited
timeInState → double
no setter

Methods

addComp<C extends Comp<T>>(C component) → Comp<T>
Adds component as a new top-level component.
inherited
addCompIfNotExists<C extends Comp<T>>(C component) → Comp<T>
Adds component only if no top-level component of type C already exists.
inherited
addState(String name, {void onEnter()?, void onExit()?, void onUpdate(double dt)?}) → CStateMachine<T>
Define a state. Must be called before start. Calling after start throws, because addState defines the machine's shape once; it's not meant to be mutated while running.
bookmarkState(String name) → AnyCompSnapshot<T>
inherited
callback(void callback()) → void
inherited
captureSnapshot() → AnyCompSnapshot<T>
inherited
captureSnapshotAs<X extends S>() → X
inherited
clearEventHistory() → void
Clears history of recorded events.
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
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(Comp<T> newInstance, [Cloner<T>? cloner]) → Comp<T>
Override to customize how state is copied into newInstance.
inherited
createInstance() → CStateMachine<T>
Override to provide a fresh uninitialized instance of this type.
override
createSnapshot() → CStateMachineSnapshot<T>
override
decVar<V extends num>(VarKey<V> key, [V? amount]) → V
inherited
disableComp<C extends Comp<T>>() → Comp<T>
Deactivates every top-level component of type C.
inherited
disableComps() → Comp<T>
Deactivates all top-level components (not nested).
inherited
disableEverything() → Comp<T>
Recursively deactivates every component, including nested ones.
inherited
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>>() → Comp<T>
Activates every top-level component of type C.
inherited
enableComps() → Comp<T>
Activates all top-level components.
inherited
enableEverything() → Comp<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<Comp<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
inState(String name) → bool
isAncestorOf(Comp<T> other) → bool
inherited
isDescendantOf(Comp<T> other) → bool
inherited
listenHandleInput(void fn(Comp<T> self)) → Comp<T>
Registers fn to be called during the input handling phase.
inherited
listenOnActivate(void fn(Comp<T> self)) → Comp<T>
Registers fn to be called whenever the active state changes.
inherited
listenOnAdd(void fn(Comp<T> self, ECSBase<T> parent)) → Comp<T>
Registers fn as an add listener.
inherited
listenOnAfterAdd(void fn(Comp<T> self, ECSBase<T> parent)) → Comp<T>
Registers fn as an after-add listener.
inherited
listenOnAfterClone(void fn(Comp<T> copy, [Cloner<T>? cloner])) → Comp<T>
Registers fn as an after-clone listener.
inherited
listenOnAfterCompAdd(void fn(Comp<T> self, Comp<T> component)) → Comp<T>
inherited
listenOnAfterCompClone(void fn(Comp<T> self, Comp<T> component)) → Comp<T>
inherited
listenOnAfterCompRemove(void fn(Comp<T> self, Comp<T> component)) → Comp<T>
inherited
listenOnAfterRemove(void fn(Comp<T> self)) → Comp<T>
Registers fn as an after-remove listener.
inherited
listenOnBeforeAdd(bool fn(Comp<T> self, ECSBase<T> parent)) → Comp<T>
Registers fn as a before-add listener.
inherited
listenOnBeforeClone(bool fn(Comp<T> copy, [Cloner<T>? cloner])) → Comp<T>
Registers fn as a before-clone listener.
inherited
listenOnBeforeCompAdd(bool fn(Comp<T> self, Comp<T> component)) → Comp<T>
inherited
listenOnBeforeCompClone(bool fn(Comp<T> self, Comp<T> component)) → Comp<T>
inherited
listenOnBeforeCompRemove(bool fn(Comp<T> self, Comp<T> component)) → Comp<T>
inherited
listenOnBeforeEvent(bool fn(Comp<T> self, Event<T> event)) → Comp<T>
Registers fn as a before-event listener.
inherited
listenOnBeforeEventRecorded(bool fn(Comp<T> self, Event<T> event)) → Comp<T>
Registers fn as a before-event-record listener.
inherited
listenOnBeforeRemove(bool fn(Comp<T> other)) → Comp<T>
Registers fn as a before-remove listener.
inherited
listenOnBeforeStorePersistable(bool fn(Comp<T> other)) → Comp<T>
Registers fn as a before-persistence listener.
inherited
listenOnClone(void fn(Comp<T> copy, [Cloner<T>? cloner])) → Comp<T>
Registers fn as a clone listener.
inherited
listenOnCompAdd(void fn(Comp<T> self, Comp<T> component)) → Comp<T>
inherited
listenOnCompClone(void fn(Comp<T> self, Comp<T> component)) → Comp<T>
inherited
listenOnCompRemove(void fn(Comp<T> self, Comp<T> component)) → Comp<T>
inherited
listenOnDispose(void fn(Comp<T> self)) → Comp<T>
Registers fn to be called at the disposal of the owned ECS object.
inherited
listenOnDraw(void fn(Comp<T> self, double dt)) → Comp<T>
Registers fn to be called during the draw phase each frame.
inherited
listenOnEvent(void fn(Comp<T> self, Event<T> event)) → Comp<T>
Registers fn to be called for every incoming event.
inherited
listenOnEventRecorded(void fn(Comp<T> self, Event<T> event)) → Comp<T>
Registers fn to be called for every event recorded.
inherited
listenOnRemove(void fn(Comp<T> self)) → Comp<T>
Registers fn as a remove listener.
inherited
listenOnStorePersistable(MapData fn(Comp<T> self, MapData data)) → Comp<T>
Registers fn as an store persistable listener.
inherited
listenOnUpdate(void fn(Comp<T> self, double dt)) → Comp<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)) → Comp<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)) → Comp<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)) → Comp<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(Comp<T> copy, [Cloner<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)) → Comp<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(Comp<T> copy, [Cloner<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
onClone(Comp<T> copy, [Cloner<T>? cloner]) → void
Override to react when cloning is about to complete.
inherited
onCloned(Comp<T> original) → void
Called on the copy after cloning completes, with a reference to original.
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
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
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(Comp<T> self)) → Comp<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
onUpdate(double dt) → void
Fires onEnter (if not already fired for this state), evaluates transitions, fires onExit when leaving, then calls onUpdate for whichever state is current after any transition.
override
persistAutoLoad({int? slot}) → void
inherited
persistAutoSave({required double interval, required int slots}) → AnyCompSnapshot<T>?
inherited
removeComp<C extends Comp<T>>() → Comp<T>
Removes the first top-level component matching type C.
inherited
removeCompByType(Type type) → Comp<T>
Removes the first top-level component whose runtimeType == type.
inherited
removeCompExact(Comp<T> component) → Comp<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>>() → Comp<T>
Removes all top-level components matching type C.
inherited
removeEverything() → Comp<T>
Removes every top-level component.
inherited
replaceComp(Comp<T> component) → Comp<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 CStateMachineSnapshot<T> snapshot) → void
override
run(Task<T> task) → void
inherited
setActive(bool active) → Comp<T>
Sets the active state to active and fires the activation hook.
inherited
setVar<V>(VarKey<V> key, V value) → Comp<T>
inherited
start(String initialState) → CStateMachine<T>
Start the machine in initialState. Fires that state's onEnter.
storePersistable() → MapData?
inherited
swapComp<A extends Comp<T>>(Comp<T> newC) → Comp<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) → Comp<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() → Comp<T>
Toggles the active state and fires the activation hook.
inherited
toString() → String
A string representation of this object.
inherited
transition(String from, String to, {required bool when()}) → CStateMachine<T>
Define a transition. when is checked every onUpdate while the machine is in from; first matching transition wins, evaluated in the order they were added.
uniqKey(String key) → String
Returns a key namespaced to this object's namedId.
inherited
whenClone(Comp<T> fn(Comp<T> newInstance, [Cloner<T>? cloner])) → Comp<T>
Registers fn as the clone factory, replacing the default clone behavior.
inherited
whenCloned(Comp<T> fn(Comp<T> self, Comp<T> copy)) → Comp<T>
Registers fn to run after the clone is produced.
inherited
whenCreateInstance(Comp<T> fn(Comp<T> component)) → Comp<T>
Registers fn as the instance factory used during cloning.
inherited

Operators

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

Constants

typeId → const String