Scene

Defined in: Scene.ts:177

Scenes own entities and define lifecycle hooks. Each scene is a self-contained world with its own entity pool.

Extended by

• LoadingScene

Constructors

Constructor

new Scene(): Scene

Returns

Scene

Properties

_childSpawn

_childSpawn: boolean = false

Defined in: Scene.ts:315

Internal

Set by Entity.spawnChild for the duration of its spawn call, and consumed by that call. It marks the one spawn a child creation is allowed to make while a batch is open; anything else reaching spawn then is a top-level entity the batch could not roll back.

---

_spawnInert

_spawnInert: boolean = false

Defined in: Scene.ts:306

Internal

Set by Entity.spawnChild while the parent is dormant. A spawn runs setup() before the parent link exists, so without this the child would be briefly active and fire enable hooks it is about to undo.

Consumed by the first entity the spawn creates — that is the child itself, built before its setup() runs. Anything setup() spawns on its own is a separate entity with no parent to resync it, so it must not inherit the suppression and stay dormant forever.

---

defaultTransition?

readonly optional defaultTransition?: SceneTransition

Defined in: Scene.ts:204

Default transition used when this scene is the destination of a push/pop/replace.

---

fixedUpdate?

readonly optional fixedUpdate?: undefined

Defined in: Scene.ts:1018

Reserved: a subclass that declares fixedUpdate fails to compile.

There is no fixed-step scene hook either, and for the same reason. Both homes above apply: a component on an entity the scene spawns, or a process on the queue that makeSceneScopedQueue() returns.

The slot is optional, so the compiler reports the subclass method as not assignable to type undefined rather than to type never.

---

name

abstract readonly name: string

Defined in: Scene.ts:179

Name for debugging/inspection.

---

pauseBelow

readonly pauseBelow: boolean = true

Defined in: Scene.ts:182

Whether scenes below this one in the stack should be paused. Default: true.

---

preload?

readonly optional preload?: readonly AssetHandle<unknown>[]

Defined in: Scene.ts:201

Asset handles to load before onEnter(). Override in subclasses.

---

timeScale

timeScale: number = 1

Defined in: Scene.ts:276

Time scale multiplier for this scene. 1.0 = normal, 0.5 = half speed. Default: 1.

---

transparentBelow

readonly transparentBelow: boolean = false

Defined in: Scene.ts:198

Whether scenes below this one should still render. Default: false.

When false (the default), the renderer hides every below-stack scene tree — both world-space layers AND screen-space layers (HUD, UI panels, dialogs). Set true for pause menus, dialog overlays, or any scene that should be drawn on top of a still-visible game world.

The chain composes: a below scene stays visible only while every scene above it has transparentBelow = true. While a scene transition is running, both the outgoing and incoming scenes render regardless of this flag so transitions like crossFade keep working; the chain is reapplied when the transition ends.

---

update?

readonly optional update?: undefined

Defined in: Scene.ts:1006

Reserved: a subclass that declares update fails to compile.

The engine’s per-frame pass ticks components, so a scene method with this name is dead code. Per-frame scene logic has two homes: a component on an entity the scene spawns, or a process on the queue that makeSceneScopedQueue() returns, which lives and dies with the scene.

The slot is optional, so the compiler reports the subclass method as not assignable to type undefined rather than to type never.

The hooks above are every hook Scene itself declares; LoadingScene adds onLoadError for a preload that fails.

Accessors

assets

Get Signature

get assets(): AssetManager

Defined in: Scene.ts:346

Convenience accessor for the AssetManager.

Returns

AssetManager

---

context

Get Signature

get context(): EngineContext

Defined in: Scene.ts:321

Access the EngineContext.

Returns

EngineContext

---

isPaused

Get Signature

get isPaused(): boolean

Defined in: Scene.ts:326

Whether this scene is effectively paused (manual pause or paused by stack).

Returns

boolean

---

isTransitioning

Get Signature

get isTransitioning(): boolean

Defined in: Scene.ts:340

Whether a scene transition is currently running.

Returns

boolean

---

paused

Get Signature

get paused(): boolean

Defined in: Scene.ts:220

Manual pause flag. Set by game code to pause this scene regardless of stack position. Assigning it fires onPause/onResume when the effective pause state (isPaused) flips — writes that don’t change the flag, or that are masked by a stack pause, fire nothing. Writes before the scene is pushed fire nothing either; the push itself fires onPause for a scene entering paused.

To start a scene paused, set paused = true before pushing it — the push fires onPause once. Do NOT write paused from inside a lifecycle hook (onEnter/onExit/onPause/onResume): that write races the stack transition’s own pause diff, so onPause/onResume can fire twice or unpaired. A dev-mode warning flags this case.

Returns

boolean

Set Signature

set paused(value): void

Defined in: Scene.ts:224

Parameters

value

boolean

Returns

void

Methods

_addExistingEntity()

_addExistingEntity(entity): void

Defined in: Scene.ts:786

Internal

Add an existing entity to this scene (used by Entity.addChild for auto-scene-membership).

Parameters

entity

Entity

Returns

void

---

_announceBatchEntity()

_announceBatchEntity(entity): void

Defined in: Scene.ts:742

Internal

Internal: announce one committed batch entity. The entity is dormant, so component:added joins no query — activation does that.

Parameters

entity

Entity

Returns

void

---

_assertKeyFree()

_assertKeyFree(key): void

Defined in: Scene.ts:711

Internal

Internal: throw if a live entity already holds key. A spawn batch checks it when reserving, long before the key reaches the index.

Parameters

key

string

Returns

void

---

_clearScopedServices()

_clearScopedServices(): void

Defined in: Scene.ts:1085

Internal

Clear all scene-scoped services. Called by the SceneManager after afterExit hooks run, so plugin cleanup code still sees scoped state.

Returns

void

---

_destroyAllEntities()

_destroyAllEntities(): void

Defined in: Scene.ts:1174

Internal

Destroy all entities — used during scene exit. Applies the same destroy contract as _flushDestroyQueue: entities are marked destroyed, torn down, detached from the scene, and entity:destroyed is emitted once per entity (including entities queued but not yet flushed). Clears the identity index in bulk; per-entity key removal in _flushDestroyQueue is the in-game path.

Returns

void

---

_dropFromDestroyQueue()

_dropFromDestroyQueue(entities): void

Defined in: Scene.ts:758

Internal

Internal: drop entities a spawn batch discarded from the destroy queue. They are already fully torn down, and the end-of-frame flush would run their teardown a second time.

Parameters

entities

ReadonlySet<Entity>

Returns

void

---

_finalizeEntityDestroy()

_finalizeEntityDestroy(entity, announce?, onError?): void

Defined in: Scene.ts:1144

Internal

Internal: tear an entity down and take it out of the scene.

A spawn batch rolling back passes announce: false for entities it never published, and an onError handler: its teardown has to finish whatever throws, because the error the caller is waiting for is the one that started the rollback.

Parameters

entity

Entity

announce?

boolean = true

onError?

(error) => void

Returns

void

---

_flushDestroyQueue()

_flushDestroyQueue(): void

Defined in: Scene.ts:1128

Internal

Flush the destroy queue — destroy pending entities. Called by the engine during the endOfFrame phase.

Returns

void

---

_observeTokenEvent()

_observeTokenEvent(eventName, data, entity): void

Defined in: Scene.ts:947

Internal

Observe a token event after its handlers ran: an entity emit after it dispatched locally and bubbled here (entity is the source), or a scene.emit (entity is undefined). Tooling only; game code should keep using on(). The observer is a callback dispatched outside any wrapped tick, so a throw is attributed here.

Parameters

eventName

string

data

unknown

entity

Entity | undefined

Returns

void

---

_onEntityEvent()

_onEntityEvent(eventName, data, entity): void

Defined in: Scene.ts:919

Internal

Called by Entity.emit() for bubbling entity events to the scene.

Parameters

eventName

string

data

unknown

entity

Entity

Returns

void

---

_queueDestroy()

_queueDestroy(entity): void

Defined in: Scene.ts:820

Internal

Add an entity to the destroy queue. Called by Entity.destroy().

Parameters

entity

Entity

Returns

void

---

_registerBatchEntities()

_registerBatchEntities(entities): void

Defined in: Scene.ts:727

Internal

Internal: put a committed batch’s entities in the scene. Keys land here too, so the first entity:created subscriber can already find any of them by key.

Parameters

entities

readonly Entity[]

Returns

void

---

_registerKey()

_registerKey(entity, key): void

Defined in: Scene.ts:700

Internal

Internal: register a key on a freshly spawned entity. Throws on duplicate so callers (Scene.spawn) can abort before adding to this.entities or emitting entity:created.

Parameters

entity

Entity

key

string

Returns

void

---

_registerPool()

_registerPool(pool): void

Defined in: Scene.ts:770

Internal

Internal: track a pool so the scene can dispose it on exit. Called by the EntityPool constructor.

Parameters

pool

ScenePool

Returns

void

---

_registerScoped()

_registerScoped<T>(key, value): void

Defined in: Scene.ts:1042

Internal

Internal alias for registerScoped kept so existing plugin/test code doesn’t churn. Prefer registerScoped in new code.

Type Parameters

T

T

Parameters

key

ServiceKey<T>

value

T

Returns

void

---

_reinsert()

_reinsert(entity): void

Defined in: Scene.ts:810

Internal

Move entity and its descendants to the end of the entity set, so a pass already iterating the set visits them after the entity that acquired them — the position a fresh spawn gets.

Parameters

entity

Entity

Returns

void

---

_resolveScoped()

_resolveScoped<T>(key): T | undefined

Defined in: Scene.ts:1076

Internal

Internal alias for tryResolveScoped. Prefer tryResolveScoped in new code.

Type Parameters

T

T

Parameters

key

ServiceKey<T>

Returns

T | undefined

---

_setContext()

_setContext(context): void

Defined in: Scene.ts:1093

Internal

Set the engine context. Called by SceneManager when the scene is pushed.

Parameters

context

EngineContext

Returns

void

---

_setTokenEventObserver()

_setTokenEventObserver(observer?): void

Defined in: Scene.ts:1051

Internal

Install or clear a tooling-only observer for token events — bubbled entity emits and scene.emit alike.

Parameters

observer?

(eventName, data, entity) => void

Returns

void

---

_unregisterPool()

_unregisterPool(pool): void

Defined in: Scene.ts:778

Internal

Internal: stop tracking a pool. Called by EntityPool.dispose.

Parameters

pool

ScenePool

Returns

void

---

emit()

Call Signature

emit(token): void

Defined in: Scene.ts:892

Emit a typed event at the scene level. Scene-level on handlers fire with entity = undefined to indicate there’s no emitting entity. Symmetric to Entity.emit but for scene-scoped signalling.

Parameters

token

EventToken<void>

Returns

void

Call Signature

emit<T>(token, data): void

Defined in: Scene.ts:893

Emit a typed event at the scene level. Scene-level on handlers fire with entity = undefined to indicate there’s no emitting entity. Symmetric to Entity.emit but for scene-scoped signalling.

Type Parameters

T

T

Parameters

token

EventToken<T>

data

T

Returns

void

---

findByKey()

findByKey<E>(key): E | undefined

Defined in: Scene.ts:688

Look up an entity by its stable identity key, scoped to this scene. Returns undefined for unknown or already-destroyed entities.

Type Parameters

E

E extends Entity = Entity

Parameters

key

string

Returns

E | undefined

---

findEntities()

Call Signature

findEntities<T>(filter): Entity & T[]

Defined in: Scene.ts:850

Find active entities matching a filter. Trait filter narrows the return type.

Type Parameters

T

T

Parameters

filter

EntityFilter & object

Returns

Entity & T[]

Call Signature

findEntities(filter?): Entity[]

Defined in: Scene.ts:853

Find active entities matching a filter. Trait filter narrows the return type.

Parameters

filter?

EntityFilter

Returns

Entity[]

---

findEntitiesByTag()

findEntitiesByTag(tag): Entity[]

Defined in: Scene.ts:841

Find active entities by tag.

Parameters

tag

string

Returns

Entity[]

---

findEntity()

findEntity(name): Entity | undefined

Defined in: Scene.ts:833

Find an active entity by name (first match).

Parameters

name

string

Returns

Entity | undefined

---

getEntities()

getEntities(): ReadonlySet<Entity>

Defined in: Scene.ts:828

Every entity in the scene, dormant ones included. Teardown walks this set; the lookups below and the query cache return active entities only.

Returns

ReadonlySet<Entity>

---

on()

on<T>(token, handler): () => void

Defined in: Scene.ts:870

Subscribe to scene-level events. Handlers fire for both:

• bubbled events from any entity (via entity.emit) — entity is the source
• scene-emitted events (via scene.emit) — entity is undefined

Type Parameters

T

T

Parameters

token

EventToken<T>

handler

(data, entity?) => void

Returns

() => void

---

onEnter()?

optional onEnter(): void

Defined in: Scene.ts:973

Called when the scene is entered (after preload completes).

Returns

void

---

onExit()?

optional onExit(): void

Defined in: Scene.ts:976

Called when the scene is exited (popped or replaced).

Returns

void

---

onPause()?

optional onPause(): void

Defined in: Scene.ts:983

Called when the scene becomes effectively paused (isPaused flips to true), whatever the source: a pauseBelow scene pushed on top, a manual paused = true, or the manager’s blur auto-pause.

Returns

void

---

onProgress()?

optional onProgress(ratio): void

Defined in: Scene.ts:970

Called during asset preloading with progress ratio (0→1).

Parameters

ratio

number

Returns

void

---

onResume()?

optional onResume(): void

Defined in: Scene.ts:990

Called when the scene stops being effectively paused (isPaused flips to false): the scene above is popped, paused is cleared, or focus returns after a blur auto-pause.

Returns

void

---

registerScoped()

registerScoped<T>(key, value): void

Defined in: Scene.ts:1032

Register a scene-scoped service. Plugins call this from their beforeEnter hook to expose per-scene state (render tree, physics world, …) resolvable via Component.use(key). It is not for game state: score, lives or a run timer live in a component on a host entity spawned with a key and found with findByKey.

Auto-cleared on scene exit — every key registered here is unregistered after onExit runs (and after plugin afterExit hooks see them).

Type Parameters

T

T

Parameters

key

ServiceKey<T>

value

T

Returns

void

---

service()

service<T>(key): T

Defined in: Scene.ts:429

Lazy proxy-based service resolution. Can be used at field-declaration time:

readonly layers = this.service(RenderLayerManagerKey);

The actual resolution is deferred until first property access and is scope-aware (see use()). For scene-scoped keys, prefer resolving inside onEnter() via use() rather than a field initializer — the proxy caches the first resolved value, which would go stale if the scene is exited and re-entered (the scoped value is recreated each enter).

Type Parameters

T

T extends object

Parameters

key

ServiceKey<T>

Returns

T

---

spawn()

Call Signature

spawn(name?, options?): Entity

Defined in: Scene.ts:471

Spawn a new entity in this scene.

Pass { key } in the trailing options to register a stable per-scene identity key, looked up later via scene.findByKey. The key is assigned before setup() runs, so entity.requireKey() is safe inside it.

For the class form, the params type is inferred from the entity’s setup(params) signature. Omitting a required field reports that field as missing on the params object, naming the field that’s actually absent.

Runtime routing for the 2-arg class form (spawn(Class, X)):

• If the class doesn’t declare setup → X is options.
• Else if X’s own keys are exactly SpawnOptions fields ({ key }) → X is options. Covers both setup(params = {}) keyed without params and setup() (no real params) keyed.
• Else → X is params (forwarded to setup). The 3-arg form is always unambiguous: spawn(Class, params, options). If setup() throws, the error reaches the caller unchanged and the entity stays in the scene with whatever setup had added so far.

Don’t name a top-level setup-params field key — the shape check would misroute it. If you must, use the 3-arg form.

Parameters

name?

string

options?

SpawnOptions

Returns

Entity

Call Signature

spawn<P>(blueprint, params, options?): Entity

Defined in: Scene.ts:478

Spawn from a blueprint. Note: blueprint params must not include a top-level key: string field — the runtime can’t disambiguate it from SpawnOptions. If your params do, use the explicit 3-arg form (spawn(bp, params, { key })) so options arrives in the trailing slot.

Type Parameters

P

P

Parameters

blueprint

Blueprint<P>

params

P

options?

SpawnOptions

Returns

Entity

Call Signature

spawn(blueprint, options?): Entity

Defined in: Scene.ts:479

Spawn a new entity in this scene.

Pass { key } in the trailing options to register a stable per-scene identity key, looked up later via scene.findByKey. The key is assigned before setup() runs, so entity.requireKey() is safe inside it.

For the class form, the params type is inferred from the entity’s setup(params) signature. Omitting a required field reports that field as missing on the params object, naming the field that’s actually absent.

Runtime routing for the 2-arg class form (spawn(Class, X)):

• If the class doesn’t declare setup → X is options.
• Else if X’s own keys are exactly SpawnOptions fields ({ key }) → X is options. Covers both setup(params = {}) keyed without params and setup() (no real params) keyed.
• Else → X is params (forwarded to setup). The 3-arg form is always unambiguous: spawn(Class, params, options). If setup() throws, the error reaches the caller unchanged and the entity stays in the scene with whatever setup had added so far.

Don’t name a top-level setup-params field key — the shape check would misroute it. If you must, use the 3-arg form.

Parameters

blueprint

Blueprint<void>

options?

SpawnOptions

Returns

Entity

Call Signature

spawn<E>(Class, …rest): E

Defined in: Scene.ts:481

Spawn an entity subclass; trailing args follow its setup() signature.

Type Parameters

E

E extends Entity

Parameters

Class

() => E

rest

…ClassSpawnArgs<E>

Returns

E

---

spawnBatch()

spawnBatch<T>(build): T

Defined in: Scene.ts:657

Build a set of entities that all exist before any of them is set up, and that arrive in the scene together or not at all.

spawn() finishes one entity at a time, so the second entity does not exist while the first runs setup(), and a failure halfway leaves the entities before it in the scene. A batch reserves every entity first, so setup parameters can carry handles in any direction, and a throw anywhere — in setup(), in a lifecycle-event subscriber, in an onEnable hook — discards the whole set synchronously and publishes nothing.

const { turret, target } = scene.spawnBatch((batch) => {
  const turret = batch.reserve(Turret, { key: "level/turret" });
  const target = batch.reserve(Dummy, { key: "level/dummy" });
  batch.setup(turret, { aimAt: target.handle() });
  batch.setup(target);
  return { turret, target };
});

The callback returns whatever the caller needs; spawnBatch returns it once the batch commits. Reserved entities stay out of scene.getEntities(), findByKey(), and every query until then, so nothing running in the scene can observe a half-built set. entity:created and component:added publish afterwards, in reservation order.

Inside the callback, entity.spawnChild() joins the batch and is rolled back with it. A top-level scene.spawn() throws instead — a batch cannot roll back an entity it does not own.

Type Parameters

T

T

Parameters

build

(batch) => T

Returns

T

---

tryResolveScoped()

tryResolveScoped<T>(key): T | undefined

Defined in: Scene.ts:1067

Resolve a scene-scoped service registered via registerScoped, or undefined if none is registered for this scene. Unlike use(), never falls back to engine scope and never throws — the read for systems that iterate scenes (e.g. physics and particles resolving SceneTimeKey).

Type Parameters

T

T

Parameters

key

ServiceKey<T>

Returns

T | undefined

---

use()

use<T>(key): T

Defined in: Scene.ts:374

Resolve a service by key. Scene-scoped values (registered via registerScoped — e.g. the renderer’s per-scene render tree) take precedence over engine scope, so the obvious call works in the obvious place. Callable from the scene itself and from anything holding a scene reference — an entity’s setup(), a helper function, an addon:

class LevelScene extends Scene {
  onEnter() {
    this.use(SceneRenderTreeKey).fx.addEffect(crt());
  }
}

class Torch extends Entity {
  setup() {
    const lighting = this.scene.use(LightingWorldKey);
  }
}

Scene-scoped values are registered by plugin beforeEnter hooks, which run before onEnter, so they’re available throughout the scene’s lifecycle. Throws if the key resolves nowhere. For lazy resolution at field-declaration time, use service().

Type Parameters

T

T

Parameters

key

ServiceKey<T>

Returns

T