Documentation / scene / ScriptingSystem

Class: ScriptingSystem

Defined in: libs/scene/src/app/scriptingsystem.ts:121

Script system that resolves, loads, and manages lifecycle of runtime scripts.

Responsibilities:

• Resolves module IDs to URLs via ScriptRegistry
• Dynamically imports modules and instantiates a RuntimeScript (default export)
• Tracks attachments between hosts and script instances
• Bridges script lifecycle hooks: onCreated, onAttached, onDetached, onDestroy, onUpdate
• Auto-detaches scripts when a host is disposed

Notes:

• Multiple hosts can reference the same RuntimeScript instance; destruction occurs when the last host detaches.
• Errors during load/attach/update are caught and logged; an optional onLoadError callback can be provided.

Constructors

Constructor

new ScriptingSystem(opts?): ScriptingSystem

Defined in: libs/scene/src/app/scriptingsystem.ts:136

Constructs a new scripting system.

Parameters

opts?

ScriptingSystemOptions = {}

Optional configuration.

Returns

ScriptingSystem

Accessors

registry

Get Signature

get registry(): ScriptRegistry

Defined in: libs/scene/src/app/scriptingsystem.ts:150

Accessor for the underlying script registry used for module resolution.

Returns

ScriptRegistry

Methods

loadRuntimeScriptClass()

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

Defined in: libs/scene/src/app/scriptingsystem.ts:158

Loads a runtime script class from file

Type Parameters

T

T extends IDisposable = IDisposable

Parameters

module

string

file path

Returns

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

The runtime script class or null

---

attachScriptIndirect()

attachScriptIndirect<T>(host, classInfo, config?): Promise<RuntimeScript<T>>

Defined in: libs/scene/src/app/scriptingsystem.ts:194

Creates a script from a dynamic loaded class and attachs it to a host and returns the RuntimeScript instance.

Type Parameters

T

T extends IDisposable

Host type.

Parameters

host

T

The host object to attach the script to.

classInfo

The dynamic loaded class information

url

string

id

string

cls

GenericConstructor<RuntimeScript<T>>

config?

Nullable<RuntimeScriptConfig>

Returns

Promise<RuntimeScript<T>>

The instantiated RuntimeScript<T> or null on failure.

---

attachScript()

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

Defined in: libs/scene/src/app/scriptingsystem.ts:289

Attaches a script to a host and returns the RuntimeScript instance.

Process:

1. Resolve module ID to a runtime URL via the registry.
2. Dynamically import the module.
3. Instantiate the default export if it is a constructor.
4. If this is the first time the instance is seen, call onCreated().
5. Link the instance to the host, and call onAttached(host).
6. Subscribe to the host's 'dispose' event to auto-detach.

If the module cannot be resolved or does not export a default RuntimeScript subclass, a warning is logged and null is returned.

Type Parameters

T

T extends IDisposable

Host type.

Parameters

host

T

The host object to attach the script to.

module

string

Module identifier used by the registry (logical ID or path).

config?

Nullable<RuntimeScriptConfig>

Returns

Promise<RuntimeScript<T>>

The instantiated RuntimeScript<T> or null on failure.

---

attachDeclarativeScript()

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

Defined in: libs/scene/src/app/scriptingsystem.ts:310

Attaches a serialized script declaration once for a host.

Repeated or concurrent calls with the same module, configuration and occurrence return the existing instance. The occurrence distinguishes duplicate declarations that intentionally appear more than once on the same host.

Type Parameters

T

T extends IDisposable

Parameters

host

T

Host object to attach the script to.

module

string

Logical script module identifier.

config?

Nullable<RuntimeScriptConfig>

Serialized script configuration.

occurrence?

number = 0

Zero-based occurrence among equivalent declarations on the host.

Returns

Promise<RuntimeScript<T>>

---

synchronizeDeclarativeScripts()

synchronizeDeclarativeScripts<T>(host, activeKeys): void

Defined in: libs/scene/src/app/scriptingsystem.ts:367

Detaches declarative script instances whose keys are no longer present on a host.

Type Parameters

T

T extends IDisposable

Parameters

host

T

Host whose serialized declarations changed.

activeKeys

ReadonlySet<string>

Complete set of declaration keys currently present on the host.

Returns

void

---

detachScript()

detachScript<T>(host, idOrInstance?): void

Defined in: libs/scene/src/app/scriptingsystem.ts:394

Detaches script(s) from a host.

Behavior:

• If idOrInstance is omitted, detaches all scripts from the host.
• If a module ID is provided, detaches only the matching script.
• If a RuntimeScript instance is provided, detaches that instance.
• Invokes onDetached(host) on each detached instance.
• If the instance has no remaining hosts, invokes onDestroy() and disposes tracking.

Type Parameters

T

T extends IDisposable

Host type.

Parameters

host

T

The host to detach from.

idOrInstance?

string | RuntimeScript<T>

Optional module ID or script instance to target.

Returns

void

---

getScriptObjects()

getScriptObjects<T>(host): T[]

Defined in: libs/scene/src/app/scriptingsystem.ts:454

Get all script instances attached to a host.

Type Parameters

T

T extends RuntimeScript<any>

Expected script type.

Parameters

host

unknown

The host whose scripts to retrieve.

Returns

T[]

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

---

update()

update(deltaTime, elapsedTime): void

Defined in: libs/scene/src/app/scriptingsystem.ts:468

Ticks all attached script instances.

Calls onUpdate(deltaTime, elapsedTime) on every attached script instance across all hosts. Exceptions thrown by a script are caught and logged, allowing other scripts to continue updating.

Parameters

deltaTime

number

Time in seconds since last update.

elapsedTime

number

Total time in seconds since start.

Returns

void

---

detachAllScripts()

detachAllScripts(): void

Defined in: libs/scene/src/app/scriptingsystem.ts:488

Detaches all scripts from all hosts.

Iteratively calls ScriptingSystem.detachScript on each host until no attachments remain.

Returns

void