Scene

Defined in: Scene.ts:74

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

defaultTransition?

readonly optional defaultTransition?: SceneTransition

Defined in: Scene.ts:101

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

---

name

abstract readonly name: string

Defined in: Scene.ts:76

Name for debugging/inspection.

---

pauseBelow

readonly pauseBelow: boolean = true

Defined in: Scene.ts:79

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

---

paused

paused: boolean = false

Defined in: Scene.ts:104

Manual pause flag. Set by game code to pause this scene regardless of stack position.

---

preload?

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

Defined in: Scene.ts:98

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

---

timeScale

timeScale: number = 1

Defined in: Scene.ts:107

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

---

transparentBelow

readonly transparentBelow: boolean = false

Defined in: Scene.ts:95

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

Convenience accessor for the AssetManager.

Returns

AssetManager

---

context

Get Signature

get context(): EngineContext

Defined in: Scene.ts:126

Access the EngineContext.

Returns

EngineContext

---

isPaused

Get Signature

get isPaused(): boolean

Defined in: Scene.ts:131

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

Returns

boolean

---

isTransitioning

Get Signature

get isTransitioning(): boolean

Defined in: Scene.ts:145

Whether a scene transition is currently running.

Returns

boolean

Methods

_addExistingEntity()

_addExistingEntity(entity): void

Defined in: Scene.ts:348

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

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

Internal

Destroy all entities — used during scene exit. 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:576

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

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

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

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

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

---

_registerScoped()

_registerScoped<T>(key, value): void

Defined in: Scene.ts:512

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

Internal

Resolve a scene-scoped service, or undefined if none was registered.

Type Parameters

T

T

Parameters

key

ServiceKey<T>

Returns

T | undefined

---

_setContext()

_setContext(context): void

Defined in: Scene.ts:547

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

Internal

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

Parameters

observer?

(eventName, data, entity) => void

Returns

void

---

afterRestore()?

optional afterRestore(data, resolve): void

Defined in: Scene.ts:489

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

Mark an entity for destruction. Deferred to endOfFrame flush.

Parameters

entity

Entity

Returns

void

---

emit()

Call Signature

emit(token): void

Defined in: Scene.ts:435

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

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

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

Find 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:396

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

Parameters

filter?

EntityFilter

Returns

Entity[]

---

findEntitiesByTag()

findEntitiesByTag(tag): Entity[]

Defined in: Scene.ts:386

Find entities by tag.

Parameters

tag

string

Returns

Entity[]

---

findEntity()

findEntity(name): Entity | undefined

Defined in: Scene.ts:378

Find entity by name (first match).

Parameters

name

string

Returns

Entity | undefined

---

getEntities()

getEntities(): ReadonlySet<Entity>

Defined in: Scene.ts:373

Get all active entities.

Returns

ReadonlySet<Entity>

---

on()

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

Defined in: Scene.ts:413

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

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

Returns

void

---

onExit()?

optional onExit(): void

Defined in: Scene.ts:477

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

Returns

void

---

onPause()?

optional onPause(): void

Defined in: Scene.ts:480

Called when a scene is pushed on top of this one.

Returns

void

---

onProgress()?

optional onProgress(ratio): void

Defined in: Scene.ts:471

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

Parameters

ratio

number

Returns

void

---

onResume()?

optional onResume(): void

Defined in: Scene.ts:483

Called when the scene above is popped, restoring this scene.

Returns

void

---

registerScoped()

registerScoped<T>(key, value): void

Defined in: Scene.ts:502

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

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

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.

Type Parameters

T

T extends object

Parameters

key

ServiceKey<T>

Returns

T

---

spawn()

Call Signature

spawn(name?, options?): Entity

Defined in: Scene.ts:198

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.

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

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

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

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.

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

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, P>(Class, params, options?): E

Defined in: Scene.ts:208

Spawn an entity subclass with setup params.

Type Parameters

E

E extends Entity

P

P

Parameters

Class

() => E & object

params

P

options?

SpawnOptions

Returns

E

Call Signature

spawn<E>(Class, options?): E

Defined in: Scene.ts:214

Spawn an entity subclass without setup params.

Type Parameters

E

E extends Entity

Parameters

Class

() => E

options?

SpawnOptions

Returns

E