Global Functions

This document lists core global utility functions provided by the scripting API environment. Each entry shows a short description, parameter/return details, and a concrete example.

cast<T>(object: any, classType: T): T

Casts an object to a specific class type. The object must be an instance of, or compatible with, the provided constructor.

Example:

const model = cast<ModelElement>(someObj, ModelElement);

---

spawn(obj: THREE.Object3D, options?: SpawnOptions): THREE.Object3D

Clones a THREE.Object3D and adds the clone to the scene. SpawnOptions can specify position, rotation, scale, visibility, delay, and parent.

Example:

const clone = spawn(originalMesh, {
  position: new THREE.Vector3(1, 2, 3),
  rotation: new THREE.Euler(0, Math.PI / 2, 0),
  scale: 1.5,
  visible: true,
  delay: 200,
  parent: scene
});

---

destroy(obj: THREE.Object3D, options?: DestroyOptions): void

Removes and optionally disposes of a THREE.Object3D from the scene. DestroyOptions may include a delay and disposal flags.

Example:

// Remove immediately and dispose resources
destroy(clone);

// Or schedule removal after 1 second
destroy(clone, { delay: 1000 });

---

delayed(action: Function, interval: number, ...args: any): CancellationHandler

Schedules action to run after interval milliseconds. Returns a CancellationHandler (a zero-arg function) that cancels the scheduled call if invoked before execution.

Example:

const cancel = delayed((msg: string) => console.log(msg), 1500, 'Hello after 1.5s');

Call cancel(); to abort before execution

---

throttled(action: Function, interval: number): ThrottledFunction

Returns a throttled wrapper around action so it will execute at most once every interval milliseconds.

Example:

const throttledLog = throttled((position) => console.log('Mouse position', position), 500);
if (Input.mouse.isButtonPressed(MouseButton.Left)) {
    throttledLog();
}

Observer Functions

emit(sender: string, data: any): void

Emits a message on the observables queue for sender. Subscribers listening for sender will receive data.

Example:

emit('scoreUpdate', { score: 123, playerId: 'player1' });

---

subscribe(sender: string): void

Subscribes the current script to messages emitted by a specific sender. Once subscribed, your script can react to these messages using the observe(event: any) lifecycle hook.

Example:

// Subscribe to updates then handle them in your message handler
subscribe('scoreUpdate');

---

unsubscribe(sender: string): void

Unsubscribes the current script from messages emitted by sender.

Example:

unsubscribe('scoreUpdate');

Animation Functions

startAnimationSession(model: ModelElement): Promise<boolean>

Begins an animation session for the provided ModelElement. Resolves to true when the session has started successfully.

Example:

(async () => {
  const success = await startAnimationSession(myModel);
  if (success) {
    console.log('Animation session started');
  } else {
    console.warn('Failed to start animation session');
  }
})();