Uso del componente Script

Usa el componente Script para dar funcionalidad con código, sin necesidad de profundizar en toda la estructura del proyecto.

Con el nuevo Script Component, es posible crear Entities que ejecutan código personalizado desde dentro de la propia entidad.

Script Components permiten la ejecución del comportamiento personalizado de una Entity sin la necesidad de trabajar directamente en el index.ts y potencialmente otros archivos.

Configurar el Script Component

1. Agrega el Script Component a una Entity haciendo clic en el + botón y selecciónalo. Crea un nuevo Script haciendo clic en + Add New Script Module y elige un nombre, o usa la File Path (buscar o arrastrar y soltar un archivo existente).

1. Haz clic en el botón CODE en el componente para abrir el editor de código predeterminado. Veamos su estructura. Para más detalles sobre cómo seleccionar y gestionar tu editor predeterminado, por favor visita Combinar con código.

Entendiendo la estructura del Script

Cuando el Script se abre por primera vez, tiene el siguiente código:

import { engine, Entity } from '@dcl/sdk/ecs'

export class BuildingScript {
  constructor(
    public src: string,
    public entity: Entity
  ) {}

  /**
   * Función start - llamada cuando el script se inicializa
   */
  start() {
    // Inicialización del Script
    console.log("BuildingScript initialized for entity:", this.entity);
  }

  /**
   * Función update - llamada en cada frame
   * @param dt - Delta time desde el último frame (en segundos)
   */
  update(dt: number) {
    // Llamado en cada frame
  }
}

La clase está compuesta por tres partes principales:

• El constructor,

• el start() método

• el update() método.

Constructor

El constructor contiene los parámetros que quieres exponer y modificar dinámicamente desde tu escena en Creator Hub.

export class BuildingScript {
  constructor(
    public src: string,
    public entity: Entity,
    public numericVariable: number, 
  ) {}
...
}

Una vez que el archivo está guardado, el Refresh botón en el Script Component actualiza todos los cambios realizados.

Una vez actualizado, el Script Component ahora muestra la numericVariable añadida en el código.

Parámetros

Si diferentes Entities usan el mismo archivo en el Script component, cada una aún tiene parámetros independientes: si la escena tiene dos edificios, building1 y building2, ambos con un Script Component apuntando a BuildingScript.ts archivo, cada edificio tiene su propio numericVariable parámetro que puede ser modificado de forma independiente.

Nota importante: No modifiques/elmines public src: string y public entity: Entity. Puedes añadir nuevas entradas siguiendo estas.

Los tipos permitidos para los parámetros del constructor son:

• Entity

• string

• number

• boolean

📔 Nota: Ambos public y private parámetros del constructor se exponen en Creator Hub. La private palabra clave solo restringe el acceso dentro de la BuildingScript clase. Para más detalles, consulta la documentación oficial de TypeScript sobre Parameter Properties.

Accediendo a los parámetros dentro del Script

Para acceder al valor de un parámetro desde tu código, usa la notación this.definedParameter. Por ejemplo, this.numericVariable o this.entity.

La plantilla de Script por defecto incluye esta línea en el método start():

console.log("BuildingScript initialized for entity:", this.entity);.

Cámbiala así para registrar el valor de un valor que definiste en el constructor:

console.log("BuildingScript initialized with numericVariable:, this.numericVariable);

Ten en cuenta que cuando cambias el valor del parámetro en la UI de Creator Hub, también deberías ver ese valor reflejado en el log.

Métodos start() & update()

El start() el método contiene código que se ejecuta solo una vez, cuando la Entity es creada (en este caso, cuando la escena se carga por primera vez).

Previsualiza la escena y revisa los logs (Consejo: puedes usar el ` atajo): Muestra el nuevo mensaje incluyendo el numericVariable parámetro.

El update() el método, por otro lado, ejecuta su código en cada frame del juego (como hacen los Systems). Por ejemplo, comprobar valores del PlayerEntity para activar comportamientos en el script.

El siguiente código imprime Logs en cada frame del juego cuando el PlayerEntity es mayor que el previamente definido numericVariable, que es provisto por el creador dinámicamente desde la UI del Script Component.

update(dt: number) {
    if (Transform.get(engine.PlayerEntity).position.y > this.numericVariable ) {
      console.log("The player's height is over ", this.numericVariable);
    }}

El primer log pertenece al método start(), indicando que establecimos numericVariable. El segundo pertenece al método update(), cuando el jugador está por encima de ese valor.

Ver también

• Smart items - Basics

• Smart items - Advanced

• Estados y condiciones

• Hacer cualquier ítem inteligente

• SDK Quick start: sigue este mini tutorial para un curso intensivo rápido.

• Flujo de trabajo de desarrollo: lee esto para entender la creación de escenas de principio a fin.

• Ejemplos: sumérgete directamente en escenas de ejemplo funcionando.