LoadingScene

Defined in: LoadingScene.ts:43

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

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

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

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

Name for debugging/inspection.

Overrides

Scene.name

---

pauseBelow

readonly pauseBelow: boolean = true

Defined in: Scene.ts:32

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

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

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

Inherited from

Scene.preload

---

target

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

Defined in: LoadingScene.ts:52

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

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

Transition used for the loading → target handoff.

---

transparentBelow

readonly transparentBelow: boolean = false

Defined in: Scene.ts:35

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

Inherited from

Scene.transparentBelow

Accessors

assets

Get Signature

get assets(): AssetManager

Defined in: Scene.ts:87

Convenience accessor for the AssetManager.

Returns

AssetManager

Inherited from

Scene.assets

---

context

Get Signature

get context(): EngineContext

Defined in: Scene.ts:62

Access the EngineContext.

Returns

EngineContext

Inherited from

Scene.context

---

isPaused

Get Signature

get isPaused(): boolean

Defined in: Scene.ts:67

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

Whether a scene transition is currently running.

Returns

boolean

Inherited from

Scene.isTransitioning

---

progress

Get Signature

get progress(): number

Defined in: LoadingScene.ts:99

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

Returns

number

Methods

_addExistingEntity()

_addExistingEntity(entity): void

Defined in: Scene.ts:166

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

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

Internal

Destroy all entities — used during scene exit.

Returns

void

Inherited from

Scene._destroyAllEntities

---

_flushDestroyQueue()

_flushDestroyQueue(): void

Defined in: Scene.ts:343

Internal

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

Returns

void

Inherited from

Scene._flushDestroyQueue

---

_onEntityEvent()

_onEntityEvent(eventName, data, entity): void

Defined in: Scene.ts:248

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

Internal

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

Parameters

entity

Entity

Returns

void

Inherited from

Scene._queueDestroy

---

_registerScoped()

_registerScoped<T>(key, value): void

Defined in: Scene.ts:288

Internal

Register a scene-scoped service. Called from a plugin’s beforeEnter hook to make per-scene state (render tree, physics world) resolvable via Component.use(key).

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

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

Internal

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

Parameters

context

EngineContext

Returns

void

Inherited from

Scene._setContext

---

afterRestore()?

optional afterRestore(data, resolve): void

Defined in: Scene.ts:278

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

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

Mark an entity for destruction. Deferred to endOfFrame flush.

Parameters

entity

Entity

Returns

void

Inherited from

Scene.destroyEntity

---

findEntities()

Call Signature

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

Defined in: Scene.ts:213

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

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

Find entities by tag.

Parameters

tag

string

Returns

Entity[]

Inherited from

Scene.findEntitiesByTag

---

findEntity()

findEntity(name): Entity | undefined

Defined in: Scene.ts:196

Find entity by name (first match).

Parameters

name

string

Returns

Entity | undefined

Inherited from

Scene.findEntity

---

getEntities()

getEntities(): ReadonlySet<Entity>

Defined in: Scene.ts:191

Get all active entities.

Returns

ReadonlySet<Entity>

Inherited from

Scene.getEntities

---

on()

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

Defined in: Scene.ts:227

Subscribe to bubbled entity events at the scene level. Handler receives (data, emittingEntity).

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

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

Returns

void

Inherited from

Scene.onEnter

---

onExit()

onExit(): void

Defined in: LoadingScene.ts:151

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

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

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

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

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

Returns

void

Inherited from

Scene.onResume

---

serialize()?

optional serialize(): unknown

Defined in: Scene.ts:275

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

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?): Entity

Defined in: Scene.ts:117

Spawn a new entity in this scene.

Parameters

name?

string

Returns

Entity

Inherited from

Scene.spawn

Call Signature

spawn<P>(blueprint, params): Entity

Defined in: Scene.ts:118

Spawn a new entity in this scene.

Type Parameters

P

P

Parameters

blueprint

Blueprint<P>

params

P

Returns

Entity

Inherited from

Scene.spawn

Call Signature

spawn(blueprint): Entity

Defined in: Scene.ts:119

Spawn a new entity in this scene.

Parameters

blueprint

Blueprint<void>

Returns

Entity

Inherited from

Scene.spawn

Call Signature

spawn<E, P>(Class, params): E

Defined in: Scene.ts:121

Spawn an entity subclass with setup params.

Type Parameters

E

E extends Entity

P

P

Parameters

Class

() => E & object

params

P

Returns

E

Inherited from

Scene.spawn

Call Signature

spawn<E>(Class): E

Defined in: Scene.ts:126

Spawn an entity subclass without setup params.

Type Parameters

E

E extends Entity

Parameters

Class

() => E

Returns

E

Inherited from

Scene.spawn

---

startLoading()

startLoading(): void

Defined in: LoadingScene.ts:120

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