> 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 scene, combinando as diferentes ferramentas que você tem à disposição: o Scene Editor visual do Creator Hub, código escrito à mão usando o Decentraland SDK e assistido por IA **vibe coding**. Você usará as três juntas e aprenderá em que cada uma se destaca.
## Como eu crio uma scene do Decentraland?
1. **Instale o** [**Creator Hub**](https://decentraland.org/download/creator-hub), o aplicativo de desktop oficial para criar, visualizar e publicar scenes. É a ferramenta recomendada para criadores de todos os níveis de habilidade.
2. **Se você usar um assistente de codificação por 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 padrões verificados de 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 criar, visualizar e fazer deploy de 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 boas opções, mas qualquer editor de código funciona.
Leia [Guia de instalação](/creator/content-creator-pt/scene-editor/comece/editor-installation.md) para mais detalhes.
## Crie sua primeira scene
1. Abra o Creator Hub.
2. Selecione a **Scenes** aba e clique em **Nova Scene**.
3. Escolha um template inicial. Para este exercício, escolha o **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 pacotes de assets
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 básicas do Scene Editor](/creator/content-creator-pt/scene-editor/comece/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 deles para sua scene, ele cobrirá todo o chão da sua scene com cópias deste item.
{% endhint %}
## Execute uma pré-visualização
Clique no **Preview** 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* no formato do seguinte [link](https://github.com/decentraland-scenes/avocado/raw/main/avocado-glb.zip) e descompacte-o.
Arraste o **avocado.glb** arquivo 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 **Scene** pasta. 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" %}
**📔 Nota**: 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 pela estrutura de arquivos e pastas do seu projeto. Abra o `index.ts` arquivo dentro da `src` pasta. 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 nova Entity
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** component.
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 [Ciclo de vida da scene](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#scene-lifecycle) para mais detalhes.
Execute o preview 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" %}
**📔 Nota**: O segundo abacate existe **apenas no seu código**. Ele aparece quando você executa a scene, mas o canvas do Scene Editor e a entity tree não conseguem exibir entities criadas em `index.ts`. Não se assuste se você não o vir no editor. Este é um ponto-chave a ter em mente quando você combina 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 no 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 no `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. Ela 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 somente de código não fica visível aqui).
2. Clique no **+** botão na parte superior do painel de propriedades e selecione **Script** para adicionar um componente Script.
3. Clique em **+ Create New Script** e dê a ele o nome `AvocadoScript`.
4. Clique no **<> Code** botão no component Script para abrir o novo arquivo no seu editor de código.
O script é uma classe com três partes principais (comentários omitidos 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 suas entradas personalizadas abaixo
) {}
start() {
// Chamado uma vez, quando a scene carrega
}
update(dt: number) {
// Chamado em cada frame
}
}
```
* O **constructor** define parâmetros que aparecem como campos editáveis no componente Script no Creator Hub. Não remova `src` ou `entity`.
* **`start()`** é executado **uma vez**, quando a scene carrega. Use-o para a configuração: criar components, registrar tratadores de click etc.
* **`update(dt)`** é executado a cada **frame** do jogo, aproximadamente 30 vezes por segundo. Use-o para comportamento contínuo, como movimento. `dt` indica quantos segundos se passaram desde o último frame.
Dentro da class, `this.entity` sempre se refere à entity que contém o Script component: neste caso, seu abacate. É isso que torna os scripts reutilizáveis: anexe o mesmo script a dez itens, e cada um age sobre si mesmo.
### Vibe code 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 a um assistente de IA e deixar que ele escreva o código. A maioria dos editores de código tem um embutido, 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 as 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
```
Essas skills são documentos de referência que a IA consulta sempre que não tem certeza de como fazer algo com o SDK, para escrever 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 prompting.
Agora tente um prompt como este:
> Em AvocadoScript.ts, faça o abacate registrar uma mensagem no console quando o player clicar nele.
Você deve acabar com algo assim (ou colar 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 um comportamento de click dentro da `start()` função. Só precisamos definir o comportamento de click uma vez, e ele reagirá cada vez que o player clicar no item. A `pointerEventsSystem.onPointerDown()` instrução define três coisas:
* Sobre o que `entity` os eventos de click funcionam: aqui `this.entity`, o abacate que contém o script.
* Um `opts` objeto: 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 o preview 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" %}
**📔 Nota**: Para uma entity ser clicável, ela deve 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 soluções alternativas para modelos que não têm.
{% endhint %}
### Faça o abacate desaparecer
Vamos fazer o click fazer algo mais empolgante agora! Peça ao seu assistente de IA:
> Quando o abacate for clicado, faça-o desaparecer. 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 analisar o que a IA fez.
* Para fazer a animação elástica, ele 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()` reduz o abacate do tamanho completo (`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 click, ele criou um `método collect()` Isso não é obrigatório (se sua IA colocou o tween dentro da função de click, isso 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 diferentes lugares.
* Para mostrar a dica "Collect" no abacate, ele definiu isso como o `hoverText` valor.
Execute o preview e clique no abacate: ele deve desaparecer com estilo.
{% hint style="warning" %}
**📔 Nota**: O abacate encolhe até o tamanho 0, mas a entity ainda existe. O ideal é excluir a entity depois que o tween terminar, para deixar 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 %}
### Executar 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` torna o movimento suave e independente da taxa de frames: o abacate gira a 45 graus por segundo, não importa quão rápido a máquina do player seja.
Como `speed` é um parâmetro do constructor, ele também aparece como um campo no componente Script no Creator Hub. Clique no ícone de atualizar no canto superior direito do componente Script para vê-lo e então ajuste o valor sem tocar em nenhum código.
Cada entity armazena seu próprio valor para o **Speed** campo, 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 velocidade diferente em cada um. Cada abacate agora gira em sua própria velocidade.
Scripts podem fazer muito mais, como expor actions que outros smart items podem acionar. Veja [Script component](/creator/content-creator-pt/scene-editor/estender-com-codigo/script-component.md) para ver o panorama completo.
## Referencie um item do Scene Editor
O Script component é a maneira mais fácil de dar comportamento a um único item, mas há 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/comece/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() {
// avocado2 code from before
// (...)
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*. A `if (crate)` verificação garante que a entity realmente existe na scene; se não houver nenhuma entity com esse nome, `crate` é `null`. Veja [Reference Items](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 Scene Editor já estão carregadas quando `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 do Decentraland funcionam.
Para exemplos feitos com SDK7, confira a [página de Examples](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 numa discussão animada sobre o que é possível e como no Decentraland Discord **Criadores** secção.
Para depurar quaisquer problemas, verifique os [Resolução de problemas](/creator/content-creator-pt/scenes-sdk7/debugging/troubleshooting.md) e [debug](/creator/content-creator-pt/scenes-sdk7/debugging/debug-in-preview.md) secções. Um assistente de IA com as [competências em SDK](/creator/content-creator-pt/scenes-sdk7/primeiros-passos/vibe-coding.md) instaladas é também um ótimo companheiro de debug: cole a mensagem de erro da console, ou descreva o que não está a comportar-se como esperado, e normalmente consegue encontrar o problema no seu código. Se não encontrar uma solução, pode publicar na [categoria SDK Support](https://forum.decentraland.org/c/support-sdk/11) no Decentraland Forum.
## Recursos de arte 3D
Uma boa experiência terá excelentes arte 3D para a acompanhar. Se estiver com vontade de criar esses modelos 3D você mesmo, veja a [secção de modelação 3D](/creator/content-creator-pt/modelagem-3d-e-animacoes/3d-models.md). Mas se preferir focar-se no lado da programação ou do design de jogos, não precisa de criar os 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 pode usar para encontrar modelos 3D para a sua scene.
## Publique a sua scene
Se for proprietário de um Decentraland NAME, de um nome ETH ENS ou de LAND, ou tiver permissões concedidas por alguém que as tenha, pode carregar a sua scene para 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)
* [Editing Scenes](/creator/content-creator-pt/scene-editor/comece/about-editor.md)
* [Noções básicas do Scene Editor](/creator/content-creator-pt/scene-editor/comece/scene-editor-essentials.md)
* [Restrições de design para jogos](/creator/content-creator-pt/scenes-sdk7/desenhando-a-experiencia/design-games.md)
* [modelação 3D](/creator/content-creator-pt/modelagem-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 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/sdk-101.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.