> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/expandir-com-codigo/script-component.md).

# Usando o Script Component

Use o Script component para dar funcionalidade ao código, sem a necessidade de 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.

Os Script Components permitem executar o comportamento personalizado de uma Entity sem ter de trabalhar diretamente no `index.ts` e, possivelmente, 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 utilize File Path (procure um ficheiro existente ou arraste-o e largue-o).

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-0a4b3eb7762a7f26eb37f920671705a1007d907f%2Fnew-script-component.webp?alt=media)

2. Clique no botão CODE no componente para abrir o editor de código predefinido. Vamos analisar a sua estrutura. Para obter mais detalhes sobre como selecionar e gerir o editor predefinido, consulte [Combinar com código](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/expandir-com-codigo/overview.md).

## Compreender a estrutura do Script

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

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

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

  /**
   * Construtor / Inputs
   * Os parâmetros declarados aqui aparecem na interface do Script Component no Creator Hub.
   * Tipos suportados: Entity, String, Number, Boolean, ActionCallback e Slider
   * para um número editado com um Slider, por exemplo, public speed: Slider<0, 10, 0.5> = 1
   *
   * Nota: depois de editar este ficheiro, clique no ícone de atualização na interface 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
    // Add your custom inputs below
  ) {}

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

  /**
   * update(dt)
   * Chamado em cada frame.
   * @param dt - (opcional) Tempo decorrido desde o frame anterior (em segundos)
   */
  update(dt: number) {
    // Chamado em cada frame
  }
}
```

A classe é composta por três partes principais:

* O **constructor**,
* o método **start()** o método
* e **update()**  .

## Construtor

O construtor contém os parâmetros que pretende expor e modificar dinamicamente na sua cena no Creator Hub.

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

Depois de guardar o ficheiro, o botão **Atualizar** no Script Component aplica todas as alterações efetuadas.

<img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-8f1b521e1b68b5d9138dd1b60eeb40e4b13dbb0c%2Fscript-refresh-button.webp?alt=media" alt="Botão de atualização" width="360">

Depois de atualizar, o Script Component passa a mostrar o `numericVariable` adicionado no código.

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-18eb30b39910dc3dacecb48e7c6e6c3a26551c4a%2Fparameter-script-component.webp?alt=media)

## Parâmetros

Se diferentes Entities usarem o mesmo arquivo no Script Component, cada uma ainda terá parâmetros independentes: se a cena tiver dois edifícios, `building1` e `building2`, ambos com um Script Component apontando para o arquivo `BuildingScript.ts` , cada edifício tem seu próprio parâmetro `numericVariable` que pode ser modificado independentemente.

{% hint style="warning" %}
**Nota importante**: Não modifique nem exclua `public src: string` e `public entity: Entity`. Você pode adicionar novas entradas depois delas.
{% endhint %}

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

* `Entity`
* `string`
* `number`
* `boolean`
* `ActionCallback`
* `Slider<Min, Max, Step>`
* Uma escolha entre strings, como `'small' | 'large'`
* Um objeto, como `{ x: number; y: number }`
* Uma lista, como `string[]` ou `Array<{ entity: Entity; label: string }>`

O Creator Hub transforma cada nome de parâmetro em um rótulo legível: `maxHealth` é exibido como **Vida máxima**.

### Parâmetros numéricos com um controle deslizante

Defina um parâmetro numérico como `Slider<Min, Max, Step>` para editá-lo com um controle deslizante em vez de uma simples caixa numérica. O Creator Hub mostra tanto um controle deslizante quanto uma caixa numérica.

```ts
constructor(
  public src: string,
  public entity: Entity,
  // Um controle deslizante de 0 a 10, avançando em incrementos de 0,5
  public speed: Slider<0, 10, 0.5> = 1,
) {}
```

* `Step` é opcional e, por padrão, tem o valor `1`.
* São permitidos limites negativos, por exemplo, `Slider<-90, 90>`.
* Em tempo de execução, o valor é um `number`, por isso `this.speed` comporta-se como qualquer outro parâmetro numérico.

{% hint style="info" %}
**📔 Nota**: Tanto os parâmetros `public` como os `private` do construtor são expostos no Creator Hub. A palavra-chave `private` apenas restringe o acesso dentro da classe `BuildingScript` . Para mais detalhes, consulte a documentação oficial do TypeScript sobre\
[Propriedades de parâmetros](https://www.typescriptlang.org/docs/handbook/2/classes.html#parameter-properties).
{% endhint %}

### Parâmetros de escolha

Defina o tipo de um parâmetro de string como uma união de strings para editá-lo com um menu suspenso. O valor predefinido é o selecionado inicialmente.

```ts
constructor(
  public src: string,
  public entity: Entity,
  // Um menu suspenso com três opções, começando em 'player'
  public target: 'all' | 'player' | 'non_player' = 'player',
) {}
```

### Agrupar parâmetros num objeto

Defina o tipo de um parâmetro como um objeto para apresentar os respetivos campos juntos, num grupo que pode expandir e recolher. Os grupos começam recolhidos.

```ts
constructor(
  public src: string,
  public entity: Entity,
  // Aparece como um grupo "Spawn Point" com campos X, Y e Z
  public spawnPoint: { x: number; y: number; z: number } = { x: 8, y: 0, z: 8 },
) {}
```

Os objetos podem conter outros objetos e listas. Escreva a estrutura diretamente, como acima: o Creator Hub não lê tipos nomeados, pelo que um parâmetro tipado com uma `interface` ou um alias de `type` declarado noutro local não apresenta os respetivos campos.

### Parâmetros de lista

Defina o tipo de um parâmetro como um array para permitir que o criador adicione as linhas necessárias. Cada linha tem um botão de lixo, e um botão **Adicionar** adiciona uma nova linha.

```ts
constructor(
  public src: string,
  public entity: Entity,
  // Cada linha tem um seletor de Entity e um campo de texto
  public targets: Array<{ entity: Entity; label: string }> = [],
) {}
```

`T[]` e `Array<T>` funcionam da mesma forma.

### Restringir seletores com tags

Adicione uma destas tags num comentário `/** */` imediatamente antes de um parâmetro ou de um campo de um parâmetro de objeto para alterar a forma como o Creator Hub o edita. Numa lista, a tag aplica-se a cada linha.

| Tag                    | Aplicar a   | O que faz                                                                                 |
| ---------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `@components <name> …` | Um `Entity` | Apresenta apenas entidades que tenham um dos componentes indicados.                       |
| `@actionsOf <field>`   | Um `string` | Apresenta um menu suspenso com as ações da entidade selecionada no campo irmão `<field>`. |
| `@format wallet`       | Um `string` | Edita o valor como um endereço de carteira.                                               |

```ts
constructor(
  public src: string,
  public entity: Entity,
  public buttons: Array<{
    /** @components asset-packs::Actions */
    entity: Entity
    /** @actionsOf entity */
    action: string
  }> = [],
  /** @format wallet */
  public owner: string = '',
) {}
```

Neste exemplo, cada linha de **Buttons** só permite escolher itens que tenham ações, e o respetivo menu **Action** pendente lista as ações do item escolhido nessa linha. Até escolher um item, o menu apresenta **Selecione primeiro um item**. Se uma ação guardada já não existir no item, o campo indica-o.

As etiquetas só alteram o editor. Em runtime, o seu script recebe valores simples: uma entidade, uma string com o nome da ação e uma string com o endereço.

### Parâmetros de ficheiro

Um parâmetro do tipo string pode conter o nome de um ficheiro incluído com o seu script, como um som ou um modelo. O seu script acede-lhe a partir da própria pasta, assim: `` `${this.src}/${this.sound}` ``. Consulte [Parâmetros predefinidos](#default-parameters).

O Creator Hub verifica estes valores. Se um valor indicar um ficheiro que deveria estar na pasta do script, mas não estiver, o campo apresenta `"<file name>" is missing`. Os URLs e o texto comum nunca são assinalados.

Quando muda o nome ou move um ficheiro dentro da pasta do script no separador **Local Assets** , os parâmetros que o utilizam são atualizados automaticamente; se o eliminar, recebe um aviso de que está a ser utilizado. Não é possível acompanhar o ficheiro se o mover para fora da pasta do script, e o Creator Hub informa que algumas referências não puderam ser atualizadas.

### 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 modelo predefinido de Script inclui esta linha no método start():

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

Altere-a desta forma para registar o valor de uma variável que definiu no construtor:

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

Tenha em atenção que, ao alterar o valor do parâmetro na interface do Creator Hub, também deverá ver esse valor atualizado no registo.

### Parâmetros predefinidos

Por predefinição, o construtor contém um parâmetro `src` e um parâmetro `entity` , que são muito úteis para o código do seu script:

* `this.entity` refere-se sempre à entidade que contém o `Script` componente, use-o para aceder a informações sobre a entidade ou adicionar componentes à mesma.
* `this.src` é o caminho onde o script está armazenado. Isto é particularmente útil ao criar Smart Items destinados a serem usados por outras pessoas. Use este campo para construir o caminho para os ficheiros incluídos no seu smart item, mesmo que o caminho do smart item seja alterado ou este seja renomeado.

```ts
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 entidade que contém o script e aplica-lhe uma textura. Obtém a textura de um ficheiro `.png` incluído na pasta do smart item, numa subpasta com o nome `/images`. Ao usar `this.src`, garantimos que o caminho do ficheiro é sempre conhecido, independentemente de o smart item ser importado para a cena em `/assets/custom/itemName` ou em `/assets/asset-packs/itemName`

### Descrições dos parâmetros

Adicione descrições aos seus parâmetros de entrada para que os utilizadores saibam para que servem estes campos ou que valores são aceites. Os utilizadores verão um ícone de descrição junto a cada campo na UI do componente Script e poderão ler o texto personalizado ao passar o cursor sobre o ícone.

Para adicionar descrições ao seu construtor, adicione um bloco de comentários imediatamente antes do construtor e escreva uma linha com `@param` seguido do nome do campo e de uma descrição, para cada descrição.

```ts
  /**
   * @param startDate - A data de início do evento no formato AAAA-MM-DD
   * @param yOffset - A altura, em metros acima do chão, a que o item será apresentado
   */
  constructor(
    public src: string,
    public entity: Entity,
    public startDate?: string,
    public yOffset: number = 0.5,
  ) {
  }
```

Poderá ter de clicar no ícone de atualização da UI do componente Script para ver as alterações às descrições.

<img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-8f1b521e1b68b5d9138dd1b60eeb40e4b13dbb0c%2Fscript-refresh-button.webp?alt=media" alt="Botão de atualização" width="360">

## Métodos start() e update()

O método **start()** 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 registos (**Sugestão**: pode usar o atalho `` ` ``  ): apresenta a nova mensagem, incluindo o parâmetro `numericVariable` .

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-fabd7facf4936fb649ae429b9c37fc419ba7d0b6%2Fscript-log-message.webp?alt=media)

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

O código seguinte apresenta registos a cada frame do jogo em que `PlayerEntity` está acima do valor definido anteriormente em `numericVariable`, fornecido dinamicamente pelo criador através da UI do componente Script.

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

<img src="https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-7825c3d4095279d79c52337e7210e1935f796703%2Fupdate-script-logs.webp?alt=media" alt="Update Method" data-size="line">

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

## Expor ações no Creator Hub

É possível definir um `Action` dentro de um script de Script Component, tornando-o acessível na UI do Creator Hub. Isto permite acionar esta `Action` com outra Entity.

```ts
  /**
   * Expor esta ação para que possa ser acionada
   * @action
   */
  exposedAction(creatorHubParameter: number) {
    console.log("Triggered from another entity using parameter: ", this.creatorHubParameter);
  }
```

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

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-b2347abdf8b6704b2c7b1f7090de49b535beaf5d%2Fscript-component-action.webp?alt=media)

Depois de adicionar a Action, qualquer Entity no Creator Hub pode acioná-la através de `Triggers`

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-d5af1dd8d6a6bbf64f9202976f66bfab49e65189%2Fscript-component-action-trigger.webp?alt=media)

{% hint style="info" %}
**📔 Nota**: pode adicionar tantas Actions quantas forem necessárias dentro do Script. Todas estarão acessíveis de forma independente através do menu suspenso `Action` .
{% endhint %}

## Chamar métodos de Script externamente

Para chamar um método de Script a partir de outro Script ou de `src/index.ts`, siga estes passos:

1. Crie um método `public` dentro da classe Script.
2. Execute `npm run build` a partir do diretório raiz da Scene.
3. No ficheiro onde pretende utilizar o método público, adicione `import { callScriptMethod } from '~sdk/script-utils'`.
4. Chame `callScriptMethod` com os parâmetros necessários (neste caso, `someParamter`).

Veja um exemplo de um método `public` exposto:

```ts
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 o chamar a partir de `src/index.ts`, utilize:

```ts
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 função `main` procura a `Entity` que tem o componente Script. Em segundo lugar, se `Entity` existir, `callScriptMethod` é chamada com os seguintes parâmetros:

1. `entity`: `Entity` que tem o método `public` .
2. `scriptPath`: `path` onde a classe `Script` está definida.
3. `methodName`: nome do método `public` a ser chamado.
4. `...args`: argumentos do método. Neste caso, são dois. Devem ser adicionados por ordem, um após o outro.

Em terceiro lugar, chamamos o `callScriptMethod`, neste caso, o `scriptMethod`.

Com os valores fornecidos para os parâmetros, o resultado é:

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-761e5092a6f0de732888f475223cd391bf158f46%2Fscript-component-public-method.webp?alt=media)

{% hint style="info" %}
**📔 Nota**: pode seguir a mesma lógica para chamar um método `public` de Script a partir de outro script ou ficheiro. Pode usá-lo para obter ou alterar valores de `public` variáveis na classe Script.
{% endhint %}

## Acionar Actions de outras Entities a partir de um Script

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

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

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

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

![](https://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-eebee3acf257773a5b63ed040f18d1010a481420%2Fscript-component-action-callback.webp?alt=media)

A ação da outra Entity está agora acessível na classe Script. Pode ser usada de várias formas. No exemplo seguinte, premir E irá acionar `this.anotherEntityAction` definindo um `pointerEventsSystem` no método `start` .

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

### Callbacks de ação opcionais

Um parâmetro `ActionCallback` que o criador deixa sem ligação é `undefined`, e o respetivo tipo é `ActionCallback | undefined`. Verifique antes de o chamar, para que o script funcione quer a ação esteja ligada ou não:

```ts
if (this.anotherEntityAction) {
  this.anotherEntityAction();
}
```

{% hint style="info" %}
**📔 Nota**: Combinar a exposição e o acionamento de `Actions` é uma ferramenta muito poderosa. Pode definir um Script Component numa Entity, expor uma ação usando um método `public` e, em seguida, acioná-la a partir do Script Component de outra Entity usando um parâmetro `ActionCallback` .
{% endhint %}

## Ver também

* [Smart items - Noções básicas](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/interatividade/smart-items.md)
* [Smart items - Avançado](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/interatividade/smart-items-advanced.md)
* [Estados e condições](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/interatividade/states-and-conditions.md)
* [Tornar qualquer item inteligente](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/interatividade/make-any-item-smart.md)
* [Início rápido do SDK](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/sdk-101.md): siga este breve tutorial para uma introdução rápida.
* [Fluxo de trabalho de desenvolvimento](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/dev-workflow.md): leia isto para compreender todo o processo de criação de cenas.
* [Exemplos](https://docs.decentraland.org/creator/content-creator-pt/tutoriais-e-exemplos/examples.md): explore diretamente cenas de exemplo funcionais.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-pt/scene-editor/expandir-com-codigo/script-component.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
