> 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 vai ajudar você a entender como as coisas funcionam no client e no SDK do Decentraland.
## As ferramentas de desenvolvimento
Em um nível muito alto, o Decentraland **Kit de Desenvolvimento de Software** (SDK) permite que você faça o seguinte:
* Gerar um *projeto padrão* contendo uma Decentraland scene, incluindo todos os assets necessários para renderizar e executar seu conteúdo.
* Construir, testar e visualizar o conteúdo da sua scene localmente no seu navegador web - totalmente offline, e sem precisar fazer nenhuma transação em Ethereum ou possuir LAND.
* Escrever código TypeScript usando a Decentraland API para adicionar comportamento interativo e dinâmico à scene.
* Fazer upload do conteúdo da sua scene para o content server.
* Vincular seus tokens LAND à URL do conteúdo que você enviou.
Nosso SDK inclui o seguinte:
* **O Creator Hub**: Um aplicativo independente que, entre outras coisas, permite criar scenes com uma interface fácil de arrastar e soltar. Você pode executar previews, depurar, editar código e publicar. [Leia mais](/creator/content-creator-pt/scene-editor/primeiros-passos/about-editor.md)
* **O Decentraland ECS**: Um pacote TypeScript contendo o framework de métodos auxiliares que permite criar experiências interativas. Use-o para criar e manipular objetos na scene e também para facilitar transações no mundo entre jogadores ou outros aplicativos. ( [referência ECS mais recente](https://github.com/decentraland/ecs-reference/blob/master/docs-latest/decentraland-ecs.md))
* **Exemplos de scenes**: Inspire-se e adote boas práticas de código a partir dos [exemplos de scenes](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 possuir tokens LAND. Desenvolver e testar uma scene pode ser feito completamente offline, sem a necessidade de implantar uma scene na rede Ethereum (o sistema que o Decentraland usa para estabelecer a propriedade de LAND, de um Decentraland NAME) ou no content server.
Você deve ter:
* **O Creator Hub**: Um aplicativo independente que, entre outras coisas, permite criar scenes com uma interface fácil de arrastar e soltar. Você pode executar previews, depurar, editar código e publicar. [Leia mais](/creator/content-creator-pt/scene-editor/primeiros-passos/about-editor.md).
Se você planeja editar o código da scene, também precisará instalar um dos seguintes:
* 
**Visual Studio Code**: Baixe-o [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 marca erros de sintaxe, completa automaticamente enquanto você escreve e até mostra sugestões inteligentes que dependem do contexto em que você está. Você também pode clicar em um objeto no código para ver a definição completa da sua class e quais atributos ela suporta.
* 
**Cursor AI**: Baixe-o [aqui](https://www.cursor.com/). Um poderoso editor de código integrado com IA. Ele permite que você escolha diferentes modelos de IA para ajudar você a escrever código, e todos eles são gratuitos. O assistente de IA não apenas completa automaticamente enquanto você escreve; você também pode pedir que ele refatore uma base de código grande, escreva 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 necessidade de experiência com TypeScript. Veja [Vibe Coding com IA](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/vibe-coding.md) para começar.
{% endhint %}
## Idiomas e sintaxe suportados
O Decentraland emprega [TypeScript (.ts)](https://www.typescriptlang.org/docs/handbook/jsx.html) como a linguagem padrão para escrever scenes.
TypeScript é um superconjunto de JavaScript, então, se você estiver 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 dicas de depuração melhores; isso acelera os tempos de desenvolvimento e permite a criação de uma base de código mais sólida. Esses recursos são todos 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 aos servidores, apenas a versão compilada em JavaScript.
### Outros idiomas
Você pode usar outra ferramenta ou linguagem em vez de TypeScript e compilá-la para JavaScript, desde que seus scripts compilados estejam contidos em um único arquivo JavaScript correspondente ao caminho definido no `main` campo do `scene.json` arquivo da sua scene *bin/index.js*(por padrão
## Scenes
O conteúdo que você implanta no seu LAND é chamado de **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!
As scenes são implantadas em LAND virtual no Decentraland. LAND é um ativo escasso e não fungível mantido em um smart contract Ethereum. Implante em um único **parcela**, um lote de LAND de 16 metros por 16 metros, ou em várias parcelas adjacentes.
Quando os jogadores visitam o Decentraland, eles baixam e renderizam o conteúdo de cada scene conforme caminham pelo mapa. Eles descarregam as scenes à medida que se afastam delas.
Você também pode executar uma scene localmente na sua máquina executando um preview a partir da CLI.
## Entities and Components
As scenes tridimensionais no Decentraland são baseadas em uma [Entity-Component-System](https://en.wikipedia.org/wiki/Entity%E2%80%93component%E2%80%93system) arquitetura, em que tudo em uma scene é uma *entity*Entity *components*, cada Component dá à Entity à qual pertence propriedades específicas. Uma Entity de porta provavelmente terá pelo menos um Transform component (que define posição, rotação e escala) e outro para fornecer uma forma. Components são apenas um lugar para armazenar dados; eles não executam nenhuma ação por si mesmos.
.png?alt=media)
```ts
export function main() {
// Criar uma entity
const door = engine.addEntity()
// Dar à entity uma posição por meio de um Transform component
Transform.create(door, {
position: Vector3.create(5, 1, 5),
})
// Dar à entity uma forma visível por meio de um GltfContainer component
GltfContainer.create(door, {
src: 'assets/models/door.glb',
})
}
```
Entities podem ser aninhadas dentro de outras Entities para formar uma estrutura em árvore. Se você estiver familiarizado com desenvolvimento web, talvez ache útil pensar em Entities como elementos em uma árvore DOM e em 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.
Veja [Entities e components](/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md) para uma visão aprofundada desses dois conceitos e de como eles são usados pelas scenes do Decentraland.
### Custom components
O conjunto padrão de Components (como `Transform`, `GltfContainer`, `Material`, etc) é interpretado pelo engine e tem consequências diretas em como a Entity ficará, sua posição, se emite sons, etc.
Você também pode definir *custom components* para armazenar dados que podem ser úteis para a mecânica da sua scene. O engine não saberá como interpretar o que os valores nesses Components significam, eles não terão consequências diretas sobre como a scene é renderizada. No entanto, você pode escrever lógica no código da sua scene para monitorar esses valores e responder a eles. Por exemplo, você pode definir um Custom Component "doorState" para acompanhar o estado aberto/fechado da porta. Nesse caso, o Component nada mais é do que um lugar para armazenar um valor que acompanha esse estado. Para ver a porta abrir e fechar na sua scene, você precisa então implementar separadamente a lógica que usa esses valores para afetar a rotação da porta, um valor do component que o engine sabe interpretar. `Transform` component que o engine sabe interpretar.
Veja [Components personalizados](/creator/content-creator-pt/scenes-sdk7/arquitetura/custom-components.md) para mais informações.
### Buscar Entities pelo nome
As Entities adicionadas ao arrastar e soltar no Scene Editor do Creator Hub também podem ser acessadas via código para editá-las ainda mais e adicionar comportamento.
Use `engine.getEntityOrNullByName()` para buscar 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')
}
```
Você pode então fazer qualquer coisa que quiser com essa Entity, como adicionar novos Components, modificar seus Components existentes, duplicá-la ou deletá-la.
Veja [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 um [Smart item](/creator/content-creator-pt/scene-editor/interatividade/smart-items.md), você também pode chamar seu **Actions** ou se inscrever em seu **Triggers** via código. Veja [Itens de referência](/creator/content-creator-pt/scene-editor/expandir-com-codigo/reference-items.md).
## Systems
Entities e Components são lugares para armazenar informações sobre os objetos em uma scene. *Systems* contêm funções que alteram as informações armazenadas nos Components ao longo do tempo.
Systems são onde implementamos a lógica do jogo; eles executam as ações que precisam ser atualizadas ou verificadas periodicamente a cada tick do game loop.
Um System é uma função pura e simples que é chamada uma vez a cada tick (até 30 vezes por segundo), seguindo o [*padrão de atualização*](http://gameprogrammingpatterns.com/update-method.html).
```ts
// System básico
function mySystem() {
console.log('meu System está rodando')
}
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 em execução ao mesmo tempo. Systems podem ser ativados ou desativados em diferentes momentos durante a duração da scene. Geralmente é uma boa prática manter comportamentos independentes em Systems separados.
Veja [Systems](/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md) para mais detalhes sobre como Systems são usados em uma scene.
### O game loop
O [game loop](http://gameprogrammingpatterns.com/game-loop.html) é a espinha dorsal do código de uma scene do Decentraland. Ele percorre parte do código em um intervalo regular e faz o seguinte:
* Escutar a entrada do player
* Atualizar a scene
* Renderizar novamente a scene
Na maioria dos programas de software tradicionais, todos os events são disparados diretamente pelas ações do player. Nada no estado do programa mudará até que o player clique em um botão, abra um menu etc.
Mas ambientes interativos e games são diferentes disso. Nem todas as mudanças na scene são necessariamente causadas pelas ações de um player. Sua scene pode ter objetos animados que se movem sozinhos ou até personagens não jogáveis que têm sua própria IA. Algumas ações do player também podem levar vários ticks para serem concluídas; por exemplo, se a abertura de uma door precisar levar um segundo inteiro, a rotação da door deve ser atualizada incrementalmente cerca de 30 vezes enquanto ela se move.
Chamamos cada iteração do loop de um *tick*. As scenes do Decentraland são renderizadas a 30 ticks por segundo, sempre que possível. Se a máquina estiver com dificuldade para renderizar cada tick, isso pode resultar em atualizações menos frequentes.
A cada tick, a scene é atualizada; em seguida, a scene é renderizada novamente, com base nos valores atualizados.
Nas scenes do Decentraland, não há um game loop explicitamente declarado, mas sim os [Systems](/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md) Systems da scene compõem o game loop.
A compilação e a renderização da scene são realizadas no backend; você não precisa lidar com isso ao desenvolver sua scene.
## Consultando 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 têm determinados components.
Muitas vezes faz sentido consultar Components dentro de um [system](/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md), para então iterar sobre cada uma das Entities retornadas e executar o mesmo conjunto de ações em cada uma.
Se você tentar iterar sobre todas as Entities da scene a cada tick do game loop, isso pode ter um custo significativo de performance. Ao se referir apenas às Entities retornadas por uma query, você garante que está lidando apenas com aquelas que são relevantes.
```ts
// Defina um System
function boxHeightSystem(dt: number) {
// query para Entities que incluam tanto MeshRenderer quanto Transform Components
for (const [entity] of engine.getEntitiesWith(MeshRenderer, Transform)) {
const transform = Transform.get(entity)
console.log('uma box está na altura: ', transform.position.y)
}
}
// Adicione o system ao engine
engine.addSystem(boxHeightSystem)
```
## ciclo de vida da cena
Se você começar a escrever linhas soltas de código diretamente em `index.ts`, seu código pode estar sem algum contexto importante. Por exemplo, você estará sem informações sobre a PlayerEntity ou sobre Entities que foram adicionadas via arrastar e soltar no Creator Hub. No momento em que suas linhas de código forem lidas, essas coisas ainda não terão sido carregadas.
Para evitar esse cenário, é sempre recomendável escrever o código de carregamento inicial da sua scene usando a `main()` função (no `index.ts` arquivo) como ponto de entrada. Essa função é executada somente depois que todo o contexto inicial da scene já tiver sido carregado, isso inclui qualquer coisa adicionada via a UI do Scene Editor.
Você pode escrever seu código fora da `main()` função 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 um [função async](/creator/content-creator-pt/scenes-sdk7/padroes-de-programacao/async-functions.md)
{% hint style="warning" %}
**📔 Observação**: Quando o código dentro de uma função async 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) definições são uma exceção, elas devem sempre ser escritas fora da `main()` função, em um arquivo separado. Elas precisam ser interpretadas antes de `main()` ser executado.
{% endhint %}
## Mutabilidade
Você pode escolher lidar com versões mutáveis ou imutáveis (somente leitura) de um Component. A `.get()` função em um Component retorna uma versão imutável do Component. Você só pode ler seus valores, mas não pode alterar nenhuma de suas propriedades.
O `.getMutable()` função retorna uma representação do Component que permite alterar seus valores. Use versões mutáveis somente quando planejar fazer alterações em um Component. Lidar com versões imutáveis de Components resulta em um grande ganho de performance.
```ts
// buscar uma versão imutável (somente leitura)
const immutableTransform = Transform.get(myEntity)
// o seguinte NÃO funciona:
// \timmutableTransform.position.y = 2
const mutableTransform = Transform.getMutable(myEntity)
// a seguir ALTERA a posição da Entity
mutableTransform.position.y = 2
```
Veja [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 valores armazenados nos Components da scene representam o estado da scene naquele momento. A cada tick do game loop, o engine executa as funções de cada um dos Systems para atualizar os valores armazenados nos Components.
Depois que todos os Systems são executados, os Components em cada Entity terão novos valores. Quando o engine renderiza a scene, ele usará esses novos valores atualizados e os players verão as Entities mudarem 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 Transform component
Transform.create(cube, {
position: Vector3.create(5, 1, 5),
})
// Dar à Entity uma forma visível por meio de um componente MeshRenderer
MeshRenderer.setBox(cube)
}
// Defina um System
function rotationSystem(dt: number) {
// query para Entities que incluam tanto MeshRenderer quanto Transform Components
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, um `cube` Entity e um `rotationSystem` System são adicionados ao engine. O `cube` Entity possui um `Transform`, e um `MeshRenderer` component. A cada tick do game loop, o `rotationSystem` System é chamado e altera os valores de rotação 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 a cada tick do game loop.
## Desacoplamento da Scene
Suas scenes não são executadas no mesmo contexto que o engine (também conhecido como thread principal). Criamos o SDK de forma totalmente desacoplada do engine de renderização. Projetamos assim por motivos de segurança e desempenho.
Devido a esse desacoplamento, o código da sua scene não tem acesso ao DOM nem ao `window` object, então você não pode acessar dados como o navegador ou a localização geográfica do player.
O desacoplamento funciona usando o protocolo RPC; esse protocolo atribui uma pequena parte do client apenas para renderizar a scene e controlar events.
Também abstraímos o protocolo de comunicação. Isso nos permite executar as scenes localmente em um WebWorker.
Não queremos que developers interfiram nos detalhes internos do engine ou sequer precisem saber o que há dentro dele. Precisamos garantir uma experiência consistente para os players em todo o mapa do Decentraland, e erros têm mais chance de acontecer nesse nível "baixo".
Esse desacoplamento também é importante para evitar que scenes vizinhas interfiram na experiência dos players enquanto eles estiverem na scene de outra pessoa. Um player pode ter várias scenes próximas carregadas ao mesmo tempo, cada uma executando seu próprio código. Algumas ações (como abrir links externos 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 sendo realmente usadas sejam convertidas. Isso ajuda a manter o código final da scene o mais leve possível. Isso é especialmente útil ao usar bibliotecas externas, já que muitas vezes essas bibliotecas incluem muita funcionalidade que não é usada e que, de outra forma, aumentaria o tamanho da scene.
Como consequência do tree shaking, qualquer código que você queira que sua scene execute precisa ser referenciado de uma forma ou de outra pelos pontos de entrada do seu código: a `main()` função em `index.ts`. Systems também podem, alternativamente, ser adicionados ao engine no `index.ts` arquivo, sem referenciar `main()`. Qualquer código que não seja explicitamente ou indiretamente referenciado por esses arquivos não entrará na scene.
Por exemplo, suponha que você tenha um arquivo 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 em execução')
}
engine.addSystem(mySystem)
```
Para fazê-lo 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 em execução')
}
/////////////////////////////
// em index.ts
import { addEntities, mySystem } from './extraContent'
export function main() {
addEntities()
}
engine.addSystem(mySystem)
```
A exceção a essa regra são as definições de custom components. Elas não devem ser acessadas por meio do `main()` ponto de entrada da função, pois precisam ser interpretadas antes de todo o resto.
## Imports
Todas as funções, objetos, Components e outros elementos usados pela scene devem ser importados para cada arquivo para usá-los. Isso é uma consequência do [tree-shaking](#tree-shaking), pois ele evita empacotar o SDK inteiro e inclui apenas as partes que a scene usa.
Os trechos ao longo da documentação omitem as linhas de import no início de cada arquivo para mantê-los limpos, mas para que funcionem você precisa adicioná-las à scene.
Ao usar o VS Studio Code para escrever suas scenes, as opções inteligentes de autocompletar devem cuidar do tratamento dos imports para você enquanto você escreve, sem que você precise estar ciente disso.
No entanto, quando você cola um trecho na sua scene, provavelmente verá alguns elementos marcados em vermelho, que não estão importados nesse arquivo. Para corrigir isso:
* Clique em cada palavra sublinhada
* Clique no ícone da lâmpada à esquerda da linha
* Selecione **Adicionar importação de**
* Uma linha de import aparece no início do arquivo.
Se houver muitas coisas diferentes para importar, você também pode selecionar **Adicionar todos os imports ausentes** no mesmo menu suspenso.
Observe que os imports devem ser feitos em cada arquivo onde um elemento é usado.
O VS Studio Code deve ser capaz de resolver os caminhos corretos para seus imports por conta própria. Se por qualquer motivo estiver tendo dificuldade para fazer isso, um truque é colar as seguintes declarações de import vazias no início do seu arquivo. O VS Studio deve conseguir seguir a partir daí.
```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 visualizar recursos futuros que ainda não chegaram à versão estável mais recente.
Para fazer isso, abra o `arquivo package.json` arquivo da sua scene, e altere as seguintes linhas:
```json
"devDependencies": {
"@dcl/js-runtime": "next",
"@dcl/sdk": "next"
},
```
Em seguida, execute o seguinte comando na pasta do projeto da sua scene:
```
npm i
```
Veja [gerenciar dependências](/creator/content-creator-pt/scenes-sdk7/bibliotecas/manage-dependencies.md) para mais detalhes.
{% hint style="warning" %}
**📔 Observação**: Tenha em mente que a versão @next pode apresentar problemas de tempos em tempos. A sintaxe e o nome dos novos recursos podem mudar antes de serem lançados em uma 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 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/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 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.