Documentation / scene / Engine

Class: Engine

Defined in: libs/scene/src/app/engine.ts:76

Core engine class managing scripting, serialization, and rendering.

Responsibilities:

• Manages a ScriptingSystem for dynamic script attachment and lifecycle.
• Manages a ResourceManager for loading scenes and assets.
• Maintains a list of active renderable objects to be rendered each frame.
• Provides methods to attach/detach scripts, update scripts, load scenes, and read files.
• Supports enabling/disabling of runtime operations.

Remarks

The engine can be configured with a virtual file system (VFS) and script root path. It exposes methods to manage scripts on host objects, update scripts each frame, load scenes from files, and render active objects.

Constructors

Constructor

new Engine(VFS?, scriptsRoot?, enabled?): Engine

Defined in: libs/scene/src/app/engine.ts:95

Creates a new runtime manager.

Parameters

VFS?

VFS

Optional virtual file system passed to the internal ScriptingSystem.

scriptsRoot?

string

Optional scripts root path within the VFS. Defaults as in ScriptingSystem.

enabled?

boolean

Whether runtime operations are active. Defaults to true.

Returns

Engine

Properties

_activeRenderables

protected _activeRenderables: object[]

Defined in: libs/scene/src/app/engine.ts:83

renderable

renderable: RenderFunc | DRef<IRenderable>

hook

hook: IRenderHook

Accessors

scriptingSystem

Get Signature

get scriptingSystem(): ScriptingSystem

Defined in: libs/scene/src/app/engine.ts:109

Exposes the instance of ScriptingSystem.

Returns

ScriptingSystem

---

VFS

Get Signature

get VFS(): VFS

Defined in: libs/scene/src/app/engine.ts:115

Exposes the virtual file system used by the underlying ScriptingSystem's registry.

Returns

VFS

Set Signature

set VFS(vfs): void

Defined in: libs/scene/src/app/engine.ts:118

Parameters

vfs

VFS

Returns

void

---

resourceManager

Get Signature

get resourceManager(): ResourceManager

Defined in: libs/scene/src/app/engine.ts:129

Exposes the instance of ResourceManager.

Returns

ResourceManager

---

msdfTextAtlasManager

Get Signature

get msdfTextAtlasManager(): MSDFTextAtlasManager

Defined in: libs/scene/src/app/engine.ts:135

Exposes the shared runtime MSDF text atlas manager.

Returns

MSDFTextAtlasManager

---

screen

Get Signature

get screen(): ScreenAdapter

Defined in: libs/scene/src/app/engine.ts:190

Exposes the active ScreenAdapter.

Returns

ScreenAdapter

Methods

releaseFontAsset()

releaseFontAsset(font): boolean

Defined in: libs/scene/src/app/engine.ts:147

Releases a loaded font asset from the resource cache and disposes its shared MSDF atlas textures.

Existing scene nodes that still reference this font asset are not updated automatically. Call this only after you have stopped using the font, or when you intentionally want it to rebuild later.

Parameters

font

string

The loaded font asset path to release.

Returns

boolean

true if either the atlas cache or the font cache had an entry to remove.

---

configureMSDFAtlas()

configureMSDFAtlas(font, pageSize, glyphSize, distanceRange?, padding?): boolean

Defined in: libs/scene/src/app/engine.ts:172

Configures the MSDF atlas for a given font asset, creating or replacing the atlas as needed.

This is useful to customize the glyph size, atlas page size, distance range, and padding for MSDF text rendering. Existing scene nodes that reference this font asset will use the updated atlas automatically.

Parameters

font

string

The font asset path to configure the MSDF atlas for.

pageSize

number

The size of each atlas page in pixels (e.g., 512, 1024).

glyphSize

number

The size of each glyph in pixels (e.g., 32, 64).

distanceRange?

number

The distance range for MSDF generation. Defaults to 4.

padding?

number

The padding between glyphs in the atlas in pixels. Defaults to 2.

Returns

boolean

true if the atlas was successfully configured, or false if the font asset was not found.

Remarks

The font asset must be loaded and available in the resource manager for the atlas to be configured.

---

detachAllScripts()

detachAllScripts(): void

Defined in: libs/scene/src/app/engine.ts:202

Detaches all scripts from all hosts, if enabled.

No-op when enabled === false.

Returns

void

---

loadRuntimeScriptClass()

loadRuntimeScriptClass<T>(module): Promise<{ url: string; cls: GenericConstructor<RuntimeScript<T>>; }>

Defined in: libs/scene/src/app/engine.ts:212

Loads a runtime script class from file

Type Parameters

T

T extends IDisposable = IDisposable

Parameters

module

string

file path

Returns

Promise<{ url: string; cls: GenericConstructor<RuntimeScript<T>>; }>

The runtime script class or null

---

attachScript()

attachScript<T>(host, module, config?): Promise<RuntimeScript<T>>

Defined in: libs/scene/src/app/engine.ts:228

Attaches a script module to the given host, if enabled.

When disabled, this method resolves to null without side effects.

Type Parameters

T

T extends IDisposable

Host type.

Parameters

host

T

Host object to attach the script to.

module

string

Module identifier to resolve and load.

config?

Nullable<RuntimeScriptConfig>

Optional configuration passed to the script instance.

Returns

Promise<RuntimeScript<T>>

The RuntimeScript<T> instance, or null if disabled or on failure.

---

detachScript()

detachScript<T>(host, idOrInstance): void

Defined in: libs/scene/src/app/engine.ts:244

Detaches a script from a host, by module ID or instance, if enabled.

No-op when disabled.

Type Parameters

T

T extends IDisposable

Host type.

Parameters

host

T

Host to detach from.

idOrInstance

string | RuntimeScript<T>

Target script by module ID or instance reference.

Returns

void

---

getScriptObjects()

getScriptObjects<T>(host): T[]

Defined in: libs/scene/src/app/engine.ts:258

Gets all scripts attached to a host.

Delegates to ScriptingSystem.getScriptObjects.

Type Parameters

T

T extends RuntimeScript<any>

Expected script type.

Parameters

host

unknown

Host object to query.

Returns

T[]

Script instances attached to the host, or an empty array.

---

update()

update(deltaTime, elapsedTime): void

Defined in: libs/scene/src/app/engine.ts:267

Ticks all attached scripts by calling their onUpdate hooks, if enabled.

Parameters

deltaTime

number

Time since last update in Seconds.

elapsedTime

number

Total elapsed time in Seconds.

Returns

void

---

loadSceneFromFile()

loadSceneFromFile(path): Promise<Scene>

Defined in: libs/scene/src/app/engine.ts:281

Loads a scene from a file path.

Concurrent requests for the same normalized path share the same loading promise. Scripts declared on the scene and its nodes are attached after the scene is loaded.

Parameters

path

string

Scene file path in the current VFS.

Returns

Promise<Scene>

The loaded scene, or null when loading fails.

---

setRenderable()

setRenderable(renderable, layer?, hook?): void

Defined in: libs/scene/src/app/engine.ts:298

Sets or clears the renderable for a render layer.

Passing null clears the layer. Object renderables are held through a strong reference wrapper, while render functions are stored directly.

Parameters

renderable

IRenderable | RenderFunc

Renderable object or render function to assign, or null to clear.

layer?

number = 0

Render layer index. Defaults to 0.

hook?

IRenderHook

Optional render hook invoked before and after this layer renders.

Returns

void

---

readFile()

readFile<T>(path, encoding?): Promise<T extends "binary" ? ArrayBuffer : string>

Defined in: libs/scene/src/app/engine.ts:332

Reads a file from the current VFS.

Type Parameters

T

T extends "utf8" | "binary" | "base64" = "binary"

Requested read encoding.

Parameters

path

string

File path to read.

encoding?

T

Optional read encoding. Defaults to binary.

Returns

Promise<T extends "binary" ? ArrayBuffer : string>

The file content, or null when the read fails.

---

startup()

startup(startupScene?, splashScreen?, startupScript?): Promise<void>

Defined in: libs/scene/src/app/engine.ts:350

Starts the runtime by optionally showing a splash screen, running a startup script, and loading the startup scene.

Parameters

startupScene?

string

Optional scene path rendered on layer 0 after startup completes.

splashScreen?

string

Optional scene path rendered on a temporary splash layer during startup.

startupScript?

string

Optional startup script module path. A trailing .ts or .js extension is removed before loading.

Returns

Promise<void>

---

render()

render(): void

Defined in: libs/scene/src/app/engine.ts:381

Renders all active render layers.

Each layer's beforeRender hook can return false to skip rendering that layer. The afterRender hook is invoked after the render attempt.

Returns

void