# Usar o component Script
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).
2. 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](/creator/content-creator-pt/scene-editor/expandir-com-codigo/reference-items.md).
## Entendendo a estrutura do Script
Quando o Script é aberto pela primeira vez, ele tem o seguinte código:
```ts
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.
```ts
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.
{% hint style="warning" %}
**Nota Importante**: Não modifique/exclua `public src: string` e `public entity: Entity`. Você pode adicionar novas entradas seguindo estas.
{% endhint %}
Os tipos permitidos para os parâmetros do construtor são:
* `Entity`
* `string`
* `number`
* `boolean`
* `ActionCallback`
{% hint style="info" %}
**📔 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](https://www.typescriptlang.org/docs/handbook/2/classes.html#parameter-properties).
{% endhint %}
### 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.
```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 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.
```ts
/**
* @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.
```ts
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.
```ts
/**
* 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`
{% hint style="info" %}
**📔 Nota**: Você pode adicionar quantas Actions forem necessárias dentro do Script. Todas elas estarão acessíveis independentemente do `Action` dropdown.
{% endhint %}
## 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
```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 chamá-lo de `main.ts`, use:
```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 `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 é:
{% hint style="info" %}
**📔 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.
{% endhint %}
## 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 `Entity`do `Action` definido pela UI do Creator Hub a partir dos métodos do Script.
Neste exemplo, `anotherEntityAction` é adicionado como um `public` .
```ts
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.
```ts
start() {
pointerEventsSystem.onPointerDown(
{
entity: this.entity,
opts: {
button: InputAction.IA_PRIMARY,
hoverText: "Pressione E para acionar uma Action de outra Entity.",
},
},
() => {
this.anotherEntityAction();
}
);
}
```
{% hint style="info" %}
**📔 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` .
{% endhint %}
## Veja também
* [Smart items - Basics](/creator/content-creator-pt/scene-editor/interatividade/smart-items.md)
* [Smart Items - Advanced](/creator/content-creator-pt/scene-editor/interatividade/smart-items-advanced.md)
* [States and conditions](/creator/content-creator-pt/scene-editor/interatividade/states-and-conditions.md)
* [Making any item smart](/creator/content-creator-pt/scene-editor/interatividade/make-any-item-smart.md)
* [Introdução rápida ao SDK](/creator/content-creator-pt/scenes-sdk7/comecar/sdk-101.md): siga este mini tutorial para um curso intensivo rápido.
* [Fluxo de trabalho de desenvolvimento](/creator/content-creator-pt/scenes-sdk7/comecar/dev-workflow.md): leia isto para entender a criação de scenes do início ao fim.
* [Exemplos](https://studios.decentraland.org/resources?sdk_version=SDK7): mergulhe diretamente em scenes de exemplo em funcionamento.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.decentraland.org/creator/content-creator-pt/scene-editor/expandir-com-codigo/script-component.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.