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 = 500;
  readonly transition = fade({ duration: 300 });
  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

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

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 ms 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:79

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

Inherited from

Scene.pauseBelow

---

paused

paused: boolean = false

Defined in: Scene.ts:104

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

Inherited from

Scene.paused

---

preload?

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

Defined in: Scene.ts:98

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

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

Inherited from

Scene.transparentBelow

Accessors

assets

Get Signature

get assets(): AssetManager

Defined in: Scene.ts:151

Convenience accessor for the AssetManager.

Returns

AssetManager

Inherited from

Scene.assets

---

context

Get Signature

get context(): EngineContext

Defined in: Scene.ts:126

Access the EngineContext.

Returns

EngineContext

Inherited from

Scene.context

---

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

Inherited from

Scene.isPaused

---

isTransitioning

Get Signature

get isTransitioning(): boolean

Defined in: Scene.ts:145

Whether a scene transition is currently running.

Returns

boolean

Inherited from

Scene.isTransitioning

---

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

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

Inherited from

Scene._clearScopedServices

---

_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

Inherited from

Scene._destroyAllEntities

---

_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

Inherited from

Scene._flushDestroyQueue

---

_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

Inherited from

Scene._observeEntityEvent

---

_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

Inherited from

Scene._onEntityEvent

---

_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

Inherited from

Scene._queueDestroy

---

_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

Inherited from

Scene._registerKey

---

_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

Inherited from

Scene._registerScoped

---

_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

Inherited from

Scene._resolveScoped

---

_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

Inherited from

Scene._setContext

---

_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

Inherited from

Scene._setEntityEventObserver

---

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

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

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

Inherited from

Scene.emit

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

Inherited from

Scene.emit

---

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

Inherited from

Scene.findByKey

---

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

Inherited from

Scene.findEntities

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

Inherited from

Scene.findEntities

---

findEntitiesByTag()

findEntitiesByTag(tag): Entity[]

Defined in: Scene.ts:386

Find entities by tag.

Parameters

tag

string

Returns

Entity[]

Inherited from

Scene.findEntitiesByTag

---

findEntity()

findEntity(name): Entity | undefined

Defined in: Scene.ts:378

Find entity by name (first match).

Parameters

name

string

Returns

Entity | undefined

Inherited from

Scene.findEntity

---

getEntities()

getEntities(): ReadonlySet<Entity>

Defined in: Scene.ts:373

Get all active entities.

Returns

ReadonlySet<Entity>

Inherited from

Scene.getEntities

---

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

Inherited from

Scene.on

---

onEnter()?

optional onEnter(): void

Defined in: Scene.ts:474

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

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

Returns

void

Inherited from

Scene.onPause

---

onProgress()?

optional onProgress(ratio): void

Defined in: Scene.ts:471

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

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

Returns

void

Inherited from

Scene.onResume

---

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

Inherited from

Scene.registerScoped

---

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

Inherited from

Scene.serialize

---

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

Inherited from

Scene.service

---

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

Inherited from

Scene.spawn

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

Inherited from

Scene.spawn

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

Inherited from

Scene.spawn

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

Inherited from

Scene.spawn

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

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