Scene

Defined in: Scene.ts:142

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

_spawnInert

_spawnInert: boolean = false

Defined in: Scene.ts:268

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:169

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

name

abstract readonly name: string

Defined in: Scene.ts:144

Name for debugging/inspection.

pauseBelow

readonly pauseBelow: boolean = true

Defined in: Scene.ts:147

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

preload?

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

Defined in: Scene.ts:166

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

timeScale

timeScale: number = 1

Defined in: Scene.ts:238

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

transparentBelow

readonly transparentBelow: boolean = false

Defined in: Scene.ts:163

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.

Accessors

assets

Get Signature

get assets(): AssetManager

Defined in: Scene.ts:296

Convenience accessor for the AssetManager.

Returns

AssetManager

context

Get Signature

get context(): EngineContext

Defined in: Scene.ts:271

Access the EngineContext.

Returns

EngineContext

isPaused

Get Signature

get isPaused(): boolean

Defined in: Scene.ts:276

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

Returns

boolean

isTransitioning

Get Signature

get isTransitioning(): boolean

Defined in: Scene.ts:290

Whether a scene transition is currently running.

Returns

boolean

paused

Get Signature

get paused(): boolean

Defined in: Scene.ts:185

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:189

Parameters

value

boolean

Returns

void

Methods

_addExistingEntity()

_addExistingEntity(entity): void

Defined in: Scene.ts:575

Internal

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

Parameters

entity

Entity

Returns

void

_clearScopedServices()

_clearScopedServices(): void

Defined in: Scene.ts:811

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:906

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

_flushDestroyQueue()

_flushDestroyQueue(): void

Defined in: Scene.ts:854

Internal

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

Returns

void

_observeEntityEvent()

_observeEntityEvent(eventName, data, entity): void

Defined in: Scene.ts:716

Internal

Observe entity-scoped event emissions after they dispatch locally and bubble to the scene. Tooling only; game code should keep using on().

Parameters

eventName

string

data

unknown

entity

Entity

Returns

void

_onEntityEvent()

_onEntityEvent(eventName, data, entity): void

Defined in: Scene.ts:691

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:595

Internal

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

Parameters

entity

Entity

Returns

void

_registerKey()

_registerKey(entity, key): void

Defined in: Scene.ts:541

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:559

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:773

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

_resolveScoped()

_resolveScoped<T>(key): T | undefined

Defined in: Scene.ts:802

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:819

Internal

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

Parameters

context

EngineContext

Returns

void

_setEntityEventObserver()

_setEntityEventObserver(observer?): void

Defined in: Scene.ts:781

Internal

Install or clear a tooling-only observer for bubbled entity events.

Parameters

observer?

(eventName, data, entity) => void

Returns

void

_unregisterPool()

_unregisterPool(pool): void

Defined in: Scene.ts:567

Internal

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

Parameters

pool

ScenePool

Returns

void

afterRestore()?

optional afterRestore(data, resolve): void

Defined in: Scene.ts:750

Called after entities are restored during save/load. Rebuild non-serializable state here.

Parameters

data

unknown

resolve

SnapshotResolver

Returns

void

destroyEntity()

destroyEntity(entity): void

Defined in: Scene.ts:587

Mark an entity for destruction. Deferred to endOfFrame flush.

Parameters

entity

Entity

Returns

void

emit()

Call Signature

emit(token): void

Defined in: Scene.ts:666

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:667

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:529

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:626

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:627

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:617

Find active entities by tag.

Parameters

tag

string

Returns

Entity[]

findEntity()

findEntity(name): Entity | undefined

Defined in: Scene.ts:609

Find an active entity by name (first match).

Parameters

name

string

Returns

Entity | undefined

getEntities()

getEntities(): ReadonlySet<Entity>

Defined in: Scene.ts:604

Every entity in the scene, dormant ones included — this is the set save and teardown walk. The lookups below and the query cache return active entities only.

Returns

ReadonlySet<Entity>

on()

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

Defined in: Scene.ts:644

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:726

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

Returns

void

onExit()?

optional onExit(): void

Defined in: Scene.ts:729

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

Returns

void

onPause()?

optional onPause(): void

Defined in: Scene.ts:737

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

Returns

void

onProgress()?

optional onProgress(ratio): void

Defined in: Scene.ts:723

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

Parameters

ratio

number

Returns

void

onResume()?

optional onResume(): void

Defined in: Scene.ts:744

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:763

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). Game code can also use it to attach scene-local services without needing a plugin.

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

serialize()?

optional serialize(): unknown

Defined in: Scene.ts:747

Return a JSON-serializable snapshot of this scene’s custom state. Used by the save system.

Returns

unknown

service()

protected service<T>(key): T

Defined in: Scene.ts:359

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:401

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 entity is destroyed and removed before the error is rethrown.

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:408

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:409

Spawn a new entity in this scene.

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 entity is destroyed and removed before the error is rethrown.

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

Call Signature

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

Defined in: Scene.ts:411

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

Type Parameters

E

E extends Entity

Parameters

Class

() => E

rest

…ClassSpawnArgs<E>

Returns

E

tryResolveScoped()

tryResolveScoped<T>(key): T | undefined

Defined in: Scene.ts:793

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()

protected use<T>(key): T

Defined in: Scene.ts:316

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:

onEnter() {
  const tree = this.use(SceneRenderTreeKey); // resolvable from onEnter on
  tree.fx.addEffect(crt());
}

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