Usando o Componente Script

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

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

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, por favor vá para Combine 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 construtor contém os parâmetros que você quer expor e modificar dinamicamente na 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 alterações 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 edifícios, building1 e building2, ambos com um Script Component apontando para BuildingScript.ts arquivo, cada edifício 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: Tanto public e private os parâmetros do construtor são expostos ao Creator Hub. A private palavra-chave apenas restringe o acesso dentro da BuildingScript classe. 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 assim para registrar (log) o valor de um valor que você definiu no construtor:

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

Note que quando você altera 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 construtor 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 à entidade que possui o Script component, use isto para acessar informações sobre a entidade ou adicionar componentes a ela.

• this.src é o caminho onde o script está armazenado. Isso é particularmente útil ao criar Smart Items que são destinados a serem usados por outros. Use este campo para construir o caminho para arquivos que estã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 obtém 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, garantimos 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

Dicas em 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 um texto personalizado ao passar o cursor 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 por 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 solo exibir o item
   */
  constructor(
    public src: string,
    public entity: Entity,
    public startDate?: string,
    public yOffset: number = 0.5,
  ) {
  }

Você pode precisar clicar no ícone de refresh na UI do Script component para ver mudanças em 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 cena é carregada 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 acionar 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 na 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 permite a possibilidade de disparar essa Action com outra Entity.

  /**
   * Exponha esta ação 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 a ele um valor personalizado. Após atualizar o Script Component, a nova ação estará disponível como uma opção no dropdown de 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 serão acessíveis independentemente do Action dropdown.

Chamando métodos de Script de fora

Para chamar um método de Script 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ê quer 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 lives.

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

4. ...args: Argumentos do método. Neste caso, são 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 de Script de outro script ou arquivo. Você pode usá-lo para buscar 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 a Entityde outra Action definida através da UI do Creator Hub a partir dos métodos do Script.

Neste exemplo, anotherEntityAction é adicionada 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 ação da outra Entity agora é acessível na classe Script. Ela poderia ser usada de muitas maneiras diferentes. 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 exposição e acionamento 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

• States and conditions

• Tornando qualquer item smartSDK 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: mergulhe diretamente em cenas de exemplo funcionando.