> 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/scenes-sdk7/primeiros-passos/coding-scenes.md).
# Essenciais de codificação
Este conjunto ajudará você a entender como as coisas funcionam no client e no SDK do Decentraland.
## As ferramentas de desenvolvimento
Num nível muito alto, a Decentraland **Kit de Desenvolvimento de Software** (SDK) permite que você faça o seguinte:
* Gerar um *projeto* contendo uma scene da Decentraland, incluindo todos os assets necessários para renderizar e executar o seu conteúdo.
* Compile, teste e pré-visualize o conteúdo da sua scene localmente no seu navegador web - completamente offline, e sem ter de fazer quaisquer transações Ethereum ou possuir LAND.
* Escreva código TypeScript usando a API da Decentraland para adicionar comportamento interativo e dinâmico à scene.
* Envie o conteúdo da sua scene para o content server.
* Associe os seus tokens LAND ao URL do conteúdo que você carregou.
O nosso SDK inclui o seguinte:
* **O Creator Hub**: Uma aplicação autónoma que, entre outras coisas, permite criar scenes com uma interface fácil de drag-and-drop. Você pode executar previews, depurar, editar código e publicar. [Leia mais](/creator/content-creator-pt/scene-editor/comece/about-editor.md)
* **O ECS da Decentraland**: Um package TypeScript contendo o framework de métodos auxiliares que permite criar experiências interativas. Use-o para criar e manipular objects na scene e também para facilitar transações no mundo entre players ou outras applications. ( [referência mais recente do ECS](https://github.com/decentraland/ecs-reference/blob/master/docs-latest/decentraland-ecs.md))
* **Exemplos de scene**: Inspire-se e tire boas práticas de programação dos [exemplos de scene](https://studios.decentraland.org/resources?sdk_version=SDK7).
Outras ferramentas legadas:
* **O Web Editor**: Uma ferramenta baseada na web para criar scenes simples e publicá-las.
## Requisitos
Para desenvolver uma scene localmente, você não precisa de possuir tokens LAND. Desenvolver e testar uma scene pode ser feito completamente offline, sem a necessidade de fazer deploy de uma scene para a rede Ethereum (o sistema que a Decentraland usa para estabelecer a propriedade de LAND, de um Decentraland Name), ou para o content server.
Você deve ter:
* **O Creator Hub**: Uma aplicação autónoma que, entre outras coisas, permite criar scenes com uma interface fácil de drag-and-drop. Você pode executar previews, depurar, editar código e publicar. [Leia mais](/creator/content-creator-pt/scene-editor/comece/about-editor.md).
Se você planeja editar o código da scene, também precisará instalar um dos seguintes:
* 
**Visual Studio Code**: Faça o download [aqui](https://code.visualstudio.com/). Ele ajuda você a escrever código muito mais rápido e com menos erros. Um editor de código-fonte assinala erros de sintaxe, faz autocompletar enquanto você escreve e até mostra sugestões inteligentes que dependem do contexto em que você está. Você também pode clicar num objeto no código para ver a definição completa da sua classe e quais atributos ela suporta.
* 
**Cursor AI**: Faça o download [aqui](https://www.cursor.com/). Um editor de código poderoso integrado com IA. Ele permite escolher diferentes modelos de IA para ajudá-lo a escrever código, todos gratuitos. O assistente de IA não apenas faz autocompletar enquanto você escreve; você também pode pedir-lhe para refatorar uma grande base de código, escrever documentação e muito mais.
{% hint style="info" %}
**💡 Dica**: Você pode usar assistentes de IA como Cursor, OpenDCL ou Claude Code para construir scenes inteiras a partir de descrições em linguagem natural — sem experiência em TypeScript necessária. Veja [Vibe Coding com IA](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/vibe-coding.md) para começar.
{% endhint %}
## Linguagens e sintaxe suportadas
A Decentraland emprega [TypeScript (.ts)](https://www.typescriptlang.org/docs/handbook/jsx.html) como a linguagem padrão para escrever scenes.
TypeScript é um superset de JavaScript, então se você está familiarizado com JavaScript, verá que é quase a mesma coisa, mas TypeScript inclui declarações de tipos. Graças às declarações de tipos, é possível ter recursos como autocompletar e melhores dicas de depuração; isso acelera o desenvolvimento e permite a criação de uma base de código mais sólida. Esses recursos são componentes essenciais para uma boa experiência de desenvolvimento.
Quando uma scene é compilada, o código TypeScript que você escreveu é compilado em JavaScript minificado, para torná-lo mais leve. O código-fonte original em TypeScript nunca é enviado para os servidores, apenas a versão JavaScript compilada.
### Outras linguagens
Você pode usar outra ferramenta ou linguagem em vez de TypeScript e compilá-la para JavaScript, desde que os seus scripts compilados estejam contidos num único ficheiro JavaScript que corresponda ao path definido no `main` campo do `scene.json` file da sua scene (por padrão *bin/index.js*). Todas as declarações de tipos fornecidas são feitas em TypeScript, e outras linguagens e transpilers não são oficialmente suportados.
## Scenes
O conteúdo que você faz deploy para o seu LAND chama-se um **scene**. Uma scene é um programa interativo que renderiza conteúdo 3D; isso pode ser um jogo, uma experiência interativa, uma galeria de arte, o que você quiser!
Scenes são feitas deploy para LAND virtual na Decentraland. LAND é um asset escasso e não fungível mantido num smart contract Ethereum. Faça deploy para um único **parcel**, um lote de LAND de 16 metros por 16 metros, ou para múltiplas parcels adjacentes.
Quando os players visitam a Decentraland, eles descarregam e renderizam o conteúdo de cada scene à medida que atravessam o mapa. Eles descarregam as scenes quando se afastam delas.
Você também pode executar uma scene localmente na sua máquina executando uma preview a partir da CLI.
## Entities e Components
As scenes tridimensionais na Decentraland baseiam-se numa [Entity-Component-System](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system) architecture, onde tudo numa scene é uma *entity*. Entities têm *components*, cada component dá à entity a que pertence propriedades específicas. É provável que uma entity de uma porta tenha pelo menos um component Transform (que define position, rotation e scale) e outro para lhe dar uma shape. Components são apenas um lugar para armazenar data; por si sós, não executam quaisquer actions.
.png?alt=media)
```ts
export function main() {
// Criar uma entity
const door = engine.addEntity()
// Dar à entity uma posição por meio de um component Transform
Transform.create(door, {
position: Vector3.create(5, 1, 5),
})
// Dar à entity uma shape visível por meio de um component GltfContainer
GltfContainer.create(door, {
src: 'assets/models/door.glb',
})
}
```
Entities podem estar aninhadas dentro de outras entities para formar uma estrutura em árvore. Se você está familiarizado com desenvolvimento web, pode achar útil pensar nas entities como elementos numa árvore DOM e nos components como os atributos de cada um desses elementos.
.png?alt=media)
Entities são um conceito abstrato. Uma entity é apenas um id, usado como referência para agrupar diferentes components.
Vê [Entities e components](/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md) para uma análise aprofundada destes dois conceitos e de como são usados pelas scenes da Decentraland.
### Custom components
O conjunto padrão de components (como `Transform`, `GltfContainer`, `Material`, etc.) é interpretado pelo engine e tem consequências diretas sobre a aparência da entity, a sua posição, se emite sons, etc.
Você também pode definir *components customizados* para armazenar data que possa ser útil para as mecânicas na sua scene. O engine não saberá interpretar o que significam os values nesses components, e eles não terão quaisquer consequências diretas sobre a forma como a scene é renderizada. No entanto, você pode escrever lógica no código da sua scene para monitorizar esses values e responder a eles. Por exemplo, você pode definir um component customizado "doorState" para acompanhar o estado aberto/fechado da door. Nesse caso, o component não é mais do que um lugar para armazenar um valor que acompanha esse estado. Para ver a door abrir e fechar na sua scene, você tem então de implementar separadamente a lógica que usa esses values para afetar a rotation da door, um value do `Transform` component que o engine sabe interpretar.
Vê [Components Personalizados](/creator/content-creator-pt/scenes-sdk7/arquitetura/custom-components.md) para mais informações.
### Obter entities pelo nome
As entities adicionadas através de drag-and-drop no Scene Editor no Creator Hub também podem ser acedidas via código para as editar mais e adicionar comportamento.
Use `engine.getEntityOrNullByName()` para obter uma entity, passando o nome atribuído à entity na UI do Scene Editor. Cada uma deve ter um nome único.
```ts
function main() {
const door = engine.getEntityOrNullByName('door3')
}
```
Depois, você pode fazer o que quiser com essa entity, como adicionar novos components, modificar os components existentes, duplicá-la ou eliminá-la.
Vê [Obter entity pelo nome](/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md#get-an-entity-by-name) para mais informações.
Se a entity for uma [Smart item](/creator/content-creator-pt/scene-editor/interatividade/smart-items.md), você também pode chamar o seu **Actions** ou subscrever-se ao seu **Triggers** via código. Veja [Itens de referência](/creator/content-creator-pt/scene-editor/estender-com-codigo/reference-items.md).
## Systems
Entities e components são lugares para armazenar informações sobre os objects numa scene. *Systems* contêm functions que alteram as informações armazenadas em components ao longo do tempo.
Os Systems são onde implementamos a lógica do jogo; eles executam as actions que precisam de ser updated ou verificadas periodicamente em cada tick do game loop.
Um system é uma function pura e simples que é chamada uma vez em cada tick (até 30 vezes por segundo), seguindo o [*padrão de update*](http://gameprogrammingpatterns.com/update-method.html).
```ts
// System básico
function mySystem() {
console.log('o meu system está a funcionar')
}
engine.addSystem(mySystem)
// System com dt
function mySystemDT(dt: number) {
console.log('tempo desde o último frame: ', dt)
}
engine.addSystem(mySystemDT)
```
Uma única scene pode ter 0 ou muitos Systems a correr ao mesmo tempo. Os Systems podem ser ativados ou desativados em momentos diferentes durante a duração da scene. Em geral, é boa prática manter comportamentos independentes em Systems separados.
Vê [Systems](/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md) para mais detalhes sobre como os Systems são usados numa scene.
### O game loop
O [game loop](http://gameprogrammingpatterns.com/game-loop.html) é a espinha dorsal do código de uma scene da Decentraland. Percorre parte do código em intervalos regulares e faz o seguinte:
* Ouvir a input do player
* Atualizar a scene
* Renderizar novamente a scene
Na maioria dos programas de software tradicionais, todos os events são acionados diretamente pelas actions do player. Nada no estado do programa muda até o player clicar num button, abrir um menu, etc.
Mas os ambientes interativos e os jogos são diferentes disso. Nem todas as mudanças na scene são necessariamente causadas pelas actions de um player. A sua scene pode ter objects animados que se movem por conta própria ou até personagens não jogáveis que têm a sua própria IA. Algumas actions do player também podem levar vários ticks para serem concluídas; por exemplo, se a abertura de uma door precisar de levar um segundo inteiro, a rotation da door tem de ser atualizada incrementalmente cerca de 30 vezes à medida que ela se move.
Chamamos a cada iteração do loop um *tick*. As scenes da Decentraland são renderizadas a 30 ticks por segundo, sempre que possível. Se a máquina estiver com dificuldades para renderizar cada tick, isso pode resultar em updates menos frequentes.
Em cada tick, a scene é updated; depois, a scene é renderizada novamente com base nos values atualizados.
Nas scenes da Decentraland, não existe um game loop explicitamente declarado, mas sim os [Systems](/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md) da scene constituem o game loop.
A compilação e renderização da scene é feita no backend, você não precisa lidar com isso enquanto desenvolve a sua scene.
## Consultar components
Você pode [consultar components](/creator/content-creator-pt/scenes-sdk7/arquitetura/querying-components.md) com o método `engine.getEntitiesWith(...components)` para acompanhar todas as entities na Scene que tenham certos components.
Muitas vezes faz sentido consultar components dentro de um [system](/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md), para depois iterar sobre cada uma das entities retornadas e executar o mesmo conjunto de actions em cada uma.
Se você tentar iterar sobre todas as entities na scene em cada tick do game loop, isso pode ter um custo significativo em performance. Ao referir-se apenas às entities devolvidas por uma query, você garante que está apenas a lidar com as que são relevantes.
```ts
// Defina um System
function boxHeightSystem(dt: number) {
// consultar entities que incluam tanto components MeshRenderer como Transform
for (const [entity] of engine.getEntitiesWith(MeshRenderer, Transform)) {
const transform = Transform.get(entity)
console.log('uma box está à altura: ', transform.position.y)
}
}
// Adicione o system ao engine
engine.addSystem(boxHeightSystem)
```
## lifecycle da Scene
Se você começar a escrever linhas soltas de código diretamente em `index.ts`, o seu código pode estar a faltar algum contexto importante. Por exemplo, estará a faltar informação sobre a entity do player, ou sobre entities que foram adicionadas via drag-and-drop no Creator Hub. No momento em que as suas linhas de código são lidas, essas coisas ainda não estão carregadas.
Para evitar essa situação, é sempre recomendado escrever o código inicial de carregamento da sua scene usando a `main()` function (no `index.ts` file) como ponto de entrada. Esta function só é executada depois de todo o contexto inicial da scene já estar carregado; isso inclui tudo o que foi adicionado via UI do Scene Editor.
Você pode escrever o seu código fora da `main()` function quando:
* O código é chamado indiretamente por `main()`
* O código define um system ou adiciona um system ao engine
* O código está dentro de uma [async function](/creator/content-creator-pt/scenes-sdk7/padroes-de-programacao/async-functions.md)
{% hint style="warning" %}
**📔 Nota**: Quando o código dentro de uma async function ou de um system é executado pela primeira vez, tudo na scene já está devidamente inicializado.
[Custom Component](/creator/content-creator-pt/scenes-sdk7/arquitetura/custom-components.md) As definições são uma exceção; estas devem sempre ser escritas fora da `main()` function, num ficheiro separado. Precisam de ser interpretadas antes de `main()` ser executado.
{% endhint %}
## Mutabilidade
Você pode escolher lidar com versões mutáveis ou imutáveis (read-only) de um component. A `.get()` function num component devolve uma versão imutável do component. Você só pode ler os seus values, mas não pode alterar nenhuma das suas properties.
O `.getMutable()` function devolve uma representação do component que permite alterar os seus values. Use versões mutáveis apenas quando planeia fazer alterações a um component. Lidar com versões imutáveis de components resulta num enorme ganho de performance.
```ts
// obter uma versão imutável (read-only)
const immutableTransform = Transform.get(myEntity)
// o seguinte NÃO funciona:
// \timmutableTransform.position.y = 2
const mutableTransform = Transform.getMutable(myEntity)
// o seguinte ALTERA a posição da entity
mutableTransform.position.y = 2
```
Vê [dados mutáveis](/creator/content-creator-pt/scenes-sdk7/padroes-de-programacao/mutable-data.md) para mais detalhes.
## Juntando tudo
O *engine* é o que fica entre *entities*, e *components* por um lado e *systems* por outro.
.png?alt=media)
Todos os values armazenados nos components na scene representam o estado da scene naquele momento. Em cada tick do game loop, o engine executa as functions de cada um dos Systems para atualizar os values armazenados nos components.
Depois de todos os Systems correrem, os components em cada entity terão novos values. Quando o engine renderiza a scene, usará esses novos values atualizados e os players verão as entities a mudar para corresponder aos seus novos estados.
```ts
export function main() {
// Criar uma entity
const cube = engine.addEntity()
// Dar à entity uma posição por meio de um component Transform
Transform.create(cube, {
position: Vector3.create(5, 1, 5),
})
// Dar à entity uma shape visível através de um component MeshRenderer
MeshRenderer.setBox(cube)
}
// Defina um System
function rotationSystem(dt: number) {
// consultar entities que incluam tanto components MeshRenderer como Transform
for (const [entity] of engine.getEntitiesWith(MeshRenderer, Transform)) {
const transform = Transform.getMutable(entity)
transform.rotation = Quaternion.multiply(
transform.rotation,
Quaternion.fromAngleAxis(dt * 10, Vector3.Up())
)
}
}
// Adicione o system ao engine
engine.addSystem(rotationSystem)
```
No exemplo acima, uma `cube` entity e um `rotationSystem` system são adicionados ao engine. O `cube` entity tem um `Transform`, e um `MeshRenderer` component. Em cada tick do game loop, o `rotationSystem` system é chamado, e altera os values de rotation no `Transform` component do `cube` entity.
Note que a maior parte do código acima é executada apenas uma vez, ao carregar a scene. A exceção é o `rotationSystem` system, que é chamado em cada tick do game loop.
## Desacoplamento da scene
As suas scenes não correm no mesmo contexto que o engine (também conhecido como a main thread). Criámos o SDK de uma forma totalmente desacoplada do rendering engine. Concebemo-lo assim por razões de segurança e de performance.
Devido a este desacoplamento, o código da sua scene não tem acesso ao DOM nem ao `window` object, por isso não pode aceder a dados como o browser ou a localização geográfica do player.
O desacoplamento funciona através do protocolo RPC; este protocolo atribui uma pequena parte do client apenas para renderizar a scene e controlar events.
Também abstraímos o protocolo de comunicação. Isto permite-nos executar as scenes localmente num WebWorker.
Não queremos que os developers intervenham com os internals do engine nem sequer precisem de saber o que existe dentro do engine. Precisamos de garantir uma experiência consistente para os players em todo o mapa da Decentraland, e os erros têm mais probabilidade de acontecer nesse nível "baixo".
Este desacoplamento também é importante para evitar que scenes vizinhas interfiram com a experiência dos players enquanto estão na scene de outra pessoa. Um player pode ter várias scenes próximas carregadas ao mesmo tempo, cada uma a correr o seu próprio código. Algumas actions (como abrir external links, ou mover o player) só são permitidas quando o player está em pé nessa scene específica, e não se a scene estiver carregada mas o player estiver fora.
## Tree Shaking
Ao converter o código-fonte em TypeScript para o código compilado em JavaScript minificado, o processo realiza [tree shaking](https://en.wikipedia.org/wiki/Tree_shaking) para garantir que apenas as partes do código que estão realmente a ser usadas são convertidas. Isto ajuda a manter o código final da scene o mais leve possível. É especialmente útil quando se usam libraries externas, uma vez que muitas vezes estas libraries incluem muita funcionalidade que não é usada e que, de outra forma, tornaria a scene mais pesada.
Como consequência do tree shaking, qualquer código que você quer que a sua scene execute precisa de ser referenciado de uma forma ou de outra pelos entry points do seu código: a `main()` function no `index.ts`. Os Systems também podem, alternativamente, ser adicionados ao engine no `index.ts` file, sem referenciar `main()`. Qualquer código que não seja explicitamente ou indiretamente referenciado por estes files não entrará na scene.
Por exemplo, suponha que você tem um file chamado `extraContent.ts` com o seguinte conteúdo, a entity não será renderizada e o system não começará a ser executado:
```ts
// extraContent.ts
const myEntity = engine.addEntity()
Transform.create(myEntity, {
position: { x: 8, y: 0, z: 8 },
})
MeshRenderer.setBox(myEntity)
function mySystem(dt: number) {
console.log('system a executar')
}
engine.addSystem(mySystem)
```
Para o fazer funcionar como parte da sua scene, você pode referenciá-lo a partir de `index.ts` da seguinte forma:
```ts
// em extraContent.ts
export function addEntities() {
const myEntity = engine.addEntity()
Transform.create(myEntity, {
position: { x: 8, y: 0, z: 8 },
})
MeshRenderer.setBox(myEntity)
}
export function mySystem(dt: number) {
console.log('system a executar')
}
/////////////////////////////
// em index.ts
import { addEntities, mySystem } from './extraContent'
export function main() {
addEntities()
}
engine.addSystem(mySystem)
```
A exceção a esta regra são as definições de custom components. Estas não devem ser acedidas através do `main()` function entry point, pois precisam de ser interpretadas antes de qualquer outra coisa.
## Imports
Todas as functions, objects, components e outros elementos usados pela scene devem ser importados para cada file para poder usá-los. Isto é uma consequência de [tree-shaking](#tree-shaking), pois evita empacotar todo o SDK e inclui apenas as partes que a scene usa.
Os snippets ao longo da documentação omitem as linhas de import no início de cada file para os manter limpos, mas, para funcionarem, você deve adicioná-las à scene.
Ao usar o VS Studio Code para escrever as suas scenes, as opções inteligentes de auto-completar devem tratar dos imports por si quando escreve, sem que você tenha de ter conhecimento disso.
Quando você cola um snippet na sua scene, porém, provavelmente verá alguns elements marcados a vermelho, que não estão importados nesse file. Para corrigir isso:
* Clique em cada palavra sublinhada
* Clique no ícone da lâmpada à esquerda da linha
* Selecionar **Adicionar importação de**
* Uma linha de import aparece no início do file.
Se houver muitas coisas diferentes para importar, você também pode selecionar **Adicionar todos os imports em falta** no mesmo dropdown.
Note que os imports devem ser feitos em cada file onde um element é usado.
O VS Studio Code deve conseguir resolver por si só os caminhos corretos para os seus imports. Se, por qualquer razão, estiver a ter dificuldades com isso, uma dica é colar as seguintes instruções de import vazias no início do seu file. O VS Studio deve conseguir tratar do resto.
```ts
import {} from '@dcl/sdk/ecs'
import {} from '@dcl/sdk/math'
```
## Versões do SDK
Ao desenvolver uma nova scene, você usa a `@latest` versão estável do SDK por padrão.
Você pode instalar a `@next` versão do SDK se quiser aproveitar ou pré-visualizar funcionalidades futuras que ainda não entraram na versão estável mais recente.
Para isso, abra o `package.json` file da sua scene e altere as seguintes linhas:
```json
"devDependencies": {
"@dcl/js-runtime": "next",
"@dcl/sdk": "next"
},
```
Depois, execute o seguinte comando na pasta do projeto da sua scene:
```
npm i
```
Vê [gerir dependências](/creator/content-creator-pt/scenes-sdk7/libraries/manage-dependencies.md) para mais detalhes.
{% hint style="warning" %}
**📔 Nota**: Tenha em mente que a versão @next pode ter problemas de vez em quando. A sintaxe e o nome de novas funcionalidades podem mudar antes de serem lançados numa versão estável.
{% endhint %}
---
# 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/scenes-sdk7/primeiros-passos/coding-scenes.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.