> 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).
# Usar o Script Component
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 em `index.ts` e potencialmente 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 usando o File Path (navegar ou arrastar e largar um ficheiro existente).
2. Clique no botão CODE no component para abrir o editor de código predefinido. Vamos ver a sua estrutura. Para mais detalhes sobre como selecionar e gerir o seu editor predefinido, vá para [Combinar com código](/creator/content-creator-pt/scene-editor/expandir-com-codigo/overview.md).
## Compreender a estrutura do Script
Quando o Script é aberto pela primeira vez, tem o seguinte código:
```ts
import { engine, Entity } from '@dcl/sdk/ecs'
import {} from '@dcl/sdk/math'
export class BuildingScript {
/**
* Propriedades
* Defina campos da classe que pretende reutilizar entre métodos.
* Exemplo de utilização: this.myVariable
*/
// private myVariable: boolean = true
/**
* Construtor / Inputs
* Os parâmetros declarados aqui aparecem na UI do Script Component no Creator Hub.
* Tipos suportados: Entity, String, Number, Boolean, ActionCallback.
*
* Nota: Depois de editar este ficheiro, clique no ícone de atualizar na UI 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
// Adicione abaixo os seus inputs personalizados
) {}
/**
* start()
* Chamado uma vez quando o script é inicializado.
*/
start() {
// Inicialização do script
console.log("BuildingScript initialized for entity:", this.entity);
}
/**
* update(dt)
* Chamado a cada frame.
* @param dt - (opcional) Tempo delta 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 pretende 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 ficheiro é guardado, o **Refresh** botão no Script Component atualiza todas as alterações feitas.
Assim que for atualizado, o Script Component agora mostra o `numericVariable` adicionado no código.
## Parâmetros
Se diferentes Entities usarem o mesmo ficheiro 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 ficheiro `BuildingScript.ts` ficheiro, cada building tem o seu próprio `numericVariable` parâmetro que pode ser modificado independentemente.
{% hint style="warning" %}
**Nota importante**: Não modifique/apague `public src: string` e `public entity: Entity`. Pode adicionar novos inputs seguindo estes.
{% endhint %}
Os tipos permitidos para os parâmetros do constructor são:
* `Entity`
* `string`
* `number`
* `boolean`
* `ActionCallback`
{% hint style="info" %}
**📔 Observação**: Ambos `público` e `private` os parâmetros do constructor são expostos ao Creator Hub. A `private` palavra-chave só restringe o acesso dentro da `BuildingScript` class. Para mais detalhes, veja a documentação oficial do TypeScript sobre\
[Propriedades de parâmetros](https://www.typescriptlang.org/docs/handbook/2/classes.html#parameter-properties).
{% endhint %}
### 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 template Script predefinido inclui esta linha no método start():
`console.log("BuildingScript initialized for entity:", this.entity);`.
Altere-a assim para registar o valor de um valor que definiu no construtor:
`console.log("BuildingScript initialized with numericVariable:`, `this.numericVariable);`
Note que quando altera o valor do parâmetro na UI do Creator Hub, também deverá ver esse valor registado refletido.
### Parâmetros predefinidos
O constructor contém por predefinição um `src` e um `entity` parâmetro, estes são muito úteis para o código no seu script:
* `this.entity` refere-se sempre à entity que contém o `Script` component, use isto para aceder às informações sobre a entity ou adicionar components a ela.
* `this.src` é o caminho onde o script está armazenado. Isto é particularmente útil quando se criam Smart Items destinados a ser usados por outros. Use este campo para construir o caminho para ficheiros que são empacotados com o 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-lhe uma texture. Obtém a texture de um `.png` ficheiro que está empacotado na pasta do smart item, numa subpasta chamada `/images`. Ao usar `this.src`, garantimos que o caminho do ficheiro é 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 input, para que os utilizadores saibam para que servem estes campos, ou quais os valores aceites. Os utilizadores verão um ícone de tooltip junto a cada campo na UI do Script Component e poderão ler texto personalizado ao passar o cursor sobre o ícone.
Para adicionar tooltips ao seu constructor, adicione um bloco comentado imediatamente antes do constructor 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,
) {
}
```
Pode ser necessário clicar no ícone de atualizar na UI do Script Component para ver alterações nas suas 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 é carregada pela primeira vez).
Pré-visualize a scene e verifique os logs (**Dica**: pode usar o `` ` `` atalho): Ele exibe a nova mensagem incluindo o `numericVariable` parâmetro.
O **update()** o método, por outro lado, executa o seu código a cada frame do jogo (tal como os Systems). Por exemplo, verificar os valores de `PlayerEntity` para desencadear comportamentos no script.
O código seguinte imprime Logs a cada frame do jogo em que o `PlayerEntity` é superior ao anteriormente definido `numericVariable`, que é fornecido dinamicamente pelo criador a partir da 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);
}}
```
A primeira mensagem de log pertence ao método start(), indicando que definimos numericVariable. A segunda pertence ao método update(), quando o player é mais alto do que esse valor.
## Expor Actions ao Creator Hub
É possível definir um `Action` dentro de um script do Script Component e torná-lo acessível na UI do Creator Hub. Isto permite a possibilidade de desencadear esta `Action` com outra Entity.
```ts
/**
* Expor esta action para ser desencadeada
* @action
*/
exposedAction(creatorHubParameter: number) {
console.log("Triggered from another entity using parameter: ", this.creatorHubParameter);
}
```
`creatorHubParameter` será exposto como um `Action` parâmetro para lhe dar um valor personalizado. Depois de atualizar o Script Component, a nova action ficará disponível como opção no dropdown de Actions.
Depois de adicionar a Action, qualquer Entity no Creator Hub pode desencadeá-la usando `Triggers`
{% hint style="info" %}
**📔 Observação**: Pode adicionar quantas Actions forem necessárias dentro do Script. Todas elas estarão acessíveis de forma independente a partir do `Action` dropdown.
{% endhint %}
## Chamar métodos do Script a partir do exterior
Para chamar um método de um Script a partir de outro Script ou de `src/index.ts`, os seguintes passos devem ser seguidos:
1. Crie um `público` método dentro da classe Script.
2. Execute `npm run build` a partir do diretório raiz da scene.
3. No ficheiro onde pretende 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 `público` 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 a partir de `src/index.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` é chamada com os seguintes parâmetros:
1. `entity`: `Entity` que tem o `público` método.
2. `scriptPath`: `caminho` onde a `Script` classe se encontra.
3. `methodName`: nome do `público` método a ser chamado.
4. `...args`: Argumentos do método. Neste caso, há dois. Devem ser adicionados pela ordem, um após o outro.
Terceiro, chamamos a definida `callScriptMethod`, neste caso, `scriptMethod`.
Com os valores dos parâmetros fornecidos, a saída é:
{% hint style="info" %}
**📔 Observação**: Pode seguir a mesma lógica para chamar um `público` método de Script a partir de outro script ou ficheiro. Pode usá-lo para obter ou alterar valores de `público` 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` na classe Script constructor. Isto permite acionar outra `Entity`'s `Action` definida através da UI do Creator Hub a partir dos métodos do Script.
Neste exemplo, `anotherEntityAction` é adicionada como um `público` parâmetro.
```ts
export class BuildingScript {
constructor(
public src: string,
public entity: Entity,
public anotherEntityAction: ActionCallback,
...,
) {}
...
}
```
Uma ação selecionável `Entity` e `Action` estão agora disponíveis quando o Script Component é atualizado na UI do Creator Hub. `Sphere` é uma Entity já existente na scene que tem uma action chamada `Scale`.
A action da outra Entity está agora acessível na classe Script. Pode ser usada de muitas formas diferentes. No exemplo seguinte, ao premir E será acionado `this.anotherEntityAction` ao definir um `pointerEventsSystem` no `start` método.
```ts
start() {
pointerEventsSystem.onPointerDown(
{
entity: this.entity,
opts: {
button: InputAction.IA_PRIMARY,
hoverText: "Press E to trigger an Action from another Entity.",
},
},
() => {
this.anotherEntityAction();
}
);
}
```
{% hint style="info" %}
**📔 Observação**: Combinar expor e acionar `Actions` é uma ferramenta muito poderosa. Pode definir um Script Component numa Entity, expor uma action usando um `público` método e depois acioná-la a partir do Script Component de outra Entity usando um `ActionCallback` parâmetro.
{% endhint %}
## Veja também
* [Smart items - Noções básicas](/creator/content-creator-pt/scene-editor/interatividade/smart-items.md)
* [Smart Items - Avançado](/creator/content-creator-pt/scene-editor/interatividade/smart-items-advanced.md)
* [Estados e condições](/creator/content-creator-pt/scene-editor/interatividade/states-and-conditions.md)
* [Tornando qualquer item smart](/creator/content-creator-pt/scene-editor/interatividade/make-any-item-smart.md)
* [Início rápido do SDK](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/sdk-101.md): siga este mini tutorial para uma introdução rápida.
* [Fluxo de trabalho de desenvolvimento](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/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 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.decentraland.org/creator/content-creator-pt/scene-editor/expandir-com-codigo/script-component.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.