Crear componentes personalizados

Si eres nuevo en scripting, te recomendamos encarecidamente leer primero las siguientes guías:

• Fundamentos de Typescript
• Needle Engine para Desarrolladores de Unity

Si sabes lo que estás haciendo, siéntete libre de ir directamente a la documentación de la API de Needle Engine.

El código en tiempo de ejecución para Needle Engine está escrito en TypeScript (recomendado) o JavaScript. Generamos automáticamente componentes stub C# a partir de eso, que puedes añadir a GameObjects en el editor. Los componentes C# y sus datos son recreados por el tiempo de ejecución como componentes JavaScript con los mismos datos y adjuntados a objetos three.js.

Tanto los componentes personalizados como los componentes integrados de Unity pueden mapearse a componentes JavaScript de esta manera. Por ejemplo, las asignaciones para muchos componentes integrados relacionados con animación, renderizado o física ya están incluidas en Needle Engine.

Si deseas seguir los siguientes ejemplos sin tener que instalar nada, simplemente haz clic en el siguiente enlace:

• Crear espacio de trabajo virtual para seguir el código.

Nuestro motor de tiempo de ejecución web adopta un modelo de componentes similar a Unity y, por lo tanto, proporciona mucha funcionalidad que resultará familiar. Los componentes adjuntos a los objetos Object3D de three tienen métodos de ciclo de vida como awake, start, onEnable, onDisable, update y lateUpdate que puedes implementar. También puedes usar Coroutines.

Cuando no necesitas escribir código

A menudo, las escenas interactivas se pueden realizar utilizando Events en Unity y llamando a métodos en componentes integrados. Un ejemplo típico es reproducir una animación al hacer clic en un botón: creas un botón, añades un evento Click en el inspector y haces que llame a Animator.SetTrigger o similar para reproducir una animación específica.

Needle Engine traduce Unity Events en llamadas a métodos JavaScript, lo que hace que este flujo de trabajo sea muy rápido y flexible: configura tus eventos como de costumbre y, cuando se activen, funcionarán igual que en Unity.

Un ejemplo de un Button Click Event que funciona de inmediato en Needle Engine — no se necesita código.

Crear un nuevo componente

Los scripts se escriben en TypeScript (recomendado) o JavaScript. Hay dos formas de añadir scripts personalizados a tu proyecto:

• Simplemente añade un archivo con extensión .ts o .js dentro de src/scripts/ en el directorio de tu proyecto generado, por ejemplo src/scripts/MyFirstScript.ts

• Específico de Unity: Organiza tu código en NPM Definition Files (paquetes npm). Estos te ayudan a modularizar y reutilizar código entre proyectos y, si estás familiarizado con el desarrollo web, de hecho son paquetes npm regulares que se instalan localmente. En Unity puedes crear archivos NpmDef a través de Create > NPM Definition y luego añadir archivos TypeScript haciendo clic derecho en un archivo NpmDef y seleccionando Create > TypeScript. Consulta este capítulo para más información.

En ambos enfoques, los directorios de origen son vigilados para detectar cambios y los componentes stub C# o paneles de Blender se regeneran cada vez que se detecta un cambio. Los cambios en los archivos de origen también resultan en una recarga en caliente del sitio web en ejecución – no tienes que esperar a que Unity recompile los componentes C#. Esto hace que iterar sobre el código sea prácticamente instantáneo.

Incluso puedes tener múltiples tipos de componentes dentro de un mismo archivo (por ejemplo, puedes declarar export class MyComponent1 y export class MyOtherComponent en el mismo archivo Typescript).

Si eres nuevo escribiendo Javascript o Typescript, te recomendamos leer primero la guía Tipscript Essentials Guide antes de continuar con esta guía.

import { Behaviour, serializable } from "@needle-tools/engine";

export class Rotate extends Behaviour
{
    @serializable()
    speed : number = 1;

    start(){
        // logging this is useful for debugging in the browser.
        // You can open the developer console (F12) to see what data your component contains
        console.log(this);
    }

    // update will be called every frame
    update(){
        this.gameObject.rotateY(this.context.time.deltaTime * this.speed);
    }
}

import { Behaviour } from "@needle-tools/engine";

export class PrintNumberComponent extends Behaviour
{
    start(){
      this.printNumber(42);
    }

    private printNumber(myNumber : number){
        console.log("My Number is: " + myNumber);
    }
}

Arquitectura de Componentes

Los componentes se añaden a los Object3Ds de three.js. Esto es similar a cómo se añaden los Componentes en Unity a los GameObjects. Por lo tanto, cuando queremos acceder a un Object3D de three.js, podemos acceder a él como this.gameObject, que devuelve el Object3D al que está adjunto el componente.

Nota: Establecer visible en falso en un Object3D actuará como SetActive(false) en Unity, lo que significa que también deshabilitará todos los componentes actuales en este objeto y sus hijos. Los eventos de actualización para componentes inactivos no se llaman hasta que visible se establece nuevamente en verdadero. Si quieres ocultar un objeto sin afectar a los componentes, simplemente puedes deshabilitar el componente Renderer de Needle Engine.

Métodos del ciclo de vida

Ten en cuenta que los métodos del ciclo de vida solo se llaman cuando se declaran. Por lo tanto, solo declara los métodos del ciclo de vida update cuando sean realmente necesarios, de lo contrario, puede perjudicar el rendimiento si tienes muchos componentes con bucles de actualización que no hacen nada.

Métodos de eventos de física

Métodos de eventos de entrada

Métodos de eventos XR

requiere Needle Engine >= 3.32.0

Eventos XR adicionales

Coroutines

Las Coroutines se pueden declarar utilizando la Sintaxis de Generadores de JavaScript. Para iniciar una coroutine, llama a this.startCoroutine(this.myRoutineName());

Ejemplo

import { Behaviour, FrameEvent } from "@needle-tools/engine";

export class Rotate extends Behaviour {

    start() {
        // the second argument is optional and allows you to specifiy
        // when it should be called in the current frame loop
        // coroutine events are called after regular component events of the same name
        // for example: Update coroutine events are called after component.update() functions
        this.startCoroutine(this.rotate(), FrameEvent.Update);
    }

    // this method is called every frame until the component is disabled
    *rotate() {
        // keep looping forever
        while (true) {
            yield;
        }
    }
}

Para detener una coroutine, sal de la rutina retornando de ella, o guarda en caché el valor de retorno de startCoroutine y llama a this.stopCoroutine(<...>). Todas las Coroutines se detienen en onDisable / al deshabilitar un componente.

Hooks especiales del ciclo de vida

Needle Engine también expone algunos hooks del ciclo de vida que puedes usar para engancharte al bucle de actualización sin tener que escribir un componente completo. Estos hooks pueden insertarse en cualquier punto de tu aplicación web (por ejemplo, en el ámbito de nivel superior o en un componente svelte)

Por ejemplo (Ver ejemplo en stackblitz)

// this can be put into e.g. main.ts or a svelte component (similar to onMount)
import { onStart, onUpdate, onBeforeRender, onAfterRender } from "@needle-tools/engine"

onStart(ctx => console.log("Hello Scene", ctx.scene));

onUpdate(ctx => {
    // do something... e.g. access the frame # or deltatime via ctx.time
    console.log("UPDATE", ctx.time.frame);
});

onBeforeRender(ctx => {
    // this event is only called once because of the { once: true } argument
    console.log("ON BEFORE RENDER", ctx.time.frame);
}, { once: true } );

// Every event hook returns a method to unsubscribe from the event
const unsubscribe = onAfterRender(ctx => {
    console.log("ON AFTER RENDER", ctx.time.frame);
});
// Unsubscribe from the event at any time
setTimeout(()=> unsubscribe(), 1000);

Encontrar, añadir y eliminar componentes

Para acceder a otros componentes, utiliza los métodos estáticos en GameObject o los métodos this.gameObject. Por ejemplo, para acceder a un componente Renderer en el padre, utiliza GameObject.getComponentInParent(this.gameObject, Renderer) o this.gameObject.getComponentInParent(Renderer).

Ejemplo:

import { Behaviour, GameObject, Renderer } from "@needle-tools/engine";

export class MyComponent extends Behaviour {

    start() {
        const renderer = GameObject.getComponentInParent(this.gameObject, Renderer);
        console.log(renderer);
    }
}

Algunos de los métodos disponibles:

Three.js y el HTML DOM

El contexto se refiere al tiempo de ejecución dentro de un web component. La escena de three.js vive dentro de un componente HTML personalizado llamado <needle-engine> (consulta el index.html en tu proyecto). Puedes acceder al web component <needle-engine> utilizando this.context.domElement.

Esta arquitectura permite tener potencialmente múltiples escenas WebGL de Needle en la misma página web, que pueden ejecutarse por sí solas o comunicarse entre sí como partes de tu página web.

Acceder a la escena

Para acceder a la escena actual desde un componente, utilizas this.scene, que es equivalente a this.context.scene; esto te da el objeto raíz de la escena de three.js.

Para recorrer la jerarquía desde un componente, puedes iterar sobre los hijos de un objeto con un bucle for:

for(let i = 0; i < this.gameObject.children; i++)
    console.log(this.gameObject.children[i]);

o puedes iterar usando el equivalente a foreach:

for(const child of this.gameObject.children) {
    console.log(child);
}

También puedes usar métodos específicos de three.js para iterar rápidamente todos los objetos recursivamente usando el método traverse:

import { Object3D } from "three";
this.gameObject.traverse((obj: Object3D) => console.log(obj));

o para recorrer solo objetos visibles, utiliza traverseVisible en su lugar.

Otra opción que es bastante útil cuando solo quieres iterar objetos que son renderizables es consultar todos los componentes renderer e iterar sobre ellos de la siguiente manera:

import { Renderer } from "@needle-tools/engine";
for(const renderer of this.gameObject.getComponentsInChildren(Renderer))
    console.log(renderer);

Para más información sobre cómo obtener componentes, consulta la siguiente sección.

Tiempo

Usa this.context.time para acceder a los datos de tiempo:

• this.context.time.time es el tiempo transcurrido desde que la aplicación comenzó a ejecutarse
• this.context.time.deltaTime es el tiempo que ha pasado desde el último frame
• this.context.time.frameCount es el número de frames que han pasado desde que la aplicación comenzó
• this.context.time.realtimeSinceStartup es el tiempo sin escalar desde que la aplicación comenzó a ejecutarse

También es posible usar this.context.time.timeScale para ralentizar deliberadamente el tiempo para efectos de cámara lenta, por ejemplo.

Entrada

Recibe datos de entrada para el objeto en el que se encuentra el componente:

import { Behaviour } from "@needle-tools/engine";
export class MyScript extends Behaviour
{
    onPointerDown() {
        console.log("POINTER DOWN on " + this.gameObject.name);
    }
}

También puedes suscribirte a eventos globales en la enumeración InputEvents de la siguiente manera:

import { Behaviour, InputEvents, NEPointerEvent } from "@needle-tools/engine";

export class MyScript extends Behaviour
{
    onEnable() {
        this.context.input.addEventListener(InputEvents.PointerDown, this.inputPointerDown);
    }

    onDisable() {
        // it is recommended to also unsubscribe from events when your component becomes inactive
        this.context.input.removeEventListener(InputEvents.PointerDown, this.inputPointerDown);
    }

    // @nonSerialized
    inputPointerDown = (evt: NEPointerEvent) => { console.log("POINTER DOWN anywhere on the <needle-engine> element"); }
}

O usa this.context.input si quieres sondear el estado de entrada en cada frame:

import { Behaviour } from "@needle-tools/engine";
export class MyScript extends Behaviour
{
    update() {
        if(this.context.input.getPointerDown(0)){
            console.log("POINTER DOWN anywhere")
        }
    }
}

Si quieres manejar las entradas tú mismo, también puedes suscribirte a todos los eventos que proporciona el navegador (hay muchísimos). Por ejemplo, para suscribirte al evento click del navegador, puedes escribir:

import { Behaviour } from "@needle-tools/engine";
export class MyScript extends Behaviour
{
    onEnable() {
        window.addEventListener("click", this.windowClick);
    }

    onDisable() {
        // unsubscribe again when the component is disabled
        window.removeEventListener("click", this.windowClick);
    }

    windowClick = () => { console.log("CLICK anywhere on the page, not just on <needle-engine>"); }
}

Ten en cuenta que en este caso tienes que manejar todos los casos tú mismo. Por ejemplo, es posible que necesites usar diferentes eventos si tu usuario está visitando tu sitio web en un escritorio, móvil o un dispositivo VR. Needle Engine maneja automáticamente estos casos con los eventos de entrada (por ejemplo, PointerDown se dispara tanto para el clic del ratón, el toque en pantalla y, en el caso de VR, al presionar un botón del controlador).

Raycasting

Utiliza this.context.physics.raycast() para realizar un raycast y obtener una lista de intersecciones. Si no pasas ninguna opción, el raycast se realiza desde la posición del ratón (o la primera posición táctil) en espacio de pantalla utilizando la mainCamera actualmente activa. También puedes pasar un objeto RaycastOptions que tiene varias configuraciones como maxDistance, la cámara a usar o las capas contra las que se debe probar.

Utiliza this.context.physics.raycastFromRay(your_ray) para realizar un raycast utilizando un three.js ray.

Nota: Este tipo de raycast lanza un rayo contra todos los objetos visibles en la escena. No se necesita un motor de física, lo cual es diferente al comportamiento en Unity, donde siempre necesitas colliders para golpear objetos. Si quieres lanzar solo contra colliders de física, utiliza los métodos physics.engine.raycast descritos a continuación.

Consideraciones de rendimiento

Cuando se utilizan las configuraciones de compresión predeterminadas de Needle, se crean y utilizan automáticamente versiones simplificadas de las mallas para el raycasting también. Aun así, algunos tipos de mallas son lentas; por ejemplo, las mallas con skinning o las mallas con blendshapes requieren cálculos costosos para determinar los hits exactos. Considera establecer esos objetos en la capa Ignore Raycast en Unity para evitar el raycasting contra ellos.

Raycasting basado en física

Otra opción es utilizar los métodos de raycast de física que solo devolverán hits con colliders en la escena.

const hit = this.context.physics.engine?.raycast();

Aquí tienes un ejemplo editable de raycast de física

Networking

Se puede acceder a los métodos de Networking a través de this.context.connection. Consulta la documentación de networking para más información.

Acceder a Needle Engine y componentes desde cualquier lugar

Es posible acceder a toda la funcionalidad descrita anteriormente utilizando código JavaScript regular que no esté dentro de los componentes y que se encuentre en otro lugar. Todos los componentes y la funcionalidad del tiempo de ejecución de Needle son accesibles a través del namespace global Needle (puedes escribir console.log(Needle) para obtener una visión general)

Puedes encontrar componentes utilizando Needle.findObjectOfType(Needle.AudioSource), por ejemplo. Se recomienda guardar en caché estas referencias, ya que buscar en toda la escena repetidamente es costoso. Consulta la lista para encontrar, añadir y eliminar componentes arriba.

Para obtener callbacks para la carga inicial de la escena, consulta el siguiente ejemplo:

<needle-engine loadstart="loadingStarted" progress="loadingProgress" loadfinished="loadingFinished"></needle-engine>

<script type="text/javascript">
function loadingStarted() { console.log("START") }
function loadingProgress() { console.log("LOADING...") }
function loadingFinished() { console.log("FINISHED!") }
</script>

También puedes suscribirte al NeedleEngine global (a veces también conocido como ContextRegistry) para recibir un callback cuando se haya creado un contexto de Needle Engine o para acceder a todos los contextos disponibles:

class YourComponentType extends Behaviour {}
//---cut---
import { NeedleEngine, GameObject, Behaviour } from "@needle-tools/engine";

NeedleEngine.addContextCreatedCallback((args) => {
  const context = args.context;
  const scene = context.scene;
  const myInstance = GameObject.getComponentInChildren(scene, YourComponentType);
});

Otra opción es usar el hook del ciclo de vida onInitialized(ctx => {})

También puedes acceder a todos los contextos disponibles a través de NeedleEngine.Registered, que devuelve el array interno. (Ten en cuenta que este array no debe modificarse, pero se puede usar para iterar sobre todos los contextos activos para modificar configuraciones, por ejemplo, establecer todos los contextos en context.isPaused = true)

A continuación, encontrarás una lista de eventos disponibles en el tipo estático NeedleEngine. Puedes suscribirte a estos eventos a través de NeedleEngine.registerCallback(ContextEvent.ContextCreated, (args) => {})

Gizmos

La clase estática Gizmos se puede usar para dibujar líneas, formas y texto, lo cual es principalmente útil para la depuración. Todas las funciones de Gizmos tienen múltiples opciones para, por ejemplo, colores o por cuánto tiempo deben mostrarse en la escena. Internamente se almacenan en caché y se reutilizan.

Serialización / Components en archivos glTF

Para incrustar componentes y recrear componentes con sus tipos correctos en glTF, también necesitamos guardar tipos no primitivos (todo lo que no sea un Number, Boolean o String). Puedes hacerlo añadiendo un decorador @serializable(<type>) encima de tu campo o propiedad.

Ejemplo:

import { Behaviour, serializable, Camera } from "@needle-tools/engine";
import { Object3D } from "three"

export class MyClass extends Behaviour {
    // this will be a "Transform" field in Unity
    @serializable(Object3D) 
    myObjectReference: Object3D | null = null;
    
    // this will be a "Transform" array field in Unity
    // Note that the @serializable decorator contains the array content type! (Object3D and not Object3D[])
    @serializable(Object3D) 
    myObjectReferenceList: Object3D[] | null = null;

    // for component or other objects use the object's type
    @serializable(Camera)
    myCameraComponent: Camera | null = null;
}

Para serializar desde y hacia formatos personalizados, es posible extender la clase TypeSerializer y crear una instancia. Usa super() en el constructor para registrar los tipos soportados.

Nota: Además de los campos que coinciden, las propiedades que coinciden también se exportarán cuando coincidan con campos en el archivo typescript.

Cargando Escenas

En Unity, los Prefabs, SceneAssets y AssetReferences (el sistema Addressable de Unity) referenciados se exportarán automáticamente como archivos glTF (consulta la documentación Export Prefabs).

Estos archivos glTF exportados se serializarán como URIs de cadena plana. Para simplificar la carga de estos desde componentes TypeScript, añadimos el concepto de tipos AssetReference. Se pueden cargar en tiempo de ejecución y, por lo tanto, permiten diferir la carga de partes de tu aplicación o cargar contenido externo.

Ejemplo:

import { Behaviour, serializable, AssetReference } from "@needle-tools/engine";

export class MyClass extends Behaviour {

    // if you export a prefab or scene as a reference from Unity you'll get a path to that asset
    // which you can de-serialize to AssetReference for convenient loading
    @serializable(AssetReference)
    myPrefab?: AssetReference;
    
    async start() {
      // directly instantiate
      const myInstance = await this.myPrefab?.instantiate();

      // you can also just load and instantiate later
      // const myInstance = await this.myPrefab.loadAssetAsync();
      // this.gameObject.add(myInstance)
      // this is useful if you know that you want to load this asset only once because it will not create a copy
      // since ``instantiate()`` does create a copy of the asset after loading it
    }  
}

Los AssetReferences se almacenan en caché por URI, por lo que si referencias el mismo glTF/Prefab exportado en múltiples componentes/scripts, solo se cargará una vez y luego se reutilizará.

Próximos pasos

Página traducida automáticamente usando IA