Usar el Script Component

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

Con el nuevo Script Component, es posible crear Entities que ejecuten código personalizado desde 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.

Configurando 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. Revisemos su estructura. Para más detalles sobre cómo seleccionar y administrar tu editor predeterminado, por favor ve a 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 cada frame
   * @param dt - Delta time desde el último frame (en segundos)
   */
  update(dt: number) {
    // Llamado 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/elimes 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

• ActionCallback

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

Accediendo a 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ámbialo así para registrar el valor de un valor que definiste en el constructor:

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

Observa que cuando cambias el valor del parámetro en la UI de Creator Hub, también deberías ver ese valor registrado reflejando el cambio.

Parámetros por defecto

El constructor por defecto contiene un src y una entity parámetro, estos son muy útiles para el código en tu script:

• this.entity siempre se refiere a la entidad que contiene el Script component, usa esto para acceder a información sobre la entidad o añadir componentes a la misma.

• this.src es la ruta donde se almacena el script. Esto es particularmente útil al crear Smart Items que están destinados a ser usados por otros. Usa este campo para construir la ruta a archivos que están empaquetados con tu smart item, incluso si la ruta del smart item cambia o es renombrada.

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

  start() {
    Material.setPbrMaterial(this.entity, {
      texture: Material.Texture.Common({
        src: this.src + '/images/myImage.png',
      })
    });
  }
}

El script anterior obtiene la entidad que posee el script y le aplica una textura. Obtiene la textura de un .png archivo que está empaquetado en la carpeta del smart item, en una subcarpeta llamada /images. Al usar this.src, nos aseguramos de que la ruta del archivo sea siempre conocida, sin importar si el smart item es importado a la escena bajo /assets/custom/itemName o /assets/asset-packs/itemName

start() & update() Método

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 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 cada frame del juego (como lo hacen los Systems). Por ejemplo, comprobando valores del PlayerEntity para desencadenar comportamientos en el script.

El siguiente código imprime Logs 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.

Exponiendo Actions al Creator Hub

Es posible definir una Action dentro de un script de Script Component y hacerla accesible en la UI del Creator Hub. Esto habilita la posibilidad de activar esta Action con otra Entity.

  /**
   * Exponer esta acción para que sea activada
   * @action
   */
  exposedAction(creatorHubParameter: number) {
    console.log("Triggered from another entity using parameter: ", this.numericActionVariable);
  }

creatorHubParameter será expuesto como un Action parámetro para darle un valor personalizado. Después de actualizar el Script Component, la nueva acción estará disponible como una opción en el desplegable Actions.

Después de añadir la Action, cualquier Entity en Creator Hub puede activarla usando Triggers

📔 Nota: Puedes añadir tantas Actions como sean necesarias dentro del Script. Todas ellas serán accesibles independientemente del Action desplegable.

Llamando a métodos de Script desde el Exterior

Para llamar a un método de Script desde otro Script o desde main.ts, se deben seguir los siguientes pasos:

1. Crea un public método dentro de la clase Script.

2. Ejecuta npm run build desde el directorio raíz de la escena.

3. Desde el archivo donde quieres usar el método público, añade import { callScriptMethod } from '~sdk/script-utils'.

4. Llama a callScriptMethod con los parámetros necesarios (en este caso, someParamter).

Aquí hay un ejemplo con un public método expuesto

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

  public publicMethod(boolParameter: boolean, someNumberParameter: number) {
    if (boolParameter) {
      console.log("Public method called with parameter true!: ", someNumberParameter);
    } else {
      console.log("Public method called with parameter: false!", someNumberParameter);
    }
  }
...
}

Para llamarlo desde main.ts, usa:

import { callScriptMethod } from '~sdk/script-utils'


export function main() {
    const buildingEntity = engine.getEntityOrNullByName("building")
    if (buildingEntity) {
        const scriptMethod = callScriptMethod(
            buildingEntity,
            "assets/scene/Scripts/BuildingScript.tsx",
            "publicMethod",
            false,
            3,
        )

        scriptMethod
    }
}

Primero, la función main busca la Entity que tiene el Script component. Segundo, si la Entity existe, callScriptMethod es llamada con los siguientes parámetros:

1. entity: Entity que tiene la public método.

2. scriptPath: ruta donde vive la clase Script .

3. methodName: nombre del public método a ser llamado.

4. ...args: Argumentos del método. En este caso, hay dos. Deben ser agregados en orden, uno tras otro.

Tercero, llamamos al callScriptMethoddefinido, en este caso, scriptMethod.

Con los valores de los parámetros dados, la salida es:

📔 Nota: Puedes seguir la misma lógica para llamar a un public método de Script desde otro script o archivo. Puedes usarlo para obtener o cambiar valores de public variables en la clase Script.

Disparando Actions de otras Entities desde un Script

Es posible usar un parámetro de tipo ActionCallback en el constructor de la clase Script. Esto permite activar otra Entity's Action definida a través de la UI de Creator Hub desde los métodos del Script.

En este ejemplo, anotherEntityAction es añadido como un public parámetro.

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

Un Entity y Action seleccionable están ahora disponibles cuando el Script Component es actualizado en la UI de Creator Hub. Sphere es una Entity ya existente en la escena que tiene una action llamada.

Scale La acción de la otra Entity ahora es accesible en la clase Script. Podría usarse de muchas formas diferentes. En el siguiente ejemplo, presionar E activará this.anotherEntityAction definiendo un pointerEventsSystem en el método.

  start() {
    start
      {
        pointerEventsSystem.onPointerDown(
        entity: this.entity,
          opts: {
          button: InputAction.IA_PRIMARY,
        },
      },
      () => {
        hoverText: "Press E to trigger an Action from another Entity.",
      }
    );
  }

📔 Notathis.anotherEntityAction(); : Combinar exponer y activar Actions public es una herramienta muy poderosa. Puedes definir un Script Component en una Entity, exponer una acción usando un ActionCallback parámetro.

método, y luego activarla desde el Script Component de otra Entity usando un

• Ver también

• Smart items - Basics

• Smart items - Advanced

• Estados y condiciones

• Hacer que cualquier ítem sea smartSDK 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 extremo a extremo.Ejemplos : sumérgete directamente en escenas de ejemplo funcionales.