LoadingScene

Defined in: LoadingScene.ts:45

Base class for a progress-bar style loading screen.

Preloads the target scene’s assets through the AssetManager, exposes progress and emits scene:loading:progress / scene:loading:done on the engine event bus, enforces minDuration to prevent flicker on cached loads, then replaces itself with target — optionally through a transition.

LoadingScene owns orchestration only. It does not render anything. To show a progress UI, spawn an entity that subscribes to the loading events (the canonical default is LoadingSceneProgressBar in @yagejs/ui, or any custom component). The loading scene is a normal Scene, so you can use onEnter to spawn whatever you want.

class Boot extends LoadingScene {
  readonly target = new GameScene();
  readonly minDuration = 0.5;
  readonly transition = fade({ duration: 0.3 });
  override onEnter() {
    this.spawn(LoadingSceneProgressBar);
    this.startLoading();
  }
}

await engine.scenes.replace(new Boot());

Set autoContinue = false to gate the handoff behind a continue() call — useful for “press any key to continue” flows. scene:loading:done still fires so UI can react (show a prompt), and whoever eventually calls this.continue() triggers the transition.

Extends

• Scene

Constructors

Constructor

new LoadingScene(): LoadingScene

Returns

LoadingScene

Inherited from

Scene.constructor

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.

Inherited from

Scene._spawnInert

---

autoContinue

readonly autoContinue: boolean = true

Defined in: LoadingScene.ts:70

When true (default), the handoff fires automatically after loading and minDuration. Set false to gate it behind continue() — useful when the loading scene also asks the player to press a key or click.

---

defaultTransition?

readonly optional defaultTransition?: SceneTransition

Defined in: Scene.ts:169

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

Inherited from

Scene.defaultTransition

---

minDuration

readonly minDuration: number = 0

Defined in: LoadingScene.ts:60

Minimum wall-clock seconds the scene stays visible before handing off. Prevents flicker on cached loads. Default 0.

---

name

readonly name: string = "loading"

Defined in: LoadingScene.ts:46

Name for debugging/inspection.

Overrides

Scene.name

---

pauseBelow

readonly pauseBelow: boolean = true

Defined in: Scene.ts:147

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

Inherited from

Scene.pauseBelow

---

preload?

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

Defined in: Scene.ts:166

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

Inherited from

Scene.preload

---

target

abstract readonly target: Scene | (() => Scene)

Defined in: LoadingScene.ts:54

Scene to load and transition to. Accepts an instance or a factory — use a factory when target construction should be deferred until loading starts (heavy constructors, side effects). The factory runs before assets.loadAll so target.preload can be inspected.

---

timeScale

timeScale: number = 1

Defined in: Scene.ts:238

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

Inherited from

Scene.timeScale

---

transition?

readonly optional transition?: SceneTransition

Defined in: LoadingScene.ts:63

Transition used for the loading → target handoff.

---

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.

Inherited from

Scene.transparentBelow

Accessors

assets

Get Signature

get assets(): AssetManager

Defined in: Scene.ts:296

Convenience accessor for the AssetManager.

Returns

AssetManager

Inherited from

Scene.assets

---

context

Get Signature

get context(): EngineContext

Defined in: Scene.ts:271

Access the EngineContext.

Returns

EngineContext

Inherited from

Scene.context

---

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

Inherited from

Scene.isPaused

---

isTransitioning

Get Signature

get isTransitioning(): boolean

Defined in: Scene.ts:290

Whether a scene transition is currently running.

Returns

boolean

Inherited from

Scene.isTransitioning

---

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

Inherited from

Scene.paused

---

progress

Get Signature

get progress(): number

Defined in: LoadingScene.ts:102

Current load progress, 0 → 1. Updated as the AssetManager reports progress.

Returns

number

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

Inherited from

Scene._addExistingEntity

---

_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

Inherited from

Scene._clearScopedServices

---

_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

Inherited from

Scene._destroyAllEntities

---

_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

Inherited from

Scene._flushDestroyQueue

---

_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

Inherited from

Scene._observeEntityEvent

---

_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

Inherited from

Scene._onEntityEvent

---

_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

Inherited from

Scene._queueDestroy

---

_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

Inherited from

Scene._registerKey

---

_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

Inherited from

Scene._registerPool

---

_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

Inherited from

Scene._registerScoped

---

_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

Inherited from

Scene._resolveScoped

---

_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

Inherited from

Scene._setContext

---

_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

Inherited from

Scene._setEntityEventObserver

---

_unregisterPool()

_unregisterPool(pool): void

Defined in: Scene.ts:567

Internal

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

Parameters

pool

ScenePool

Returns

void

Inherited from

Scene._unregisterPool

---

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

Inherited from

Scene.afterRestore

---

continue()

continue(): void

Defined in: LoadingScene.ts:148

Trigger the handoff to target. No-op if already called or if autoContinue already fired it. If called before loading finishes, the handoff runs as soon as loading + minDuration complete.

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

Inherited from

Scene.destroyEntity

---

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

Inherited from

Scene.emit

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

Inherited from

Scene.emit

---

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

Inherited from

Scene.findByKey

---

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[]

Inherited from

Scene.findEntities

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[]

Inherited from

Scene.findEntities

---

findEntitiesByTag()

findEntitiesByTag(tag): Entity[]

Defined in: Scene.ts:617

Find active entities by tag.

Parameters

tag

string

Returns

Entity[]

Inherited from

Scene.findEntitiesByTag

---

findEntity()

findEntity(name): Entity | undefined

Defined in: Scene.ts:609

Find an active entity by name (first match).

Parameters

name

string

Returns

Entity | undefined

Inherited from

Scene.findEntity

---

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>

Inherited from

Scene.getEntities

---

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

Inherited from

Scene.on

---

onEnter()?

optional onEnter(): void

Defined in: Scene.ts:726

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

Returns

void

Inherited from

Scene.onEnter

---

onExit()

onExit(): void

Defined in: LoadingScene.ts:154

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

Returns

void

Overrides

Scene.onExit

---

onLoadError()?

optional onLoadError(error): void | Promise<void>

Defined in: LoadingScene.ts:85

Optional hook; fires if asset loading rejects. The scene stays mounted whether or not this is set. When set, the hook is the recovery channel: draw a retry UI, push an error scene, or call this.startLoading() again to retry the load. When unset, the error is logged via the engine logger and the scene remains mounted in a failed state with no automatic recovery.

The hook may still be running when the scene is replaced externally — don’t assume the scene is live (check this.context.tryResolve rather than this.service before touching engine services, and avoid spawning new entities after an await).

Parameters

error

Error

Returns

void | Promise<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

Inherited from

Scene.onPause

---

onProgress()?

optional onProgress(ratio): void

Defined in: Scene.ts:723

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

Parameters

ratio

number

Returns

void

Inherited from

Scene.onProgress

---

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

Inherited from

Scene.onResume

---

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

Inherited from

Scene.registerScoped

---

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

Inherited from

Scene.serialize

---

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

Inherited from

Scene.service

---

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

Inherited from

Scene.spawn

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

Inherited from

Scene.spawn

Call Signature

spawn(blueprint, options?): Entity

Defined in: Scene.ts:409

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

blueprint

Blueprint<void>

options?

SpawnOptions

Returns

Entity

Inherited from

Scene.spawn

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

Inherited from

Scene.spawn

---

startLoading()

startLoading(): void

Defined in: LoadingScene.ts:123

Kick off asset loading. While a load is in flight, subsequent calls are no-ops. After a load failure the guard is released, so calling startLoading() from onLoadError (or from a retry button) kicks off a fresh load against the same target.

Usually called once from onEnter after spawning the loading UI:

override onEnter() {
  this.spawn(LoadingSceneProgressBar);
  this.startLoading();
}

Deferring the call lets you gate the start of the load behind a title screen, “press any key” prompt, intro animation, etc.

Returns

void

---

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

Inherited from

Scene.tryResolveScoped

---

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

Inherited from

Scene.use