> 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/sdk-101.md).
# Início Rápido do SDK
Crie sua primeira scene do Decentraland com o Creator Hub, o SDK e vibe coding assistido por IA usando o SDK Skills oficial.
Este tutorial guia você na criação da sua primeira cena, combinando as diferentes ferramentas disponíveis: o Scene Editor visual do Creator Hub, código escrito à mão usando o Decentraland SDK e assistência com IA **vibe coding**. Você usará os três juntos e aprenderá quando cada um se destaca.
## Como faço para criar uma scene do Decentraland?
1. **Instale o** [**Creator Hub**](https://decentraland.org/download/creator-hub), o aplicativo desktop oficial para criar, visualizar e publicar scenes. É a ferramenta recomendada para creators de todos os níveis de habilidade.
2. **Se você usar um assistente de programação com IA** (como Claude Code, Cursor ou Copilot), instale o oficial [Decentraland SDK Skills](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/vibe-coding.md) para que ele conheça os padrões verificados do SDK7: `npx skills add decentraland/sdk-skills`
3. **O** [**CLI**](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/using-the-cli.md) é uma alternativa para usuários avançados e fluxos de trabalho automatizados.
O restante deste tutorial percorre esse caminho recomendado passo a passo.
## Instale o Creator Hub
O Creator Hub permite que você crie, visualize e publique scenes do Decentraland. Baixe o Creator Hub [aqui](https://decentraland.org/download/creator-hub).
Para editar o código da sua scene, você também precisa de um editor de código. [Visual Studio Code](https://code.visualstudio.com/) e [Cursor](https://www.cursor.com/) são excelentes opções, mas qualquer editor de código funciona.
Leia o [guia de instalação](/creator/content-creator-pt/scene-editor/primeiros-passos/editor-installation.md) para mais detalhes.
## Crie sua primeira scene
1. Abra o Creator Hub.
2. Selecione a aba **Scenes** e clique em **New Scene**.
3. Escolha um template inicial. Para este exercício, escolha **Empty Scene**.
Esta etapa pode levar alguns minutos. Ela preenche sua pasta com o conjunto padrão de arquivos para uma scene básica. Quando isso terminar, você verá a grade vazia da sua scene.
## Adicione itens dos asset packs
Explore os **Asset packs** na seção inferior do Scene Editor e arraste alguns itens para sua scene. Qualquer item serve por enquanto.
Itens já colocados podem ser clicados e arrastados para reposicioná-los. Veja [Noções essenciais do Scene Editor](/creator/content-creator-pt/scene-editor/primeiros-passos/scene-editor-essentials.md#position-items) para mais detalhes.
{% hint style="info" %}
**💡 Dica**: cubra toda a scene com um item Ground. Itens do tipo **Ground** têm um ícone de balde de tinta. Se você arrastar um desses para sua scene, ele cobrirá todo o chão da sua scene com cópias desse item.
{% endhint %}
## Execute uma prévia
Clique no **Play** botão no menu superior para carregar sua scene dentro do Decentraland. Agora você pode explorar a scene como um avatar do Decentraland.
Você pode manter a janela de preview aberta enquanto trabalha: ela é atualizada toda vez que você faz uma alteração. Leia mais em [pré-visualizar uma scene](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/preview-scene.md).
## Assets 3D personalizados
Baixe este modelo 3D de um abacate em *GLB* a partir do seguinte [link](https://github.com/decentraland-scenes/avocado/raw/main/avocado-glb.zip) e descompacte-o.
Arraste o arquivo **avocado.glb** do seu explorador de arquivos para o painel inferior do Scene Editor (o mesmo painel que contém as **Asset Packs** e **Local Assets** abas) e clique em **Import**.
Agora você pode encontrar o **avocado.glb** modelo na **Local Assets** aba, dentro da pasta **Scene** . Arraste o arquivo para sua scene, como qualquer item dos Asset Packs.
## Edite o código da scene
Clique no **<> Code** botão no menu superior para abrir o projeto da sua scene no seu editor de código.
{% hint style="warning" %}
**📔 Observação**: se nada abrir, certifique-se de que você tem um editor de código como [Visual Studio Code](https://code.visualstudio.com/) ou [Cursor](https://www.cursor.com/) instalado.
{% endhint %}
Na margem esquerda do seu editor de código, você pode navegar pelos arquivos e pela estrutura de pastas do seu projeto. Abra o arquivo `index.ts` dentro da pasta `src` . O conteúdo deve se parecer com isto:
```ts
import {} from '@dcl/sdk/math'
import { engine } from '@dcl/sdk/ecs'
export function main() {}
```
As scenes do Decentraland são escritas em [TypeScript](https://www.typescriptlang.org/), usando o Decentraland SDK: uma biblioteca com tudo o que você precisa para posicionar conteúdo 3D, adicionar interatividade e controlar o que acontece na sua scene.
Este arquivo define uma função chamada `main()`, que é o ponto de entrada da scene: qualquer código que você colocar ali é executado quando a scene carrega pela primeira vez.
Você já arrastou um abacate para a scene visualmente. Agora vamos adicionar um segundo, desta vez escrevendo código. Substitua todo o conteúdo do seu `index.ts` arquivo pelo seguinte:
```ts
import { Vector3 } from '@dcl/sdk/math'
import { engine, Transform, GltfContainer } from '@dcl/sdk/ecs'
export function main() {
// crie uma Entity nova
let avocado2 = engine.addEntity()
// dê a ela um Transform
Transform.create(avocado2, {
position: Vector3.create(8, 0, 8),
})
// dê a ela um GLTF
GltfContainer.create(avocado2, {
src: 'assets/scene/avocado.glb',
})
}
```
Estas linhas criam uma nova [entity](/creator/content-creator-pt/scenes-sdk7/arquitetura/entities-components.md), dão a ela uma [forma](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/shape-components.md) com base no modelo 3D que você baixou e [definem sua posição](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/entity-positioning.md) por meio do **Transform** .
Como regra geral, o código que você escreve em `index.ts` deve estar todo dentro de `main()` (ou em outras funções referenciadas indiretamente por main). Veja [Scene lifecycle](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#scene-lifecycle) para mais detalhes.
Execute a prévia da scene: agora você deve ver dois abacates, o que você adicionou no Scene Editor e o que você adicionou via código.
{% hint style="warning" %}
**📔 Observação**: o segundo abacate existe **apenas no seu código**. Ele aparece quando você executa a scene, mas o canvas e a entity tree do Scene Editor não conseguem exibir entities criadas em `index.ts`. Não se assuste se você não o vir no editor. Isso é algo importante a ter em mente quando você mistura edição visual com código.
{% endhint %}
Ambos os abacates são construídos com as mesmas peças. Selecione o **primeiro** abacate no Scene Editor: o painel de propriedades mostra um **Transform** e um **GltfContainer** component com os mesmos tipos de campos que você acabou de escrever em código. São duas visões da mesma coisa.
## Adicione interatividade com um Script
Vamos fazer um abacate responder ao player. Poderíamos fazer isso adicionando código ao `index.ts` que já estávamos editando, mas em vez disso vamos usar o **Script component**: uma forma de anexar código diretamente a um item no Scene Editor. Isso mantém o comportamento de cada item autocontido e você pode até reutilizar o mesmo script em vários itens.
1. No Scene Editor, selecione o primeiro abacate (o que você arrastou; lembre-se, o abacate apenas de código não fica visível aqui).
2. Clique no **+** botão no topo do painel de propriedades e selecione **Script** para adicionar um Script component.
3. Clique em **+ Create New Script** e nomeie-o `AvocadoScript`.
4. Clique no **<> Code** botão no Script component para abrir o novo arquivo no seu editor de código.
O script é uma classe com três partes principais (comentários reduzidos por brevidade):
```ts
import { engine, Entity } from '@dcl/sdk/ecs'
import {} from '@dcl/sdk/math'
export class AvocadoScript {
constructor(
public src: string, // NÃO REMOVA
public entity: Entity, // NÃO REMOVA
// Adicione seus inputs personalizados abaixo
) {}
start() {
// Chamado uma vez, quando a scene carrega
}
update(dt: number) {
// Chamado a cada frame
}
}
```
* O **constructor** define parâmetros que aparecem como campos editáveis no Script component no Creator Hub. Não remova `src` ou `entity`.
* **`start()`** executa **uma vez**, quando a scene carrega. Use-o para configuração: criar components, registrar manipuladores de clique etc.
* **`update(dt)`** executa em **cada frame** do jogo, aproximadamente 30 vezes por segundo. Use-o para comportamento contínuo, como movimento. `dt` diz quantos segundos se passaram desde o último frame.
Dentro da classe, `this.entity` sempre se refere à entity que contém o Script component: neste caso, o seu abacate. É isso que torna os scripts reutilizáveis: anexe o mesmo script a dez itens, e cada um age sobre si mesmo.
### Faça vibe coding da sua primeira interação
Você pode escrever o código a seguir à mão, mas este é um ótimo momento para experimentar **vibe coding**: descrever o que você quer para um assistente de IA e deixar que ele escreva o código. A maioria dos editores de código já tem um встроído, como o chat do Cursor, o GitHub Copilot no VS Code ou [Claude Code](https://claude.com/product/claude-code). Você também pode escrever prompts fora do seu editor de código, como com o Claude Desktop ou o Claude Code na linha de comando.
Antes do seu primeiro prompt, instale o Decentraland SDK Skills para que a IA conheça os padrões do SDK e cometa muito menos erros:
```bash
npx skills add decentraland/sdk-skills
```
Esses skills são documentos de referência que a IA consulta sempre que não tem certeza de como fazer algo com o SDK, então ela escreve código correto em vez de adivinhar. Veja [Vibe Coding com IA](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/vibe-coding.md) para opções de configuração e dicas de prompts.
Agora tente um prompt como este:
> Em AvocadoScript.ts, faça com que o abacate registre uma mensagem no console quando o player clicar nele.
Você deve acabar com algo assim (ou cole você mesmo):
```ts
import { engine, Entity, pointerEventsSystem, InputAction } from '@dcl/sdk/ecs'
import {} from '@dcl/sdk/math'
export class AvocadoScript {
constructor(
public src: string,
public entity: Entity,
) {}
start() {
pointerEventsSystem.onPointerDown(
{
entity: this.entity,
opts: { button: InputAction.IA_POINTER },
},
() => {
console.log('CLICKED AVOCADO')
}
)
}
update(dt: number) {}
}
```
Ele adicionou algum comportamento de clique dentro da função `start()` . Precisamos definir o comportamento de clique apenas uma vez, e ele reagirá sempre que o player clicar no item. A `pointerEventsSystem.onPointerDown()` instrução define três coisas:
* O que `entity` os eventos de clique funcionam em: aqui `this.entity`, o abacate que contém o script.
* Um `objeto opts` : qual botão usar e outros argumentos opcionais que não estamos usando agora.
* Uma função que é executada toda vez que a entity é clicada.
Para ver a mensagem registrada, execute a prévia e abra o console clicando no  ícone no canto superior direito. Você também pode alterná-lo pressionando a tecla **\`** . Cada vez que você clicar no abacate, verá uma nova linha aparecer:
{% hint style="warning" %}
**📔 Observação**: para uma entity ser clicável, ela precisa ter uma geometria de collider. O modelo usado aqui já inclui uma. Veja [Colliders](https://github.com/decentraland/docs/tree/main/creator/sdk7/3d-modeling/colliders.md) para alternativas para modelos que não têm.
{% endhint %}
### Faça o abacate desaparecer
Vamos fazer o clique fazer algo mais empolgante agora! Peça ao seu assistente de IA:
> Quando o abacate for clicado, faça com que ele desapareça. Quero que ele desapareça com uma animação elástica de encolhimento. Também quero que a dica que vejo ao apontar para o abacate diga "Collect".
Você deve acabar com algo assim:
```ts
import { engine, Entity, pointerEventsSystem, InputAction, Tween, EasingFunction } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'
export class AvocadoScript {
constructor(
public src: string,
public entity: Entity,
) {}
start() {
pointerEventsSystem.onPointerDown(
{
entity: this.entity,
opts: { button: InputAction.IA_POINTER, hoverText: 'Collect' },
},
() => {
this.collect()
}
)
}
collect() {
Tween.setScale(
this.entity,
Vector3.One(),
Vector3.Zero(),
500,
EasingFunction.EF_EASEINBOUNCE
)
}
update(dt: number) {}
}
```
Vamos destrinchar o que a IA fez.
* Para fazer a animação elástica, ela usou um **Tween**. Um tween descreve uma transição gradual da posição, rotação ou escala de uma entity ao longo do tempo. Aqui `Tween.setScale()` encolhe o abacate do tamanho total (`Vector3.One()`) para nada (`Vector3.Zero()`) ao longo de 500 milissegundos, usando uma curva de easing elástica. Saiba mais sobre tweens em [mover entities](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/move-entities.md).
* Em vez de escrever o tween diretamente dentro da função de clique, ela criou um `método collect()` . Isso não é obrigatório (se a sua IA colocou o tween dentro da função de clique, também funciona), mas é uma boa prática: métodos mantêm o código legível e permitem reutilizar a mesma lógica em lugares diferentes.
* Para mostrar a dica "Collect" no abacate, ela definiu isso como o valor de `hoverText` .
Execute a prévia e clique no abacate: ele deve desaparecer com estilo.
{% hint style="warning" %}
**📔 Observação**: o abacate encolhe até o tamanho 0, mas a entity ainda existe. O ideal é deletar a entity depois que o tween terminar, para manter sua scene mais leve. Veja [Ao terminar o tween](/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/move-entities.md#on-tween-finished).
{% endhint %}
### Execute código a cada frame
Até agora, todo o nosso código foi executado em `start()`. Vamos usar `update()` para fazer o abacate girar continuamente. Substitua o constructor e `update()` por:
```ts
constructor(
public src: string,
public entity: Entity,
public speed: number = 45,
) {}
update(dt: number) {
const transform = Transform.getMutable(this.entity)
transform.rotation = Quaternion.multiply(
transform.rotation,
Quaternion.fromAngleAxis(this.speed * dt, Vector3.Up())
)
}
```
Você também precisará adicionar `Transform` e `Quaternion` aos imports no topo do arquivo, para que fiquem assim:
```ts
import { engine, Entity, pointerEventsSystem, InputAction, Tween, EasingFunction, Transform } from '@dcl/sdk/ecs'
import { Vector3, Quaternion } from '@dcl/sdk/math'
```
{% hint style="info" %}
**💡 Dica**: em vez de editar os imports manualmente, você pode clicar nos erros marcados pelo seu editor de código e deixá-lo adicioná-los automaticamente.
{% endhint %}
A cada frame, isso gira o abacate um pouco mais. Multiplicar por `dt` dt torna o movimento suave e independente da taxa de quadros: o abacate gira a 45 graus por segundo, não importa quão rápido a máquina do player esteja rodando.
Como `speed` é um parâmetro do constructor, ele também aparece como um campo no Script component no Creator Hub. Clique no ícone de atualização no canto superior direito do Script component para vê-lo e depois ajuste o valor sem tocar em nenhum código.
Cada entity armazena seu próprio valor para o campo **Speed** , então vários itens podem compartilhar o mesmo script, mas se comportar de maneira diferente. Experimente: copie o abacate com Ctrl + C e Ctrl + V, mova a cópia para que os dois não se sobreponham e defina uma speed diferente em cada um. Agora cada abacate gira em sua própria velocidade.
Scripts podem fazer muito mais, como expor ações que outros smart items podem acionar. Veja [Script component](/creator/content-creator-pt/scene-editor/expandir-com-codigo/script-component.md) para a visão completa.
## Faça referência a um item do Scene Editor
O Script component é a maneira mais fácil de dar comportamento a um único item, mas existe uma alternativa: seu código em `index.ts` pode buscar qualquer item que você adicionou visualmente, pelo nome, usando `engine.getEntityOrNullByName()`. Isso é útil quando uma parte da lógica envolve vários itens, ou quando você quer tudo em um só lugar. Use o nome que aparece na [entity tree](/creator/content-creator-pt/scene-editor/primeiros-passos/scene-editor-essentials.md#the-entity-tree).
Neste exemplo, usamos uma entity chamada **Yellow Crate**. Você pode usar qualquer item, basta escrever o nome exatamente como ele aparece na entity tree.
{% hint style="info" %}
**💡 Dica**: você pode renomear entities clicando com o botão direito e selecionando **Rename** na entity tree.
{% endhint %}
```ts
export function main() {
// código do avocado2 de antes
// (...)
const crate = engine.getEntityOrNullByName('Yellow Crate')
if (crate) {
pointerEventsSystem.onPointerDown(
{
entity: crate,
opts: { button: InputAction.IA_POINTER, hoverText: 'Open' },
},
function () {
console.log('CLICKED CRATE')
}
)
}
}
```
Aqui `engine.getEntityOrNullByName()` busca uma referência à entity chamada *Yellow Crate*Yellow Crate `if (crate)` verifica se a entity realmente existe na scene; se não houver nenhuma entity com esse nome, `crate` é `null`. Veja [Itens de referência](https://github.com/decentraland/docs/tree/main/creator/sdk7/code/reference-items.md) para mais informações.
{% hint style="info" %}
**💡 Dica**: todas as entities adicionadas via o Scene Editor já estão carregadas no momento em que `main()` é executado, então é seguro referenciá-las ali ou em funções chamadas indiretamente por `main()`.
{% endhint %}
## Mais tutoriais
Leia [Programando scenes](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md) para uma compreensão geral de como as scenes da Decentraland funcionam.
Para exemplos criados com SDK7, confira a [página de exemplos](https://studios.decentraland.org/resources?sdk_version=SDK7), que contém várias scenes pequenas.
Veja a **guia de desenvolvimento** seção para mais instruções sobre como adicionar conteúdo à sua scene.
## Interaja com outros desenvolvedores
Visite o [Decentraland Discord](https://dcl.gg/discord) e o [Decentraland DAO Discord](https://discord.gg/bxHtcMxUs4) para participar de uma discussão animada sobre o que é possível e como no Decentraland Discord's **Creators** seção.
Para depurar quaisquer problemas, consulte as [Solução de problemas](/creator/content-creator-pt/scenes-sdk7/depuracao/troubleshooting.md) e [debug](/creator/content-creator-pt/scenes-sdk7/depuracao/debug-in-preview.md) seções. Um assistente de IA com as [habilidades de SDK](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/vibe-coding.md) instalado também é um ótimo companheiro de depuração: cole a mensagem de erro do console, ou descreva o que não está se comportando como esperado, e ele geralmente consegue encontrar o problema no seu código. Se você não encontrar uma solução, você pode postar na [categoria SDK Support](https://forum.decentraland.org/c/support-sdk/11) no Decentraland Forum.
## Recursos de arte 3D
Uma boa experiência terá ótimos recursos de arte 3D para acompanhá-la. Se você estiver interessado em criar esses modelos 3D sozinho, veja a [seção de modelagem 3D](/creator/content-creator-pt/modelacao-3d-e-animacoes/3d-models.md). Mas se você preferir se concentrar no lado da programação ou do design de jogos, não precisa criar seus próprios assets! Veja [Recursos úteis](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/useful-resources.md) para bibliotecas de assets e ferramentas de IA que você pode usar para encontrar modelos 3D para sua scene.
## Publique sua scene
Se você possui um NAME da Decentraland, um nome ENS da ETH ou LAND, ou tem permissões concedidas por alguém que possua, você pode enviar sua scene para a Decentraland. Veja [publicação](/creator/content-creator-pt/scenes-sdk7/publicacao/publishing.md).
## Outras informações úteis
* [Vibe Coding com IA](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/vibe-coding.md)
* [Fluxo de trabalho de desenvolvimento](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/dev-workflow.md)
* [Edição de Scenes](/creator/content-creator-pt/scene-editor/primeiros-passos/about-editor.md)
* [Noções essenciais do Scene Editor](/creator/content-creator-pt/scene-editor/primeiros-passos/scene-editor-essentials.md)
* [Restrições de design para jogos](/creator/content-creator-pt/scenes-sdk7/conceber-a-experiencia/design-games.md)
* [modelagem 3D](/creator/content-creator-pt/modelacao-3d-e-animacoes/3d-models.md)
* [Limitações da Scene](/creator/content-creator-pt/scenes-sdk7/otimizacao/scene-limitations.md)
---
# 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/sdk-101.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.