Usando o Componente Script

Use o componente Script para dar funcionalidade de código, sem a necessidade de investigar toda a estrutura do projeto.

Com o novo Script Component, é possível criar Entities que executam código personalizado de dentro da própria entity.

Script Components permitem a execução do comportamento customizado de uma Entity sem a necessidade de trabalhar diretamente no index.ts e potencialmente outros arquivos.

Configurando 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 use o File Path (procurar ou arrastar e soltar um arquivo existente).

1. Clique no botão CODE no componente para abrir o editor de código padrão. Vamos verificar sua estrutura. Para mais detalhes sobre como selecionar e gerenciar seu editor padrão, por favor vá para Combinar com código.

Entendendo a estrutura do Script

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

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

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

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

  /**
   * Função update - chamada a cada frame
   * @param dt - Delta time 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 constructor contém os parâmetros que você deseja expor e modificar dinamicamente a partir da sua cena no Creator Hub.

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

Uma vez que o arquivo é salvo, o Refresh botão no Script Component atualiza todas as mudanças feitas.

Uma vez atualizado, o Script Component agora mostra o numericVariable adicionado no código.

Parâmetros

Se diferentes Entities usam o mesmo arquivo no Script component, cada uma ainda tem parâmetros independentes: se a cena tem dois prédios, building1 e building2, ambos com um Script Component apontando para BuildingScript.ts arquivo, cada prédio tem seu próprio numericVariable parâmetro que pode ser modificado independentemente.

Nota importante: Não modifique/exclua public src: string e public entity: Entity. Você pode adicionar novas entradas seguindo estes.

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

• Entity

• string

• number

• boolean

• ActionCallback

📔 Nota: Ambos public e private parâmetros do constructor são expostos ao Creator Hub. A private keyword apenas restringe o acesso dentro da BuildingScript class. Para mais detalhes, veja a documentação oficial do TypeScript sobre Parameter Properties.

Acessando Parâmetros dentro do Script

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

O template padrão do Script inclui esta linha no método start():

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

Mude-o assim para registrar (log) o valor de um valor que você definiu no constructor:

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

Note que quando você muda o valor do parâmetro na UI do Creator Hub, você também deve ver esse valor registrado refletir isso.

Parâmetros padrão

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

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

• this.src é o caminho onde o script está armazenado. Isto é particularmente útil ao criar Smart Items que devem ser usados por outros. Use este campo para construir o caminho para arquivos que são empacotados com seu smart item, mesmo se o caminho do smart item mudar ou for 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 busca a entity que possui o script e aplica uma textura a ela. Ele obtém a textura de um .png arquivo que está empacotado na pasta do smart item, em uma subpasta chamada /images. Ao usar this.src, asseguramos que o caminho do arquivo seja sempre conhecido, não importa se o smart item é importado para a cena sob /assets/custom/itemName ou /assets/asset-packs/itemName

start() & update() Método

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

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

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

O código a seguir imprime Logs a cada frame do jogo que o PlayerEntity é maior que o previamente definido numericVariable, que é fornecido pelo criador dinamicamente 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);
    }}

O primeiro log pertence ao método start(), indicando que definimos numericVariable. O segundo pertence ao método update(), quando o jogador está acima desse valor.

Expondo Actions ao Creator Hub

É possível definir uma Action dentro de um script do Script Component e torná-la acessível na UI do Creator Hub. Isso possibilita acionar essa Action com outra Entity.

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

creatorHubParameter será exposto como um Action parâmetro para dar-lhe um valor customizado. Após atualizar o Script Component, a nova action estará disponível como uma opção no dropdown de Actions.

Após adicionar a Action, qualquer Entity no Creator Hub pode acioná-la usando Triggers

📔 Nota: Você pode adicionar quantas Actions forem necessárias dentro do Script. Todas elas serão acessíveis independentemente do Action dropdown.

Chamando métodos do Script de Fora

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

1. Crie um public método dentro da classe Script.

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

3. Do arquivo onde você deseja 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 public 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 de main.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 pela Entity que tem o Script component. Segundo, se a Entity existe, callScriptMethod é chamada com os seguintes parâmetros:

1. entity: Entity que tem o public método.

2. scriptPath: caminho onde a Script class vive.

3. methodName: nome do public método a ser chamado.

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

Terceiro, chamamos o callScriptMethoddefinido, neste caso, scriptMethod.

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

📔 Nota: Você pode seguir a mesma lógica para chamar um public método do Script a partir de outro script ou arquivo. Você pode usá-lo para obter ou alterar valores de public variáveis na classe Script.

Acionando Actions de outras Entities a partir de um Script

É possível usar um parâmetro do tipo ActionCallback no constructor da classe Script. Isso permite acionar o Entityde outra Action definido através da UI do Creator Hub a partir dos métodos do Script.

Neste exemplo, anotherEntityAction é adicionado como um public parâmetro.

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

Um Entity e Action selecionável agora está disponível quando o Script Component é atualizado na UI do Creator Hub. Sphere é uma Entity já existente na cena que tem uma action chamada.

Scale A action da outra Entity agora é acessível na classe Script. Ela poderia ser usada de várias maneiras. No exemplo a seguir, pressionar E acionará this.anotherEntityAction definindo um pointerEventsSystem no 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(); : Combinando expor e acionar Actions public é uma ferramenta muito poderosa. Você pode definir um Script Component em uma Entity, expor uma action usando um ActionCallback parâmetro.

método, e então acioná-la a partir do Script Component de outra Entity usando um

• Veja também

• Smart items - Basics

• Smart items - Advanced

• Estados e condições

• Tornando qualquer item inteligenteSDK Quick start

• : siga este mini tutorial para um curso rápido.Fluxo de trabalho de desenvolvimento

• : leia isto para entender a criação de cenas de ponta a ponta.Exemplos