> 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/vibe-coding.md).

# Vibe Coding com IA

Crie scenes do Decentraland com assistentes de IA usando o Creator Hub e o SDK Skills oficial do Decentraland (npx skills add decentraland/sdk-skills).

Crie cenas de Decentraland descrevendo o que pretende. Um assistente de IA trata do código SDK7, da arquitetura ECS e da estrutura do projeto por si.

Quer esteja a criar pela primeira vez ou seja um programador experiente, a «programação por vibe» assistida por IA permite passar de uma ideia a uma cena funcional em minutos, em vez de horas.

{% hint style="info" %}
**💡 Dica**: Não precisa de conhecer TypeScript para começar. Os assistentes de IA conseguem gerar código funcional para cenas a partir de descrições em linguagem corrente.
{% endhint %}

## O que é a programação por vibe?

A programação por vibe consiste em criar cenas através de uma conversa com um assistente de IA, em vez de escrever manualmente cada linha de código. Descreve o que pretende — «uma taberna medieval com portas em que se pode clicar e música de fundo» — e a IA escreve código SDK7 correto e pronto a implementar.

Esta abordagem é adequada a qualquer nível de experiência:

* **Iniciantes e pessoas sem experiência em programação** — Passe do zero a uma cena funcional sem escrever código manualmente.
* **Programadores experientes** — Evite o código repetitivo. Deixe a IA tratar da sincronização multijogador, da estrutura inicial da UI e da configuração de implementação, enquanto se concentra nas decisões criativas.
* **Equipas e estúdios** — Crie protótipos de conceitos de cenas rapidamente, antes de dedicar recursos de desenvolvimento a tempo inteiro.

## Utilize o AI Assistant no Creator Hub

A forma mais rápida de começar é utilizar o [AI Assistant](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/expandir-com-codigo/ai-assistant.md), integrado no Creator Hub. Este consegue ver a cena aberta, editar Entities, Components, Smart items e código por si, e executar a pré-visualização para verificar o próprio trabalho. Instala automaticamente no seu projeto as Skills abaixo, pelo que não precisa de configurar mais nada além de iniciar sessão numa CLI de programação.

É uma funcionalidade experimental, desativada por predefinição.

## Combine um editor de código com IA

Utilize um editor de código com IA de uso geral, como o [Cursor](https://www.cursor.com/) ou o VS Code com o GitHub Copilot ou o Claude AI. A Decentraland fornece uma pasta de contexto para que estas ferramentas compreendam o SDK.

1. Abra o Creator Hub e crie uma cena ou abra uma já existente.
2. Clique no botão **< > CODE** para abrir o editor de código.
3. Utilize o assistente de IA integrado no editor (o chat do Cursor, o Copilot, etc.) para gerar ou modificar código.

## Instalar Skills para qualquer agente de IA

As Skills são conjuntos de instruções prontos a utilizar que ensinam o seu agente de IA a trabalhar com o SDK da Decentraland. Cada Skill aborda um tema específico, como criar cenas, adicionar modelos 3D ou configurar o modo multijogador, para que a IA já conheça os padrões, as APIs e as limitações adequados, sem ter de os explicar. A instalação de Skills reduz os erros e melhora os resultados desde o primeiro pedido.

```bash
# Escolha as Skills da Decentraland que pretende instalar através de um seletor interativo
npx skills add decentraland/sdk-skills

# Ou instale todas as Skills da Decentraland
npx skills add decentraland/sdk-skills --all

# Ou escolha Skills específicas
npx skills add decentraland/sdk-skills --skill create-scene

# Instalar globalmente (disponível em todos os projetos)
npx skills add decentraland/sdk-skills -g
```

Este comando copia os ficheiros das Skills para a configuração do seu agente, para que este conheça os padrões e as limitações da Decentraland.

## Atualizar Skills

São adicionadas novas Skills ao longo do tempo e as existentes são melhoradas. Para obter as versões mais recentes, execute novamente o comando de instalação com `--all`:

```bash
# Atualizar todas as Skills instaladas e transferir as novas
npx skills add decentraland/sdk-skills --all
```

Executar `add` novamente volta a obter o repositório, atualizando as Skills que já tem e instalando as que foram adicionadas desde a primeira instalação. Se instalou Skills globalmente, inclua também `-g` neste comando.

{% hint style="warning" %}
**📔 Nota**: Não utilize `npx skills update` para isso. Apenas atualiza as skills que já estão na sua máquina, por isso quaisquer skills adicionadas ao repositório desde a última instalação são ignoradas sem aviso. Use sempre `npx skills add decentraland/sdk-skills --all` em vez disso.
{% endhint %}

## Depurar uma cena multijogador implementada

A versão atualizada da skill `authoritative-server` pode pesquisar registos persistentes do servidor, acompanhar os registos durante um período limitado e obter métricas de CPU, memória e outras quando lhe pedir para investigar uma cena implementada. Atualize as suas skills e o `auth-server` SDK da cena primeiro; consulte [Scene Insights](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/depuracao/scene-insights.md) para obter informações sobre configuração, permissões e limites.

Por exemplo, peça:

> Investigue erros e o aumento da utilização de CPU ou memória na minha cena multijogador implementada durante as últimas duas horas. Use o Scene Insights e correlacione os registos e as métricas com o código-fonte.

Aprova pessoalmente o início de sessão da carteira no navegador. Em seguida, o assistente pode reutilizar a sessão só de leitura; não precisa da sua chave privada nem do ficheiro de sessão.

## Skills de IA disponíveis

Quando instala skills no seu agente, ficam disponíveis as seguintes funcionalidades:

| Skill                  | O que faz                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `sdk-scenes`           | Ponto de entrada com diretrizes para agentes e índice de todas as skills por tópico   |
| `create-scene`         | Criar a estrutura de um novo projeto de cena SDK7 do zero                             |
| `migrate-sdk6-to-sdk7` | Migrar uma cena antiga de SDK6 para SDK7                                              |
| `add-3d-models`        | Adicionar modelos 3D (`.glb`/`.gltf`) com posicionamento, dimensionamento e colliders |
| `add-interactivity`    | Eventos de ponteiro, triggers e raycasts                                              |
| `build-ui`             | UI 2D no espaço do ecrã com React-ECS — HUDs, menus e caixas de diálogo               |
| `animations-tweens`    | Animações de modelos GLTF com Animator e tweens do SDK                                |
| `multiplayer-sync`     | Multijogador ponto a ponto com rede CRDT                                              |
| `authoritative-server` | Servidor multijogador sem interface para cenas validadas pelo servidor (BETA)         |
| `audio-video`          | Efeitos sonoros, música, transmissão de áudio e leitores de vídeo                     |
| `audio-analysis`       | Dados de amplitude e frequência em tempo real para cenas reativas ao áudio            |
| `deploy-scene`         | Implementar cenas na Genesis City (baseada em LAND)                                   |
| `deploy-worlds`        | Implementar cenas em Worlds (espaços 3D pessoais)                                     |
| `optimize-scene`       | Otimização do desempenho, limites das cenas e práticas recomendadas                   |
| `camera-control`       | Deteção do modo de câmara, câmara cinematográfica, câmaras virtuais                   |
| `composites`           | Referência ao formato de ficheiro Composite para conteúdo estático de cenas           |
| `lighting-environment` | Iluminação dinâmica, sombras, skybox, nevoeiro, definições do ambiente                |
| `particle-system`      | Efeitos de partículas — fogo, fumo, faíscas, neve, fogo de artifício                  |
| `npcs`                 | Personagens não jogáveis — biblioteca NPC Toolkit e abordagens manuais                |
| `player-avatar`        | Posição do jogador, perfil, personalização do Avatar, acessórios                      |
| `player-physics`       | Forças físicas — impulsos, repulsão, forças contínuas                                 |
| `nft-blockchain`       | Exibição de NFT e interações com blockchain/criptoativos                              |
| `advanced-rendering`   | Billboard, TextShape, materiais PBR, materiais de vídeo                               |
| `advanced-input`       | Leitura de entradas ao nível do sistema e controlo do movimento do jogador            |
| `scene-runtime`        | APIs de runtime transversais — operações assíncronas, HTTP, mensagens                 |
| `script-components`    | Classes de componentes de script para o Creator Hub                                   |
| `game-design`          | Padrões de design de jogos, limites das cenas, orçamentos de desempenho               |
| `unity-explorer-mcp`   | Controlar um Explorer em execução para testar e verificar uma cena dentro do mundo    |

Nota: Algumas destas competências envolvem obter modelos 3D ou outros recursos de catálogos de recursos gratuitos. O agente de IA deve sempre pedir confirmação ao utilizador antes de transferir novos recursos para um projeto de cena.

## Permita que a IA veja a sua cena dentro do mundo

Normalmente, a IA escreve código e *você* executa a pré-visualização, observa-a e comunica o que está errado. O cliente de desktop Decentraland pode fechar esse ciclo: inclui um **servidor MCP** opcional que permite a um agente de IA observar e controlar diretamente o Explorer em execução. O agente tira as suas próprias capturas de ecrã, lê a saída da consola da cena, movimenta o jogador, clica em objetos e verifica se a cena faz realmente aquilo que lhe foi pedido — depois corrige os problemas que encontra e volta a observar.

Isto transforma a programação por vibe de «descrever, esperar, rever» num ciclo que o agente consegue executar quase sozinho.

{% hint style="info" %}
**💡 Sugestão**: Instale a competência `unity-explorer-mcp` antes de experimentar. Esta competência ensina ao agente todo o fluxo de trabalho — como iniciar o cliente, como enquadrar capturas de ecrã úteis, como comparar o que vê com o estado real da cena e como recuperar quando a cena deixa de carregar.

```bash
npx skills add decentraland/sdk-skills --skill unity-explorer-mcp
```

{% endhint %}

### O que é necessário

* O **cliente de desktop Decentraland** instalado (o mesmo que o Creator Hub inicia para as pré-visualizações).
* Um agente de IA que consiga ligar-se a servidores MCP por HTTP — Claude Code, Cursor, Cline, VS Code com uma extensão compatível com MCP, entre outros.
* Uma versão atualizada do SDK na sua cena: execute `npm i @dcl/sdk@latest` se a `--mcp` opção abaixo for rejeitada como desconhecida.

### 1. Inicie a cena com o servidor MCP ativado

Na pasta da cena:

```bash
npm run start -- --mcp
```

Este comando faz o que `npm run start` faz sempre — disponibiliza a sua cena em `http://127.0.0.1:8000` e recarrega-a automaticamente sempre que guarda um ficheiro — e, além disso, inicia o cliente de desktop com o servidor MCP à escuta em `http://127.0.0.1:8123/unity-explorer-mcp`.

Inicie sessão quando o cliente abrir. O agente só pode começar a trabalhar depois de ultrapassar o ecrã de início de sessão e de o mundo carregar.

### 2. Ligue o seu agente de IA ao servidor

No **Claude Code**, registe-o uma vez:

```bash
claude mcp add --transport http --scope user explorer http://127.0.0.1:8123/unity-explorer-mcp
```

Em **qualquer outro cliente MCP**, adicione o servidor conforme indicado na documentação desse cliente, usando estes dados:

| Definição    | Valor                                                                                                               |
| ------------ | ------------------------------------------------------------------------------------------------------------------- |
| Transporte   | Streamable HTTP (não stdio — não há nenhum comando para executar; o servidor está integrado no cliente em execução) |
| URL          | `http://127.0.0.1:8123/unity-explorer-mcp`                                                                          |
| Autenticação | Nenhuma                                                                                                             |
| Nome         | `explorer`                                                                                                          |

Muitos clientes usam um ficheiro de configuração JSON para este efeito (`.cursor/mcp.json`, `mcp.json`, entre outros — consulte a documentação do seu cliente para saber os nomes exatos das chaves):

```json
{
  "mcpServers": {
    "explorer": {
      "type": "http",
      "url": "http://127.0.0.1:8123/unity-explorer-mcp"
    }
  }
}
```

Reinicie ou recarregue o seu cliente de IA depois de registar o servidor, para que estabeleça a ligação. Se o agente indicar que as ferramentas do Explorer não estão disponíveis, a causa mais comum é o cliente não estar em execução quando o agente foi iniciado — volte a ligar o servidor (no Claude Code, execute `/mcp`) com o Explorer aberto.

{% hint style="info" %}
**É seguro?** O servidor só é executado quando inicia o cliente com `--mcp`, só aceita ligações do seu próprio computador (`127.0.0.1`) e rejeita pedidos provenientes de páginas Web. Nada fica exposto à Internet e o servidor fica completamente desativado quando inicia o cliente normalmente.
{% endhint %}

### 3. Peça o que pretende e deixe o agente verificar

Com o servidor ligado, peça o que pretende da forma habitual — a diferença é que agora o agente pode verificar os próprios resultados:

> "Adicione um baú de tesouro no centro do parcel que se abra ao clicar nele e, em seguida, caminhe até lá e clique para confirmar que a tampa é animada."

> "O letreiro de néon está demasiado escuro. Faça uma captura de ecrã, ajuste a intensidade emissiva e mostre-me o antes e o depois."

> "Há algo de errado com o elevador. Suba para a plataforma, observe os registos e diga-me porque não se move."

Nos bastidores, o agente pode:

* **Ver** — tirar capturas de ecrã, ler o resultado de `console.log` e os erros, verificar se a cena foi carregada ou falhou, listar as entidades da cena e inspecionar os respetivos Components, e ler a posição do jogador e da câmara.
* **Controlar** — mover e teletransportar o jogador, caminhar numa direção com colisões reais, apontar a câmara, colocar uma câmara livre para uma captura específica, alternar os modos de câmara, clicar nos objetos da cena, enviar mensagens de chat e `/commands`, ativar Emotes e recarregar a cena.
* **Medir** — ler em tempo real as contagens do conteúdo da cena (triângulos, entidades, texturas, materiais e muito mais) e compará-las com os limites da Decentraland, classificar os modelos 3D que mais contribuem para essa carga a partir de qualquer ponto de vista e medir a taxa de fotogramas real que o jogador sente em qualquer local.

### Utilize-a para otimizar a sua cena

Como o agente consegue medir e também ver, pode delegar-lhe diretamente tarefas de desempenho. Pode verificar a sua cena face aos [limites da cena](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/otimizacao/scene-limitations.md), identificar os modelos 3D mais pesados, medir a taxa de fotogramas em locais específicos e, acima de tudo, voltar a medir depois de fazer alterações para comprovar que foram úteis:

> "Verifica se a minha cena está dentro dos limites de conteúdo da Decentraland e diz-me qual é o orçamento que está mais perto do limite."

> "A cena parece aos solavancos perto da fonte. Vai até lá, mede a taxa de fotogramas e diz-me quais são os modelos que mais pesam nesse local."

> "Otimiza a cena: descobre o que está a reduzir a taxa de fotogramas, corrige-o e mostra-me as medições antes e depois."

Para obter os melhores resultados, instala a `optimize-scene` skill juntamente com `unity-explorer-mcp`, para que o agente também conheça as melhores práticas de otimização da Decentraland. Consulta [Otimização do desempenho](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/otimizacao/performance-optimization.md#optimize-with-ai) para saber mais sobre este fluxo de trabalho, incluindo como o combinar com o servidor MCP do Blender para automatizar correções nos próprios modelos 3D.

### Sugestões

* **Peça provas, não afirmações.** É pedir "Confirma com uma captura de ecrã" ou "confirma através dos registos" que torna este fluxo de trabalho vantajoso. Um bom agente verifica ambos: os píxeis podem parecer corretos enquanto o estado subjacente está avariado, e vice-versa.
* **As capturas de ecrã consomem tokens.** Cada captura de ecrã que o agente analisa consome parte do seu contexto. Se quiser uma inspeção visual prolongada — uma animação ao longo do tempo, um percurso por vários locais — peça-lhe para guardar fotogramas em ficheiros e ler apenas os que forem relevantes. A skill `unity-explorer-mcp` inclui um script que faz exatamente isso.
* **Guarde uma vez, não cinco vezes seguidas.** Guardar várias vezes seguidas num curto espaço de tempo pode fazer com que o cliente carregue um pacote escrito apenas parcialmente e perca completamente a cena, sendo necessário reiniciar o cliente para recuperar. Peça ao agente para agrupar as alterações e guardá-las de uma só vez.
* **Mantenha o cliente aberto.** Se o fechar, a ligação é interrompida e o agente deixa de conseguir ver. Ao reiniciá-lo com o mesmo comando, a ligação é restabelecida.
* **Os teletransportes funcionam de forma diferente durante o desenvolvimento local de cenas.** A deslocação entre parcels com `/goto` não é permitida nesse contexto, por isso o agente deve reposicionar o jogador dentro da cena em vez de o teletransportar.

## Sugestões para criar prompts eficazes

Para obter os melhores resultados da IA, dê instruções claras e específicas. Eis algumas sugestões:

### Seja específico quanto ao que pretende

Em vez de:

> "Melhora a minha cena"

Experimente:

> "Adiciona uma porta na posição (8, 0, 8) que se abre com uma animação de rotação quando se clica nela e reproduz um efeito sonoro de rangido"

### Faça referência a elementos existentes

> "Faz com que o botão vermelho em cima da mesa ative a subida do elevador"

### Peça uma coisa de cada vez

Divida os pedidos complexos em etapas:

1. "Adiciona uma UI de pontuação no canto superior direito"
2. "Adicione um contador que aumenta quando o jogador clica no alvo"
3. "Apresente o valor do contador no marcador"

### Itere e refine

Após cada alteração:

1. Pré-visualize a cena (clique em **Play** no Creator Hub ou execute `npm run start` na linha de comandos)
2. Verifique o que funciona e o que não funciona
3. Diga à IA o que deve ajustar: "Desloque o NPC 2 metros para a esquerda e vire-o para o jogador"

### Exemplos de prompts

Para executar numa cópia nova de [sdk7-scene-template](https://github.com/decentraland/sdk7-scene-template/).

#### Exemplo de prompt 1

```
Quero que elimine o código atual da cena e crie um jogo de labirinto pequeno e simples, num único parcel. As paredes podem ser cubos e devem ter colisão.

O jogo deve começar quando o jogador entrar efetivamente no labirinto pelo ponto A e terminar quando sair pelo ponto B (a única saída do labirinto).

Quero que adicione 3 portas diferentes no labirinto, com as quais seja possível interagir usando o apontador para as abrir e passar por elas.

Deve verificar se o jogador consegue realmente jogar e vencer
```

#### Exemplo de prompt 2

```
Quero que elimine o código atual da cena e crie um jogo de plataformas simples.

Tem de verificar se é possível vencer o jogo antes de o considerar concluído.
```

## Em que a IA pode ajudar

* Criar a estrutura de novas cenas a partir de uma descrição
* Adicionar e posicionar modelos 3D
* Escrever funções de clique e criar interatividade
* Criar UI (HUDs, menus, caixas de diálogo)
* Configurar a sincronização multijogador
* Configurar o Multiplayer Server para impedir batotas
* Adicionar áudio, vídeo e streaming
* Criar animações e tweens
* Otimizar o desempenho da cena
* Preparar cenas para implementação
* Depurar problemas no código existente
* Testar e verificar visualmente uma cena num Explorer em execução (consulte [Permita que a IA veja a sua cena no mundo virtual](#let-the-ai-see-your-scene-in-world))

## Limitações

Embora as ferramentas de IA sejam poderosas, tenha em conta o seguinte:

* **Pré-visualize sempre** — O código gerado por IA pode não ter exatamente o aspeto esperado. Execute uma pré-visualização para verificar.
* **Os limites das cenas continuam a aplicar-se** — A IA não pode contornar as [limitações das cenas](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/otimizacao/scene-limitations.md) do Decentraland (contagem de triângulos, tamanhos de ficheiro, limites dos parcels).
* **Lógica de jogo complexa** — Para mecânicas de jogo complexas, poderá ter de orientar a IA passo a passo ou aperfeiçoar manualmente o resultado.
* **Modelos 3D personalizados** — A IA pode recorrer a recursos gratuitos existentes ou carregar modelos fornecidos por si, mas não consegue criar modelos 3D de raiz (a menos que utilize também outras ferramentas, como o servidor MCP oficial do Blender).

## Próximos passos

* [Início rápido do SDK](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/sdk-101.md) — Aprenda os fundamentos do SDK7
* [Combine com código](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/expandir-com-codigo/overview.md) — Combine a edição visual com código
* [Servidor multijogador](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/rede/authoritative-servers.md) — Multijogador com autoridade do servidor
* [Exemplos de cenas](https://docs.decentraland.org/creator/content-creator-pt/tutoriais-e-exemplos/examples.md) — Explore mecânicas de cenas reutilizáveis e repositórios
* [Recursos úteis](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/useful-resources.md) — Mais ferramentas de IA, bibliotecas de recursos e complementos para acelerar o seu fluxo de trabalho


---

# 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/vibe-coding.md?ask=<question>&goal=<user_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.
