Global Functions

Este documento lista las funciones utilitarias globales principales proporcionadas por el entorno de la API de scripting. Cada entrada muestra una breve descripción, detalles de parámetros/retorno y un ejemplo concreto.

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

Convierte un objeto a un tipo de clase específico. El objeto debe ser una instancia o compatible con el constructor proporcionado.

Ejemplo:

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

---

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

Clona un THREE.Object3D y añade el clon a la escena. SpawnOptions puede especificar posición, rotación, escala, visibilidad, retardo y padre.

Ejemplo:

    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

Elimina y opcionalmente libera un THREE.Object3D de la escena. DestroyOptions puede incluir un retardo y banderas de liberación.

Ejemplo:

    // Eliminar inmediatamente y liberar recursos
    destroy(clone);

    // O programar la eliminación después de 1 segundo
    destroy(clone, { delay: 1000 });

---

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

Programa la ejecución de action después de interval milisegundos. Devuelve un CancellationHandler (una función sin argumentos) que cancela la ejecución programada si se invoca antes de su ejecución.

Ejemplo:

    const cancel = delayed((msg: string) => console.log(msg), 1500, 'Hola después de 1.5s');

Llama a cancel(); para abortar antes de la ejecución.

---

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

Devuelve un contenedor limitado de action que asegura que solo se ejecute una vez cada interval milisegundos.

Ejemplo:

    const throttledLog = throttled((position) => console.log('Posición del ratón', position), 500);
    if (Input.mouse.isButtonPressed(MouseButton.Left)) {
        throttledLog();
    }

Funciones de Observador

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

Emite un mensaje en la cola de observables para sender. Los suscriptores que estén escuchando a sender recibirán data.

Ejemplo:

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

---

subscribe(sender: string): void

Suscribe el script actual a los mensajes emitidos por un sender específico. Una vez suscrito, tu script puede reaccionar a estos mensajes usando el hook de ciclo de vida observe(event: any).

Ejemplo:

    // Suscribirse a actualizaciones y luego manejarlas en tu handler de mensajes
    subscribe('scoreUpdate');

---

unsubscribe(sender: string): void

Cancela la suscripción del script actual a los mensajes emitidos por sender.

Ejemplo:

    unsubscribe('scoreUpdate');

Funciones de Animación

startAnimationSession(model: ModelElement): Promise<boolean>

Inicia una sesión de animación para el ModelElement proporcionado. Resuelve en true cuando la sesión se inicia con éxito.

Ejemplo:

    (async () => {
      const success = await startAnimationSession(myModel);
      if (success) {
        console.log('Sesión de animación iniciada');
      } else {
        console.warn('No se pudo iniciar la sesión de animación');
      }
    })();