Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Solução de problemas

Esta página lista problemas comuns ao usar o Godot e possíveis soluções.

Ver também

Consulte Utilizando o editor Web para ressalvas específicas da versão Web do editor do Godot.

O editor roda lento e usa todos os recursos do meu CPU e da GPU, fazendo meu computador barulhento

Este é um problema conhecido, especialmente no macOS, já que a maioria dos Macs possui telas Retina. Devido à maior densidade de pixels das telas Retina, tudo precisa ser renderizado em uma resolução mais alta. Isso aumenta a carga na GPU e diminui o desempenho percebido.

Existem várias formas de melhorar o desempenho e a duração da bateria:

  • Em 3D, clique no botão Perspectiva no canto superior esquerdo e habilite Metade da Resolução. Agora o jogo será renderizado na 3D viewport com metade da resolução, deixando em até 4x mais rapido.

  • Abra as Configurações do Editor e aumente o valor de Low Processor Mode Sleep (µsec) para 33000 (30 FPS). Esse valor determina a quantidade de microssegundos entre os frames renderizados. Valores maiores tornam o editor menos responsivo, mas reduzem significativamente o uso de CPU e GPU.

  • Se você possui um nó que faz o editor redesenhar continuamente (como partículas), oculte-o e exiba-o através de um script no método _ready(). Dessa forma, ele ficará oculto no editor, mas continuará visível durante a execução do projeto.

O editor tem stutters e flickes no meu monitor com refresh rate variável (G-Sync/FreeSync)

Este é um problema conhecido. Monitores com taxa de atualização variável precisam ajustar suas curvas de gama continuamente para emitir uma quantidade consistente de luz ao longo do tempo. Isso pode causar a aparição de cintilação em áreas escuras da imagem quando a taxa de atualização varia muito, o que ocorre porque o editor do Godot só redesenha quando necessário.

Existem várias alternativas para isso:

  • Ative Interface > Editor > Update Continuously nas Configurações do Editor. Lembre-se de que isso aumentará o consumo de energia e a emissão de calor/ruído, pois o editor passará a renderizar continuamente mesmo quando nada mudar na tela. Para amenizar isso, você pode aumentar Low Processor Mode Sleep (µsec) para 33000 (30 FPS). Esse valor determina a quantidade de microssegundos entre os frames renderizados. Valores maiores tornam o editor menos responsivo, mas reduzem significativamente o uso de CPU e GPU.

  • Alternativamente, desabilite a taxa de atualização variável no seu monitor ou no driver de gráficos.

  • Flicker VRR pode ser reduzido em alguns displays usando as opções Controle de VRR ou Ajustar Áreas Pretas no OSD do seu monitor. Essas opções podem aumentar o lag de entrada ou resultar em pretos esmagados.

  • Se estiver usando um display OLED, use a predefinição de tema do editor Black (OLED) nas Configurações do Editor. Isso oculta a cintilação do VRR graças aos níveis de preto perfeitos do OLED.

O editor ou projeto leva muito tempo para iniciar

Ao utilizar um dos renderizadores baseados em RenderingDevice (Forward+ ou Mobile), a primeira inicialização tende a ser relativamente demorada. Isso ocorre porque os shaders precisam ser compilados antes de serem armazenados em cache. Eles também precisarão ser recompilados após atualizar o Godot, atualizar os drivers de vídeo ou trocar de placa gráfica.

Esse é um bug conhecido no Windows quando você tem periféricos USB específicos conectados. Em particular, o software iCUE da Corsair parece causar o bug. Tente atualizar os drivers dos seus periféricos USB para a última versão. Se o bug persistir, você precisa desconectar os periféricos com defeito antes de abrir o editor. Após isso, você pode conectá-lo novamente.

Softwares de firewall, como o Portmaster, também podem causar o bloqueio da porta de depuração. Isso faz com que o projeto demore a iniciar e impede o uso de recursos de depuração no editor (como visualizar a saída de print()). Você pode contornar esse problema alterando a porta de depuração utilizada pelo projeto nas Configurações do Editor (Rede > Depuração > Porta Remota). O padrão é 6007; tente outro valor maior que 1024, como 7007.

No Windows, ao carregar o projeto pela primeira vez após ligar o PC, o Windows Defender pode fazer com que a validação do cache do sistema de arquivos durante a inicialização do projeto demore significativamente mais. Isso é especialmente perceptível em projetos com um grande número de arquivos. Considere adicionar a pasta do projeto à lista de exclusões acessando Proteção contra vírus e ameaças > Configurações de proteção contra vírus e ameaças > Adicionar ou remover exclusões.

O editor do Godot parece congelar após clicar no console do sistema

Ao executar o Godot no Windows com o console do sistema aberto, você pode acidentalmente habilitar o modo de seleção clicando dentro da janela de comando. Esse comportamento específico do Windows pausa o aplicativo para que você selecione o texto dentro do console do sistema. O Godot não pode ignorar esse comportamento específico do sistema.

Para resolver isto, selecione a janela do console do sistema e pressione Enter para sair do modo de seleção.

O icon do painel do editor da Godot no mac'os é duplicado toda vez que é movido manualmente

Se você abrir o editor da Godot e mudar a posição manualmente do ícone do painel, quando você reiniciar o editor, você terá um ícone do painel duplicado á direita do painel.

Isto ocorre devido a limitação de designer do painel do macOS. A unica maneira conhecida de resolver isto é alterando colocando o gerenciador de projetos em uma único processo, fazendo que o o gerenciador de projetos não abrisse um processo separado quando inicia-se o editor. Embora o uso de um única instancia processo possa trazer vários benefícios, não há um planejamento para realizar essa tarefa devido a sua complexidade.

Para evitar este problema, mantenha o ícone de dock do editor do Godot na localização padrão criada pelo macOS.

Alguns textos como "NO DC" aparecem no canto superior esquerdo do Gerenciador de Projetos e na janela do editor

Isso é devido ao driver gráfico da NVIDIA injetando um overlay para mostrar informações.

Para desabilitar esse overlay no Windows, restaure suas configurações do driver gráfico para os valores padrões no Painel de Controle NVIDIA.

Para desabilitar esse overlay no Linux, abra nvidia-settings, vá até X Screen 0 > OpenGL Settings e desmarque Enable Graphics API Visual Indicator.

Um ícone de microfone ou "recarregar" aparece no canto superior esquerdo do Gerenciador de Projetos e na janela do editor

Isso é causado pelo driver gráfico da NVIDIA, que injeta uma sobreposição para exibir informações de replay instantâneo na gravação do ShadowPlay. Essa sobreposição só pode ser vista no Windows, já que o Linux não tem suporte para o ShadowPlay.

Para desativar essa sobreposição, pressione Alt + Z (atalho padrão para a sobreposição da NVIDIA) e desative em Settings > HUD Layout > Status Indicator na sobreposição da NVIDIA.

Alternativamente, você pode instalar o novo aplicativo da NVIDIA <https://www.nvidia.com/pt-br/software/nvidia-app/>, que substitui o GeForce Experience e não sofre com esse problema. Diferente do GeForce Experience, o aplicativo da NVIDIA desenha o indicador de replay no canto da tela, em vez de no canto de cada janela.

O editor ou projeto aparece muito pixelado ou embaçado

Aparência correta (esquerda), Aparência sobre-afiada devido ao afiamento dos drivers de gráficos (direita)

Aparência correta (esquerda), Aparência sobre-afiada devido ao afiamento dos drivers de gráficos (direita)

Se o editor ou projeto parecer demasiadamente afiado, provavelmente se deve ao afiamento da imagem ser forçado em todas as aplicações Vulkan ou OpenGL pelo driver da sua placa gráfica. Você pode desabilitar esta função no painel de controle do driver:

  • NVIDIA (Windows): Abra o Menu Iniciar e selecione Painel de Controle NVIDIA. Abra a aba Administrar configuração 3D a esquerda. Na lista do meio, role até Afiamento de Imagem e marque-o para Afiamento Delisgado.

  • AMD (Windows): Abra o Menu Iniciar e selecione AMD Software. Clique no ícone de engrenagem no canto superior direito. Vá ate a aba Gráficos e desabilite Afiamento de Imagem Radeon.

Se o editor ou projeto parecer muito borrado, provavelmente se deve ao FXAA sendo forçado em todas as aplicações Vulkan ou OpenGL pelo driver de vídeo.

  • NVIDIA (Windows): Abra o menu Iniciar e selecione Painel de Controle da NVIDIA. Abra a guia Manage 3D settings, à esquerda. Na lista central, role até Fast Approximate Antialiasing e defina a opção como Application Controlled.

  • NVIDIA (Linux): Abra o menu de aplicativos e escolha NVIDIA X Server Settings. Selecione Antialiasing Settings à esquerda e, em seguida, desmarque Enable FXAA.

  • AMD (Windows): Abra o menu Iniciar e escolha AMD Software. Clique no ícone de engrenagem de configurações no canto superior direito. Vá até a aba Graphics, role até o final e clique em Advanced para expandir as opções. Desative Morphological Antialiasing.

Utilitários de terceiros independentes de fornecedores, como o vkBasalt, também podem forçar o uso de nitidez ou FXAA em todas as aplicações Vulkan. Você pode querer verificar as configurações deles também.

Após alterar as opções no driver gráfico ou em utilitários de terceiros, reinicie o Godot para que as mudanças entrem em vigor.

Se você ainda desejar forçar a nitidez ou o FXAA em outras aplicações, é recomendado fazê-lo individualmente usando o sistema de perfis de aplicativos fornecido pelos painéis de controle dos drivers gráficos.

O editor/projeto trava ou exibe visuais corrompidos após a retomada do PC do modo de suspensão

Este é um problema conhecido no Linux com placas NVIDIA usando o driver proprietário. Ainda não existe uma solução definitiva, pois a combinação Linux + NVIDIA em suspensão frequentemente apresenta falhas quando OpenGL ou Vulkan estão envolvidos. O método de renderização Compatibility (que utiliza OpenGL) geralmente é menos suscetível a problemas relacionados à suspensão do que os renderizadores Forward+ e Mobile (que utilizam Vulkan).

O driver da NVIDIA oferece uma opção experimental para preservar a memória de vídeo após a suspensão, que pode resolver esse problema. Relatos indicam que essa opção funciona melhor com versões mais recentes do driver da NVIDIA.

Para evitar a perda de trabalho, salve as cenas no editor antes de colocar o PC em suspensão.

O projeto funciona quando executado a partir do editor, mas falha ao carregar alguns arquivos ao executar a partir de uma cópia exportada

Isso é geralmente causado ao esquecer de especificar um filtro para arquivos sem recursos no diálogo Exportar. Por padrão, Godot somente incluirá recursos presentes no arquivo PCK. Alguns arquivos comumente usados, como arquivos JSON, não são considerados recursos. Por exemplo, se você carregar test.json no projeto exportado, você precisa especificar *.json no filtro de exportação sem recursos. Veja Opções de recursos para mais informação.

Observe também que arquivos e pastas cujos nomes começam com ponto nunca serão incluídos no projeto exportado. Isso é feito para evitar que diretórios de controle de versão como .git sejam incluídos no arquivo PCK exportado.

No Windows, isso também pode ser devido a problemas de sensibilidade de maiúsculas e minúsculas. Se você fizer referência a um recurso em seu script com maiúsculas e minúsculas diferentes das do sistema de arquivos, o carregamento falhará quando você exportar o projeto. Isso ocorre porque o sistema de arquivos PCK virtual diferencia maiúsculas de minúsculas, enquanto o sistema de arquivos do Windows não diferencia maiúsculas de minúsculas por padrão.

O projeto trava com frequência ou imediatamente após ser aberto pelo gerenciador de projetos

Isso pode ser causado por diversos fatores, como um plugin do editor, um addon feito com GDExtension ou outra coisa. Nesse caso, é recomendado abrir o projeto em modo de recuperação e tentar identificar e corrigir o que está causando os travamentos. Veja a página do Gerenciador de Projetos para mais informações.