> 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/depuracao/troubleshooting.md).

# Solução de Problemas

Correções para problemas comuns

## Depurar com um assistente de IA

Antes de investigar os problemas abaixo, considere pedir ajuda a um assistente de IA, como o chat do Cursor, o GitHub Copilot ou o Claude Code. Cole a mensagem de erro do console ou descreva o que não está a funcionar como esperado, e normalmente ele consegue encontrar o problema no código da sua cena e corrigi-lo por si.

Para obter bons resultados, certifique-se de que as competências do SDK da Decentraland estão instaladas na IA. Essas competências ensinam-lhe os padrões e as limitações do SDK, para que não faça suposições com base em informações genéricas ou desatualizadas. Instale-as executando este comando no projeto da sua cena:

```bash
npx skills add decentraland/sdk-skills
```

Consulte [Programação Vibe com IA](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/vibe-coding.md) para obter mais detalhes sobre como configurar e dar instruções a assistentes de IA.

Também pode deixar a IA depurar a cena *enquanto está em execução*. O cliente de desktop da Decentraland pode disponibilizar um servidor MCP que permite a um agente tirar as suas próprias capturas de ecrã, ler a saída do console da cena, deslocar o jogador pelo cenário e clicar em objetos — assim, em vez de reproduzir o erro e colar a mensagem, o agente reproduz o problema por si, observa o que acontece e faz novas tentativas até o corrigir. Inicie a cena com `npm run start -- --mcp` e ligue o seu agente a esse servidor.

Consulte [Permitir que a IA veja a sua cena no mundo](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/vibe-coding.md#let-the-ai-see-your-scene-in-world) para ver as instruções completas de configuração e instale a competência `unity-explorer-mcp` para que o agente conheça o fluxo de trabalho:

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

## Problemas ao executar a pré-visualização

#### Problema: não é possível executar a pré-visualização de nenhuma cena; a mensagem de erro menciona **Permissões negadas** ou **EACCES**

O seu sistema operativo não lhe permite alterar as permissões da pasta onde pretende executar o projeto. Ao executar a cena, é necessário instalar algumas dependências, mas isso não é permitido. Tem de configurar as permissões da pasta para permitir que a sua conta de utilizador do Windows/Mac/Linux edite os ficheiros nela contidos.

Recursos úteis:

* [docs.npmjs](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)
* [letscodepare](https://letscodepare.com/blog/npm-resolving-eacces-permissions-denied)

#### Problema: não é possível executar a pré-visualização de uma cena específica; a mensagem de erro diz **Erro: erro ao criar o projeto**

Se estiver a executar uma cena que foi partilhada consigo, certifique-se de que ela não foi partilhada com uma pasta `node_modules` ou `bin` ou com um ficheiro `package-lock.json` . Estes ficheiros contêm dependências com versões específicas do seu sistema operativo e da sua máquina; devem ser gerados quando a cena é executada pela primeira vez. Elimine manualmente estas pastas e este ficheiro e, em seguida, execute `npm run start` novamente.

#### Problema: executar `npm run start` não apresenta erros, mas não abre nenhuma janela do browser e não aparece nenhum URL na saída para abrir a pré-visualização

Certifique-se de que a sua versão do Node está atualizada. Tem de ser a versão 20 ou posterior.

#### Problema: executar `npm run start` abre um separador do browser, mas o ecrã de carregamento nunca termina o carregamento, ou aparece uma faixa de erro vermelha com a mensagem "erro crítico".

* Certifique-se de que tem a versão mais recente do SDK da Decentraland instalada no seu projeto. Execute:

  `npm i @dcl/sdk@latest`

#### Problema: a cena é executada e aparece no console o aviso `Cyclic dependencies` .

Estes avisos referem-se a ficheiros da sua cena que fazem referência uns aos outros. Isto não é necessariamente um problema, mas não é uma prática recomendada no desenvolvimento de software, pois pode causar condições de corrida difíceis de depurar e outros problemas. É provável que a sua cena funcione corretamente apesar destes avisos.

Idealmente, o código da sua cena deve ser carregado numa sequência clara. O código com dependências cíclicas pode sofrer do problema do ovo e da galinha, em que o compilador não sabe qual elemento deve inicializar primeiro. Muitas vezes, isto é resolvido sem problemas, mas é uma boa prática evitar essa situação.

Para corrigir estas dependências, muitas vezes é necessário recorrer à chamada de funções ou construtores de objetos, passando referências a entidades/objetos já instanciados nos argumentos da função, em vez de codificar diretamente referências a essas entidades/objetos na função, que podem ou não já estar instanciados.

## Problemas ao fazer o deploy

#### Problema: não tem permissões para fazer o deploy nestas parcelas

* Certifique-se de que o ficheiro `scene.json` da sua Scene lista corretamente as coordenadas para onde pretende fazer o deploy.
* Certifique-se de que o Metamask está corretamente configurado para utilizar a wallet certa para assinar a transação. Esta pode ser a wallet proprietária dos tokens LAND ou uma wallet à qual o proprietário tenha concedido permissões de operador.

#### Problema: a execução de `npm run deploy` falha

* Verifique os pontos de spawn da sua Scene. As três coordenadas x, y e z de um ponto de spawn têm de ser números ou intervalos. Ou são todas números ou são todos intervalos. Não é possível usar intervalos em algumas coordenadas e números noutras.

  Por exemplo, isto não é suportado:

  `"position": {"x": [1,4], "y": 0, "z": [1,4]}`

  Isto é suportado:

  `"position": {"x": [1,4], "y": [0,0], "z": [1,4]}`
* O servidor Catalyst predefinido ao qual foi atribuído o deploy pode estar indisponível ou com problemas. Pode forçar o comando `npm run deploy` a fazer o deploy para um servidor Catalyst específico. Para fazer o deploy para um servidor específico no Decentraland Editor:

  1. Abra a sua Scene e clique em **Publish**
  2. Selecione a opção **Publish to a different server** na parte inferior.
  3. No menu pendente, selecione **Custom Server**
  4. Introduza o endereço do servidor, por exemplo, `peer-ec1.decentraland.org`
  5. Clique em **Publish to custom server**
  6. Aprove a transação como faria num deploy normal.

  Para fazer isto através da CLI:

  `npm run deploy -- --target-content <server-name>`

  Por exemplo:

  `npm run deploy -- --target-content peer-ec1.decentraland.org`

  Consulte [catalyst-monitor](https://decentraland.github.io/catalyst-monitor/) para verificar o estado de todos os servidores da rede Catalyst. Também pode copiar os endereços de cada servidor, na parte superior do respetivo cartão.
* Verifique o ficheiro `package.json`da sua Scene. Um problema comum é haver uma secção `bundleDependencies` e também uma secção `bundledDependencies` (com um d adicional). Isto pode acontecer quando são utilizadas diferentes versões de Node no mesmo projeto em momentos distintos ou quando o projeto é partilhado entre pessoas que o executaram com diferentes versões de Node instaladas. Elimine `bundleDependencies`, que está relacionada com versões mais antigas de Node.

Certifique-se também de que tem uma versão atualizada de Node, no mínimo a versão 20.

#### Problema: a publicação num World falha com um limite de tamanho de 0 bytes

A mensagem completa é «The deployment is too big. The maximum total size allowed is 0 bytes for scenes». Isto significa que os Worlds da sua wallet já estão a utilizar todo o espaço de armazenamento disponível, pelo que não resta espaço para qualquer upload, por mais pequeno que seja. Reduzir o tamanho desta Scene não vai ajudar.

O servidor Worlds contabiliza tudo o que publicou em todos os seus Worlds, menos as Scenes que esta publicação substitui. Para publicar novamente:

* Libertar espaço: anule a publicação de outro World ou de outras Scenes deste World na página [Manage](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/publicar/manage-lands-and-worlds.md#world-storage-budget) do Creator Hub.
* Ou aumente o seu orçamento: obtenha mais NAMEs, LAND ou MANA.

Ultrapassar o orçamento também inicia o período de tolerância de 48 horas para os seus outros Worlds. Consulte [Limites de tamanho dos Worlds](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/tipos-de-projetos/kinds-of-project.md#size-limits).

Isto só se aplica a Worlds com Decentraland NAMEs. Os Worlds em domínios ENS têm um limite fixo por World.

#### Problema: executar `npm run deploy` ou `npm run build` apresenta erros de tipo

A sua scene pode ter erros de tipo comunicados pelo TypeScript, por exemplo, indicando que uma determinada variável pode ser do tipo `any` ou que `undefined` ou `null` não são permitidos. Ao executar `npm run deploy`, também é executado `npm run build`, que é um pouco mais rigoroso nestas verificações do que `npm run start`.

Ao contrário do JavaScript, o TypeScript impõe uma tipagem rigorosa para todas as variáveis. Mesmo que a sua scene esteja escrita de forma a que, por exemplo, um determinado valor nunca seja `undefined`, o TypeScript precisa de saber o que aconteceria nesse cenário, ou tem de especificar explicitamente que o valor só pode ser, por exemplo, uma string.

Em alternativa, pode executar `npm run deploy -- --skip-build` para ignorar a execução de `npm run build`e impedir que estas verificações sejam executadas.

#### Problema: publiquei a minha scene, mas não vejo as alterações quando entro em Decentraland

* Tenha em conta que o processo pode demorar alguns minutos se a scene incluir Assets pesados.
* Enquanto os modelos 3D da nova versão estão a ser convertidos em asset bundles, os jogadores recebem deliberadamente a última versão da sua scene que funciona corretamente. Normalmente, isto demora apenas alguns segundos, mas pode demorar mais em scenes muito grandes ou quando os servidores estão ocupados. Pode [consultar o estado da conversão](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/publicar/publish-scene.md#check-the-conversion-status) da sua scene diretamente.
* Recarregar a scene não basta para obter uma nova versão: o recarregamento reinicia o código da scene, mas não obtém a versão publicada mais recentemente. Quando a conversão estiver concluída, feche completamente e volte a iniciar Decentraland; depois, entre novamente na scene através de um link de salto ou do `/goto` comando de chat.

#### Problema: alguns jogadores veem a nova versão da minha scene, enquanto outros continuam a ver a versão antiga

A conversão dos modelos 3D da sua scene termina em momentos diferentes em cada plataforma (Windows e Mac), e o cliente de cada jogador também mantém uma cache local. Para verificar se a conversão está concluída em todas as plataformas, [consulte o estado da conversão](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/publicar/publish-scene.md#check-the-conversion-status) e compare os valores de `windows` e `mac` em `assetBundles`. Quando ambos estiverem `complete`, peça aos jogadores afetados que fechem completamente e voltem a iniciar Decentraland.

#### Problema: a publicação está bloqueada na etapa de conversão e o botão Jump In não aparece

A sua cena está na fila, atrás de outras cenas que estão a ser convertidas, ou a conversão falhou.

* Abra `https://asset-bundle-registry.decentraland.org/queues/status` e procure o ID da entidade da sua cena. Pode encontrar esse ID no campo `entityId` quando [verificar o estado da conversão](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/publicar/publish-scene.md#check-the-conversion-status) usando as coordenadas da sua cena. Se o seu ID estiver listado na fila, a cena está na fila e basta aguardar.
* Se não estiver na fila, [verifique o estado da conversão](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/publicar/publish-scene.md#check-the-conversion-status) da sua cena. Se uma plataforma apresentar `failed`, publique a cena novamente. Se falhar uma segunda vez, [comunique o problema](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/depuracao/report-bug.md) e inclua o ID da entidade.

#### Problema: após a publicação, alguns modelos 3D estão em falta, pretos ou sem textura

* Se acabou de publicar, a conversão dos seus modelos em asset bundles pode ainda não ter terminado. Escreva `/detectabs` na janela de chat: os modelos com tonalidade vermelha ainda não foram convertidos. [Verifique o estado da conversão](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/publicar/publish-scene.md#check-the-conversion-status) e aguarde até estar concluída.
* Certifique-se de que todos os modelos 3D estão dentro dos limites da cena, incluindo as respetivas caixas delimitadoras. Se alguma parte dos seus modelos ultrapassar estes limites durante uma pré-visualização, essa parte será cortada e não será renderizada, tanto na pré-visualização como na cena publicada.
* Se o problema estiver nas texturas, tenha em conta que, durante a conversão, as texturas dos modelos 3D estão limitadas a um tamanho máximo de 1024x1024 píxeis.

#### Problema: a cena parece estar bem de perto, mas está danificada ou em falta quando vista à distância

As versões de baixo nível de detalhe (LOD) dos seus recursos, usadas para renderizar a cena à distância, são geradas na última etapa da publicação e podem ainda não estar prontas. Isto não impede que teste a sua cena de perto. [Verifique o estado da conversão](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/publicar/publish-scene.md#check-the-conversion-status) e consulte os valores em `lods`, ou aguarde e volte a verificar mais tarde.

#### Problema: após a publicação, os meus modelos 3D têm um aspeto diferente

* Se as texturas tiverem um aspeto diferente, tenha em conta que as texturas dos modelos 3D estão limitadas a um tamanho máximo de 1024x1024 píxeis. Esta conversão é realizada para garantir que o Decentraland funciona sem problemas para todos.
* Se os modelos tiverem um aspeto diferente, poderá haver um problema na conversão dos modelos em asset bundles. Saiba mais sobre a compressão de asset bundles [aqui](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/otimizacao/performance-optimization.md#asset-bundle-conversion).

  Para validar isto, experimente executar a cena com o parâmetro de URL `&DISABLE_ASSET_BUNDLES`. Se os modelos tiverem um aspeto normal com esta flag, o problema deverá estar relacionado com um erro na conversão do modelo. Nesse caso, [comunique o problema](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/depuracao/report-bug.md) e inclua o ID da entidade da sua publicação.

  Tenha em conta que os servidores demoram algum tempo a gerar versões comprimidas dos modelos em asset bundles (normalmente alguns minutos, ou mais no caso de cenas muito grandes ou quando os servidores estão ocupados). Pode verificar se os modelos estão a ser carregados como asset bundles comprimidos escrevendo o seguinte comando na janela de chat `/detectabs`. Os modelos comprimidos aparecem com tonalidade verde; os não comprimidos, com tonalidade vermelha.

  O Explorer para computador realiza a mesma conversão localmente quando [pré-visualiza a sua cena](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/preview-scene.md#preview-with-optimized-assets), para que possa detetar estes problemas sem publicar. Para comparar, volte a pré-visualizar com a opção **Load Raw GLTFs** ativada: se os modelos tiverem um aspeto normal dessa forma, o problema está na conversão.

#### Problema: a minha cena desapareceu por completo

* Se a cena estiver num World: o limite de armazenamento do seu World poderá ter sido excedido, por exemplo, depois de vender ou transferir NAMEs, LAND ou MANA. Tem 48 horas para libertar espaço ou aumentar o seu limite antes de os seus Worlds ficarem inacessíveis. Consulte o seu limite em **Gerir** separador do Creator Hub ou no separador **Worlds** separador do [Builder](https://decentraland.org/builder/worlds), e volte a publicar. Consulte [Limites de tamanho de Worlds](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/tipos-de-projetos/kinds-of-project.md#size-limits).
* Se a cena estiver em LAND: alguém com permissões de publicação pode ter publicado uma nova cena nos seus parcels, apagando o conteúdo anterior. Consulte [substituição de cenas](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/publicacao/publishing.md#scene-overwriting).
* Em casos raros, o conteúdo que viola a política de conteúdo da Decentraland pode ser colocado numa lista de bloqueio nos servidores de conteúdo. Se acredita que isso aconteceu por engano, entre em contacto através do [Discord da Decentraland](https://decentraland.org/discord).

#### Problema: a minha cena tem um FPS baixo em produção, apesar de funcionar sem problemas na pré-visualização.

O desempenho da sua cena pode ser afetado pelas cenas vizinhas que seguem práticas inadequadas, uma vez que também são executadas em paralelo. Pode confirmar se é esse o caso abrindo as definições e definindo a distância de visão para o mínimo, para que seja carregado apenas 1 parcel à volta da cena atual.

Pode reduzir ainda mais a distância de visão executando a sua cena com o parâmetro `&LOS=0`, para não carregar quaisquer cenas circundantes.

Se acabou de publicar a sua cena, a carga durante o carregamento também poderá diminuir assim que os servidores converterem os modelos 3D da cena em pacotes de assets comprimidos. Pode verificar se os modelos estão a ser carregados como pacotes de assets comprimidos escrevendo o seguinte comando na janela de chat `/detectabs`. Os modelos comprimidos aparecem a verde e os não comprimidos a vermelho.

### Comunicar um erro

Se encontrar um problema que não esteja relacionado com a sua cena, mas sim com o Decentraland SDK em geral, consulte [Comunicar um erro](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/depuracao/report-bug.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/depuracao/troubleshooting.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.
