Documentation / scene / ScriptingSystem

Class: ScriptingSystem

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

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

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

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

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

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

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.

---

detachScript()

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

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

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

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

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

Detaches all scripts from all hosts.

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

Returns

void