Usando o Script Component

Use o component Script para dar funcionalidade de código, sem precisar de explorar 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 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 usando o File Path (navegue ou arraste e solte 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, 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() method

• o update() método.

Construtor

O construtor contém os parâmetros que você deseja 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 arquivo for salvo, o Refresh botão no Script Component atualiza todas as alterações feitas.

Após atualizar, o Script Component agora mostra o numericVariable adicionado no código.

Parâmetros

Se Entities diferentes usarem o mesmo arquivo 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 arquivo BuildingScript.ts, cada building 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 estas.

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

• Entity

• string

• number

• boolean

• ActionCallback

📔 Nota: Ambos public e private parâmetros do construtor são expostos ao Creator Hub. A private palavra-chave apenas restringe o acesso dentro do 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 no 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);.

Altere-a assim para registrar o valor de uma variável que você definiu no construtor:

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

Observe que, quando você alterar o valor do parâmetro na UI do Creator Hub, também deverá ver esse valor registrado refletir isso.

Parâmetros padrão

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

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

• this.src é o caminho onde o script está armazenado. Isso é particularmente útil ao criar Smart Items destinados a serem usados por outras pessoas. Use este campo para construir o caminho para arquivos que estão empacotados com 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 uma texture a ela. Ele obtém a texture de um .png arquivo empacotado na pasta do smart item, em uma subpasta chamada /images. Ao usar this.src, garantimos que o caminho do arquivo seja 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 entrada, para que os usuários saibam para que esses campos são usados ou quais valores são aceitos. Os usuários verão um ícone de tooltip ao lado de cada campo na UI do Script component e poderão ler o texto personalizado ao passar o mouse sobre o ícone.

Para adicionar tooltips ao seu construtor, adicione um bloco comentado logo antes do construtor 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,
  ) {
  }

Talvez seja necessário clicar no ícone de atualização na UI do Script component para ver as alterações nos seus tooltips.

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 carrega pela primeira vez).

Faça o preview da scene e verifique os logs (Dica: você pode usar o ` atalho): Ele exibe a nova mensagem incluindo o numericVariable .

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

O código a seguir imprime Logs a cada frame do jogo em que o PlayerEntity é maior do que o previamente definido numericVariable, que é fornecido pelo criador dinamicamente pela 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 player 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 atribuir um valor personalizado a ele. Após atualizar o Script Component, a nova action estará disponível como uma opção no dropdown Actions.

Depois de 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 estarão acessíveis independentemente do Action dropdown.

Chamando métodos do Script de fora

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

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

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

3. No arquivo em que 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 a Entity que tem o Script component. Segundo, se a Entity existir, callScriptMethod é chamado com os seguintes parâmetros:

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

2. scriptPath: path onde a Script classe reside.

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 callScriptMethod, 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 construtor da classe Script. Isso permite acionar outro Entitydo Action definido pela UI do Creator Hub a partir dos métodos do Script.

Neste exemplo, anotherEntityAction é adicionado como um public .

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. Esfera é uma Entity já existente na scene que tem uma action chamada Scale.

A action da outra Entity agora está acessível na classe Script. Ela pode ser usada de muitas maneiras diferentes. No exemplo a seguir, pressionar E acionará this.anotherEntityAction ao definir um pointerEventsSystem mais próximo no start método.

  start() {
    pointerEventsSystem.onPointerDown(
      {
        entity: this.entity,
        opts: {
          button: InputAction.IA_PRIMARY,
          hoverText: "Pressione E para acionar uma Action de outra Entity.",
        },
      },
      () => {
        this.anotherEntityAction();
      }
    );
  }

📔 Nota: Combinar expor e acionar Actions é uma ferramenta muito poderosa. Você pode definir um Script Component em uma Entity, expor uma action usando um public método e então acioná-la a partir do Script Component de outra Entity usando um ActionCallback .

Veja também

• Smart items - Basics

• Smart Items - Advanced

• States and conditions

• Making any item smart

• Introdução rápida ao SDK: siga este mini tutorial para um curso intensivo rápido.

• 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 em funcionamento.