Usando o Script Component

Use o Script component para dar funcionalidade ao código, sem precisar se aprofundar em toda a estrutura do projeto.

Com o novo Script Component, é possível criar Entities que executam código personalizado a partir da própria Entity.

Script Components permitem a execução do comportamento personalizado de uma Entity sem a necessidade de trabalhar diretamente em index.ts e potencialmente noutros ficheiros.

Configurar o Script Component

1. Adicione o Script Component a uma Entity clicando no + botão e selecione-o. Crie um novo Script clicando em + Add New Script Module e escolha um nome, ou usando o File Path (navegar ou arrastar e largar um ficheiro existente).

1. Clique no botão CODE no component para abrir o editor de código predefinido. Vamos ver a sua estrutura. Para mais detalhes sobre como selecionar e gerir o seu editor predefinido, vá para Combinar com código.

Compreender a estrutura do Script

Quando o Script é aberto pela primeira vez, tem o seguinte código:

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

export class BuildingScript {
  /**
   * Propriedades
   * Defina campos da classe que pretende reutilizar entre métodos.
   * Exemplo de utilização: this.myVariable
   */
   // private myVariable: boolean = true

  /**
   * Construtor / Inputs
   * Os parâmetros declarados aqui aparecem na UI do Script Component no Creator Hub.
   * Tipos suportados: Entity, String, Number, Boolean, ActionCallback.
   *
   * Nota: Depois de editar este ficheiro, clique no ícone de atualizar na UI do Script Component
   * para ver os inputs atualizados.
   *
   * Os campos `src` e `entity` no construtor são necessários para referências internas.
   */
  constructor(
    public src: string,     // DO NOT REMOVE
    public entity: Entity,   // DO NOT REMOVE
    // Adicione abaixo os seus inputs personalizados
  ) {}

  /**
   * start()
   * Chamado uma vez quando o script é inicializado.
   */
  start() {
    // Inicialização do script
    console.log("BuildingScript initialized for entity:", this.entity);
  }

  /**
   * update(dt)
   * Chamado a cada frame.
   * @param dt - (opcional) Tempo delta desde o último frame (em segundos)
   */
  update(dt: number) {
    // Chamado a cada frame
  }
}

A classe é composta por três partes principais:

• O constructor,

• o start() método

• o update() método.

Construtor

O construtor contém os parâmetros que pretende expor e modificar dinamicamente a partir da sua scene no Creator Hub.

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

Assim que o ficheiro é guardado, o Refresh botão no Script Component atualiza todas as alterações feitas.

Botão de atualizar

Assim que for atualizado, o Script Component agora mostra o numericVariable adicionado no código.

Parâmetros

Se diferentes Entities usarem o mesmo ficheiro no Script component, cada uma ainda terá parâmetros independentes: se a scene tiver dois buildings, building1 e building2, ambos com um Script Component apontando para o ficheiro BuildingScript.ts ficheiro, cada building tem o seu próprio numericVariable parâmetro que pode ser modificado independentemente.

Nota importante: Não modifique/apague public src: string e public entity: Entity. Pode adicionar novos inputs seguindo estes.

Os tipos permitidos para os parâmetros do constructor são:

• Entity

• string

• number

• boolean

• ActionCallback

📔 Observação: Ambos público e private os parâmetros do constructor são expostos ao Creator Hub. A private palavra-chave só restringe o acesso dentro da BuildingScript class. Para mais detalhes, veja a documentação oficial do TypeScript sobre Propriedades de parâmetros.

Aceder aos Parâmetros dentro do Script

Para aceder ao valor de um parâmetro no seu código, use a notação this.definedParameter. Por exemplo, this.numericVariable ou this.entity.

O template Script predefinido inclui esta linha no método start():

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

Altere-a assim para registar o valor de um valor que definiu no construtor:

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

Note que quando altera o valor do parâmetro na UI do Creator Hub, também deverá ver esse valor registado refletido.

Parâmetros predefinidos

O constructor contém por predefinição um src e um entity parâmetro, estes são muito úteis para o código no seu script:

• this.entity refere-se sempre à entity que contém o Script component, use isto para aceder às informações sobre a entity ou adicionar components a ela.

• this.src é o caminho onde o script está armazenado. Isto é particularmente útil quando se criam Smart Items destinados a ser usados por outros. Use este campo para construir o caminho para ficheiros que são empacotados com o seu smart item, mesmo que o caminho do smart item mude ou seja renomeado.

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',
      })
    });
  }
}

O script acima obtém a entity que possui o script e aplica-lhe uma texture. Obtém a texture de um .png ficheiro que está empacotado na pasta do smart item, numa subpasta chamada /images. Ao usar this.src, garantimos que o caminho do ficheiro é sempre conhecido, independentemente de o smart item ser importado para a scene em /assets/custom/itemName ou /assets/asset-packs/itemName

Tooltips nos parâmetros

Adicione tooltips aos seus parâmetros de input, para que os utilizadores saibam para que servem estes campos, ou quais os valores aceites. Os utilizadores verão um ícone de tooltip junto a cada campo na UI do Script Component e poderão ler texto personalizado ao passar o cursor sobre o ícone.

Para adicionar tooltips ao seu constructor, adicione um bloco comentado imediatamente antes do constructor e escreva uma linha com @param mais o nome do campo, seguido de uma descrição, para cada tooltip.

  /**
   * @param startDate - A data de início do evento no formato YYYY-MM-DD
   * @param yOffset - Quantos metros acima do chão exibir o item
   */
  constructor(
    public src: string,
    public entity: Entity,
    public startDate?: string,
    public yOffset: number = 0.5,
  ) {
  }

Pode ser necessário clicar no ícone de atualizar na UI do Script Component para ver alterações nas suas tooltips.

Botão de atualizar

Método start() & update()

O start() o método contém código que é executado apenas uma vez, quando a Entity é criada (neste caso, quando a scene é carregada pela primeira vez).

Pré-visualize a scene e verifique os logs (Dica: pode usar o ` atalho): Ele exibe a nova mensagem incluindo o numericVariable parâmetro.

O update() o método, por outro lado, executa o seu código a cada frame do jogo (tal como os Systems). Por exemplo, verificar os valores de PlayerEntity para desencadear comportamentos no script.

O código seguinte imprime Logs a cada frame do jogo em que o PlayerEntity é superior ao anteriormente definido numericVariable, que é fornecido dinamicamente pelo criador a partir da UI do Script Component.

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

A primeira mensagem de log pertence ao método start(), indicando que definimos numericVariable. A segunda pertence ao método update(), quando o player é mais alto do que esse valor.

Expor Actions ao Creator Hub

É possível definir um Action dentro de um script do Script Component e torná-lo acessível na UI do Creator Hub. Isto permite a possibilidade de desencadear esta Action com outra Entity.

  /**
   * Expor esta action para ser desencadeada
   * @action
   */
  exposedAction(creatorHubParameter: number) {
    console.log("Triggered from another entity using parameter: ", this.creatorHubParameter);
  }

creatorHubParameter será exposto como um Action parâmetro para lhe dar um valor personalizado. Depois de atualizar o Script Component, a nova action ficará disponível como opção no dropdown de Actions.

Depois de adicionar a Action, qualquer Entity no Creator Hub pode desencadeá-la usando Triggers

📔 Observação: Pode adicionar quantas Actions forem necessárias dentro do Script. Todas elas estarão acessíveis de forma independente a partir do Action dropdown.

Chamar métodos do Script a partir do exterior

Para chamar um método de um Script a partir de outro Script ou de src/index.ts, os seguintes passos devem ser seguidos:

1. Crie um público método dentro da classe Script.

2. Execute npm run build a partir do diretório raiz da scene.

3. No ficheiro onde pretende usar o método público, adicione import { callScriptMethod } from '~sdk/script-utils'.

4. Chame callScriptMethod com os parâmetros necessários (neste caso, someParamter).

Aqui está um exemplo com um público método exposto

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 chamá-lo a partir de src/index.ts, use:

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
    }
}

Primeiro, a main função procura a Entity que tem o Script component. Segundo, se a Entity existir, callScriptMethod é chamada com os seguintes parâmetros:

1. entity: Entity que tem o público método.

2. scriptPath: caminho onde a Script classe se encontra.

3. methodName: nome do público método a ser chamado.

4. ...args: Argumentos do método. Neste caso, há dois. Devem ser adicionados pela ordem, um após o outro.

Terceiro, chamamos a definida callScriptMethod, neste caso, scriptMethod.

Com os valores dos parâmetros fornecidos, a saída é:

📔 Observação: Pode seguir a mesma lógica para chamar um público método de Script a partir de outro script ou ficheiro. Pode usá-lo para obter ou alterar valores de público variáveis na classe Script.

Acionar Actions de outras Entities a partir de um Script

É possível usar um parâmetro do tipo ActionCallback na classe Script constructor. Isto permite acionar outra Entity's Action definida através da UI do Creator Hub a partir dos métodos do Script.

Neste exemplo, anotherEntityAction é adicionada como um público parâmetro.

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

Uma ação selecionável Entity e Action estão agora disponíveis quando o Script Component é atualizado na UI do Creator Hub. Sphere é uma Entity já existente na scene que tem uma action chamada Scale.

A action da outra Entity está agora acessível na classe Script. Pode ser usada de muitas formas diferentes. No exemplo seguinte, ao premir E será acionado this.anotherEntityAction ao definir um pointerEventsSystem no start método.

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

📔 Observação: Combinar expor e acionar Actions é uma ferramenta muito poderosa. Pode definir um Script Component numa Entity, expor uma action usando um público método e depois acioná-la a partir do Script Component de outra Entity usando um ActionCallback parâmetro.

Veja também

• Smart items - Noções básicas

• Smart Items - Avançado

• Estados e condições

• Tornando qualquer item smart

• Início rápido do SDK: siga este mini tutorial para uma introdução rápida.

• Fluxo de trabalho de desenvolvimento: leia isto para entender a criação de scenes do início ao fim.

• Exemplos: mergulhe diretamente em scenes de exemplo funcionais.