Scene<T extends App<T>> class

A self-contained game scene, the primary organizational unit of the ECS.

A Scene owns a set of Entity objects, a collection of SceneSystems, an event queue, and a deferred callback queue. The app lifecycle drives the scene through a fixed sequence each frame:

_doUpdate(dt)
  ├─ _processEvents()
  ├─ _updateScene(dt)
  │    ├─ _doHandleInput()
  │    ├─ _doPreUpdate(dt)
  │    ├─ systems (preEntities phase)
  │    ├─ _updateEntities(dt)
  │    ├─ systems (postEntities phase)
  │    └─ _doPostUpdate(dt)
  └─ onUpdate callbacks (happens after everything updated)

_doDraw(dt)
  └─ per render layer:
       ├─ onDrawBackground   (on RenderLayers.background)
       ├─ systems (preEntities draw phase)
       ├─ _drawEntities(dt)
       ├─ systems (postEntities draw phase)
       ├─ onDrawForeground   (on RenderLayers.foreground)
       └─ onDraw callbacks (happens after everything drawn)

_doBeginFrame(dt)
  ├─ beginFrame callbacks (happens before anything)
  └─ systems beginFrame

_doEndFrame(dt)
  ├─ process drain loop
  ├─ process callbacks
  ├─ process drain loop
  ├─ systems endFrame
  └─ endFrame callbacks (happens after everything)

Drawing

For scenes that render directly to the screen, prefer DrawScene, which handles RaylibCoreD.BeginDrawing/RaylibCoreD.EndDrawing automatically. Use Scene directly only when you need manual control over the drawing lifecycle.

Events

Events posted via emit are queued and processed in priority order at the start of the next _doUpdate. Events posted via dispatch are delivered immediately.

Cloning

clone produces a deep copy of the scene, entities, systems, hooks, and the event queue, subject to an optional SceneCloner that can selectively exclude or transform individual elements.

Key

Each scene has a key used to identify it in the app's scene registry. If not supplied at construction, defaults to '$runtimeType.$id'.

Inheritance

Object
ECSBase<T>
Scene

Mixed-in types

Self<Scene<T>>
HasSceneAccess<T>
HasVars<T, Scene<T>>
IsAddable<T, Scene<T>>
IsBeginEndFrameable<T, Scene<T>>
IsClonable<T, Scene<T>, SceneCloner<T>>
IsDisposable<T, Scene<T>>
IsDrawable<T, Scene<T>>
IsEnterable<T, Scene<T>>
IsEntityManagable<T, Scene<T>, Entity<T>>
IsEventEmittable<T, Scene<T>>
IsEventHistoryHolder<T, Scene<T>>
IsInputHandleable<Scene<T>>
IsLeavable<T, Scene<T>>
IsPrePostDrawable<T, Scene<T>>
IsPrePostUpdatable<T, Scene<T>>
IsRemovable<T, Scene<T>>
IsSceneSystemManagable<T, Scene<T>>
IsStartable<T, Scene<T>>
IsTaskProcessable<T, Scene<T>>
IsUpdatable<T, Scene<T>>
IsCallbackProcessable<T, Scene<T>>
IsStateHolder<T, Scene<T>, AnySceneSnapshot<T>>
IsPersistable<T, Scene<T>, AnySceneSnapshot<T>>

Implementers

DrawScene

Constructors

Scene(T app, {String? key, bool populateDefaults = true}): Creates a new scene bound to app.

Properties

app → T: final
backend → UnhingedBackend: Shorthand for App.backend.
no setterinherited
draw → Drawers<T>: Shorthand for App.draw.
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
hasStarted ↔ bool: Whether this object has already started.
getter/setter pairinherited
id → int: Per-type unique identifier, auto-assigned in the constructor.
no setterinherited
input → InputSystem<T>: Shorthand for App.input.
no setteroverride
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
isDrainLoopEmptyForTest → bool: no setter
isOriginal → bool: Whether this object is an original (not a clone).
no setterinherited
isRemoved ↔ bool: Whether this object has been removed.
getter/setter pairinherited
isTaskQueueEmptyForTest → bool: no setter
key ↔ String: Unique identifier for this scene within the app's scene registry.
latefinal
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
QueryEntity → QueryEntities<T, Scene<T>>: Returns a fresh QueryEntity scoped to this scene.
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 setteroverride
sceneBounds ↔ Bounds: getter/setter pairoverride-getter
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 → Scene<T>: no setterinherited
time → AppTime<T>: Shorthand for App.time.
no setterinherited

Methods

addEntity(Entity<T> entity) → bool: Registers entity and runs the full add lifecycle.
inherited
addSystem<S extends SceneSystem<T>>(S system) → void: Registers system in this scene and runs the full add lifecycle.
inherited
bookmarkState(String name) → AnySceneSnapshot<T>: inherited
callback(void callback()) → void: Schedules a callback.
inherited
captureSnapshot() → AnySceneSnapshot<T>: override
captureSnapshotAs<X extends S>() → X: inherited
clearCallbackQueue() → void: Clears callback queue.
inherited
clearEventHistory() → void: Clears history of recorded events.
inherited
clearTaskQueue() → void: Clears task queue.
inherited
clone<X extends E>([SceneCloner<T>? cloner]) → X: Produces a clone of this object.
inherited
cloneInto<X extends E>(X target, [SceneCloner<T>? cloner]) → X: inherited
createClone(Scene<T> newInstance, [SceneCloner<T>? cloner]) → Scene<T>: Override to customize how state is copied into newInstance.
inherited
createInstance() → Scene<T>: Override to provide a fresh uninitialized instance of this type.
override
createSnapshot() → AnySceneSnapshot<T>: override
decVar<V extends num>(VarKey<V> key, [V? amount]) → V: 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
exchangeSystems<A extends SceneSystem<T>, B extends SceneSystem<T>>() → void: Exchanges the positions of the first found system of type A with the first found system of type B. No-op if either type is not found.
inherited
getAncestors() → Iterable<ECSBase<T>>: Returns every ancestor of this component, from immediate parent up to the root.
inherited
getClones() → Iterable<Scene<T>>: Returns all clones produced from this object.
inherited
getDepth() → int: Returns the depth/level in the hierarchy.
inherited
getEntities() → Set<Entity<T>>: Returns all entities currently registered.
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
getSystem<S extends SceneSystem<T>>() → S?: Returns the registered system of type S, or null if absent.
inherited
getSystems() → Iterable<SceneSystem<T>>: Returns all systems currently registered in this scene.
inherited
getVar<V>(VarKey<V> key) → V?: inherited
getVarSafe<V>(VarKey<V> key, V fallback) → V: inherited
hasParentOf<P extends ECSBase<T>>() → bool: Whether parent is of type P.
inherited
hasSystem<S extends SceneSystem<T>>() → bool: Returns true if a system of type S is currently registered.
inherited
hasSystemByType(Type type) → bool: Returns true if a system registered under type is currently present.
inherited
hasVar(VarKey key) → bool: inherited
incVar<V extends num>(VarKey<V> key, [V? amount]) → V: inherited
listenHandleInput(void fn(Scene<T> self)) → Scene<T>: Registers fn to be called during the input handling phase.
inherited
listenOnAdd(void fn(Scene<T> self, ECSBase<T> parent)) → Scene<T>: Registers fn as an add listener.
inherited
listenOnAfterAdd(void fn(Scene<T> self, ECSBase<T> parent)) → Scene<T>: Registers fn as an after-add listener.
inherited
listenOnAfterClone(void fn(Scene<T> copy, [SceneCloner<T>? cloner])) → Scene<T>: Registers fn as an after-clone listener.
inherited
listenOnAfterEnter(void fn(Scene<T> self)) → Scene<T>: Registers fn as an after-enter listener.
inherited
listenOnAfterEntityAdd(void fn(Scene<T> self, Entity<T> entity)) → Scene<T>: Registers fn as an after-add listener.
inherited
listenOnAfterEntityRemove(void fn(Scene<T> self, Entity<T> entity)) → Scene<T>: Registers fn as an after-remove listener.
inherited
listenOnAfterLeave(void fn(Scene<T> self)) → Scene<T>: Registers fn as an after-leave listener.
inherited
listenOnAfterRemove(void fn(Scene<T> self)) → Scene<T>: Registers fn as an after-remove listener.
inherited
listenOnAfterSceneSystemAdd(void fn(Scene<T> self, SceneSystem<T> system)) → Scene<T>: Registers fn as an after-add listener.
inherited
listenOnAfterSceneSystemRemove(void fn(Scene<T> self, SceneSystem<T> system)) → Scene<T>: Registers fn as an after-remove listener.
inherited
listenOnBeforeAdd(bool fn(Scene<T> self, ECSBase<T> parent)) → Scene<T>: Registers fn as a before-add listener.
inherited
listenOnBeforeClone(bool fn(Scene<T> copy, [SceneCloner<T>? cloner])) → Scene<T>: Registers fn as a before-clone listener.
inherited
listenOnBeforeEnter(bool fn(Scene<T> self)) → Scene<T>: Registers fn as a before-enter listener.
inherited
listenOnBeforeEntityAdd(bool fn(Scene<T> self, Entity<T> entity)) → Scene<T>: Registers fn as a before-add listener.
inherited
listenOnBeforeEntityRemove(bool fn(Scene<T> self, Entity<T> entity)) → Scene<T>: Registers fn as a before-remove listener.
inherited
listenOnBeforeEvent(bool fn(Scene<T> self, Event<T> event)) → Scene<T>: Registers fn as a before-event listener.
inherited
listenOnBeforeEventRecorded(bool fn(Scene<T> self, Event<T> event)) → Scene<T>: Registers fn as a before-event-record listener.
inherited
listenOnBeforeLeave(bool fn(Scene<T> self)) → Scene<T>: Registers fn as a before-leave listener.
inherited
listenOnBeforeRemove(bool fn(Scene<T> self)) → Scene<T>: Registers fn as a before-remove listener.
inherited
listenOnBeforeSceneSystemAdd(bool fn(Scene<T> self, SceneSystem<T> system)) → Scene<T>: Registers fn as a before-add listener.
inherited
listenOnBeforeSceneSystemRemove(bool fn(Scene<T> self, SceneSystem<T> system)) → Scene<T>: Registers fn as a before-remove listener.
inherited
listenOnBeforeStorePersistable(bool fn(Scene<T> self)) → Scene<T>: Registers fn as a before-persistence listener.
inherited
listenOnBeginFrame(void fn(Scene<T> self, double dt)) → Scene<T>: Registers fn to be called at the start of each frame.
inherited
listenOnClone(void fn(Scene<T> copy, [SceneCloner<T>? cloner])) → Scene<T>: Registers fn as a clone listener.
inherited
listenOnDispose(void fn(Scene<T> self)) → Scene<T>: Registers fn to be called at the disposal of the owned ECS object.
inherited
listenOnDraw(void fn(Scene<T> self, double dt)) → Scene<T>: Registers fn to be called during the draw phase each frame.
inherited
listenOnDrawBackground(void fn(Scene<T> self, double dt)) → Scene<T>: Registers fn to be called each frame during the background draw pass, before onDrawBackground. Returns self for chaining.
listenOnDrawForeground(void fn(Scene<T> self, double dt)) → Scene<T>: Registers fn to be called each frame during the foreground draw pass, before onDrawForeground. Returns self for chaining.
listenOnEndFrame(void fn(Scene<T> self, double dt)) → Scene<T>: Registers fn to be called at the end of each frame.
inherited
listenOnEnter(void fn(Scene<T> self)) → Scene<T>: Registers fn to be called when this object is entered.
inherited
listenOnEntityAdd(void fn(Scene<T> self, Entity<T> entity)) → Scene<T>: Registers fn as an add listener.
inherited
listenOnEntityRemove(void fn(Scene<T> self, Entity<T> entity)) → Scene<T>: Registers fn as a remove listener.
inherited
listenOnEvent(void fn(Scene<T> self, Event<T> event)) → Scene<T>: Registers fn to be called for every incoming event.
inherited
listenOnEventRecorded(void fn(Scene<T> self, Event<T> event)) → Scene<T>: Registers fn to be called for every event recorded.
inherited
listenOnLeave(void fn(Scene<T> self)) → Scene<T>: Registers fn to be called when this object is left.
inherited
listenOnPostDraw(void fn(Scene<T> self, double dt)) → Scene<T>: Registers fn to be called after the draw phase each frame.
inherited
listenOnPostUpdate(void fn(Scene<T> self, double dt)) → Scene<T>: Registers fn to be called after the update phase each frame.
inherited
listenOnPreDraw(void fn(Scene<T> self, double dt)) → Scene<T>: Registers fn to be called before the draw phase each frame.
inherited
listenOnPreUpdate(void fn(Scene<T> self, double dt)) → Scene<T>: Registers fn to be called before the update phase each frame.
inherited
listenOnRemove(void fn(Scene<T> self)) → Scene<T>: Registers fn as a remove listener.
inherited
listenOnSceneSystemAdd(void fn(Scene<T> self, SceneSystem<T> system)) → Scene<T>: Registers fn as an add listener.
inherited
listenOnSceneSystemRemove(void fn(Scene<T> self, SceneSystem<T> system)) → Scene<T>: Registers fn as a remove listener.
inherited
listenOnStart(void fn(Scene<T> self)) → Scene<T>: Registers fn to be called when this object starts.
inherited
listenOnStorePersistable(MapData fn(Scene<T> self, MapData data)) → Scene<T>: Registers fn as an store persistable listener.
inherited
listenOnTask(bool fn(Task<T> task)) → Scene<T>: Registers fn to be called for each task before it is executed.
inherited
listenOnUpdate(void fn(Scene<T> self, double dt)) → Scene<T>: Registers fn to be called during the update phase each frame.
inherited
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
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(Scene<T> copy, [SceneCloner<T>? cloner]) → void: Override to react after cloning has completed.
inherited
onAfterEnter() → void: Override to react after an enter has completed.
inherited
onAfterEntityAdd(Entity<T> entity) → void: Override to react after an entity add has completed.
inherited
onAfterEntityRemove(Entity<T> entity) → void: Override to react after an entity remove has completed.
inherited
onAfterLeave() → void: Override to react after an leave has completed.
inherited
onAfterRemove() → void: Override to react after removal has completed.
inherited
onAfterSceneSystemAdd(SceneSystem<T> system) → void: Override to react after a system add has completed.
inherited
onAfterSceneSystemRemove(SceneSystem<T> system) → void: Override to react after a system remove has completed.
inherited
onBeforeAdd(ECSBase<T> parent) → bool: Override to cancel the add from within the class.
inherited
onBeforeClone(Scene<T> copy, [SceneCloner<T>? cloner]) → bool: Override to cancel cloning from within the class.
inherited
onBeforeEnter() → bool: Override to cancel an enter from within the class.
inherited
onBeforeEntityAdd(Entity<T> entity) → bool: Override to cancel an entity add from within the class.
inherited
onBeforeEntityRemove(Entity<T> 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
onBeforeLeave() → bool: Override to cancel an leave from within the class.
inherited
onBeforeRemove() → bool: Override to cancel removal from within the class.
inherited
onBeforeSceneSystemAdd(SceneSystem<T> system) → bool: Override to cancel a system add from within the class.
inherited
onBeforeSceneSystemRemove(SceneSystem<T> system) → bool: Override to cancel a system remove from within the class.
inherited
onBeforeStorePersistable() → bool: Override to cancel the persistence from within the class.
inherited
onBeginFrame(double dt) → void: Override to react at the start of each frame.
inherited
onClone(Scene<T> copy, [SceneCloner<T>? cloner]) → void: Override to react when cloning is about to complete.
inherited
onCloned(Scene<T> original) → void: Called on the copy after cloning completes, with a reference to original.
inherited
onDispose() → void: Override to react at the disposal.
inherited
onDraw(double dt) → void: Override to react during the draw phase each frame.
inherited
onDrawBackground() → void: Override to draw content behind entities on the RenderLayers.background layer. Called after all listenOnDrawBackground listeners.
onDrawForeground() → void: Override to draw content in front of entities on the RenderLayers.foreground layer. Called after all listenOnDrawForeground listeners.
onEndFrame(double dt) → void: Override to react at the end of each frame.
inherited
onEnter() → void: Override to react when an enter is about to complete.
inherited
onEntityAdd(Entity<T> entity) → void: Override to react when an entity add is about to complete.
inherited
onEntityRemove(Entity<T> 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
onLeave() → void: Override to react when an leave is about to complete.
inherited
onPostDraw(double dt) → void: Override to react after the draw phase each frame.
inherited
onPostUpdate(double dt) → void: Override to react after the update phase each frame.
inherited
onPreDraw(double dt) → void: Override to react before the draw phase each frame.
inherited
onPreUpdate(double dt) → void: Override to react before the update phase each frame.
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
onSceneSystemAdd(SceneSystem<T> system) → void: Override to react when a system add is about to complete.
inherited
onSceneSystemRemove(SceneSystem<T> system) → void: Override to react when a system remove is about to complete.
inherited
onSelf(void fn(Scene<T> self)) → Scene<T>: Calls fn with self and returns self, for fluent chaining.
inherited
onStart() → void: Override to react when this object starts.
inherited
onStorePersistable(MapData data) → MapData: Override to react when the persistence is about to complete.
inherited
onTask(Task<T> task) → void: Override to intercept tasks before they execute.
inherited
onUpdate(double dt) → void: Override to react during the update phase each frame.
inherited
persistAutoLoad({int? slot}) → void: inherited
persistAutoSave({required double interval, required int slots}) → AnySceneSnapshot<T>?: inherited
processDrainLoopForTest() → void: Synchronously runs the drain loop.
processTaskQueueForTest() → void: Synchronously processes the task queue.
relocateSystem<S extends SceneSystem<T>>(int index) → void: Moves the first found system of type S to the specified index. No-op if no system of type S is found. Clamps index to the valid range of the list.
inherited
removeEntity(Entity<T> entity) → bool: Unregisters entity and runs the full remove lifecycle.
inherited
removeSystem<S extends SceneSystem<T>>() → Scene<T>: Removes the system of type S. No-op if absent.
inherited
removeSystemByType(Type type) → Scene<T>: Removes the system registered under type and runs the full remove lifecycle. Emits EventSceneSystemRemoving; cancellable hooks emit EventSceneSystemRemoveCancelled. On success emits EventSceneSystemRemoved.
inherited
replaceSystem(SceneSystem<T> system) → Scene<T>: Replaces the first scene system whose runtimeType == system.runtimeType with system.
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 AnySceneSnapshot<T> snapshot) → void: override
run(Task<T> task) → Scene<T>: Enqueues task and executes it immediately at the end of the current frame, if it isn't already running.
inherited
setVar<V>(VarKey<V> key, V value) → Scene<T>: inherited
storePersistable() → MapData?: inherited
swapSystem<A extends SceneSystem<T>>(SceneSystem<T> newSystem) → void: Replaces the registered A system with newSystem of type B in one step.
inherited
swapSystemByType<B extends SceneSystem<T>>(Type type, B newSystem) → void: Replaces the system registered under type with newSystem in one step.
inherited
task(Task<T> task) → void: Enqueues task for execution starting at the end of the current frame.
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(Scene<T> fn(Scene<T> newInstance, [SceneCloner<T>? cloner])) → Scene<T>: Registers fn as the clone factory, replacing the default clone behavior.
inherited
whenCloned(Scene<T> fn(Scene<T> self, Scene<T> copy)) → Scene<T>: Registers fn to run after the clone is produced.
inherited
whenCreateInstance(Scene<T> fn(Scene<T> self)) → Scene<T>: Registers fn as the instance factory used during cloning.
inherited

Operators

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

Constants

typeId → const String