Como Atualizar a Versão do Godot com Segurança — Um Checklist Baseado em Risco

Introdução

Atualizar a engine do jogo no meio de um projeto é uma das decisões rotineiras mais assustadoras do desenvolvimento de jogos. Uma nova versão do Godot pode corrigir o bug que está travando você — ou pode quebrar silenciosamente uma cena na qual você investiu seis meses de trabalho. É por isso que desenvolvedores experientes da comunidade Godot tratam a atualização de versão como uma decisão de risco, e não como uma tarefa rotineira.

Este guia não é uma defesa do "atualize sempre". É um checklist de gerenciamento de risco para migrações de 4.x para 4.x no Godot: como decidir se vale a pena atualizar, como se preparar para poder recuar com segurança, o que se sabe que quebra entre versões e — o mais importante — como verificar de fato que nada quebrou.

Você Deveria Mesmo Atualizar?

Antes de mexer em qualquer coisa, responda a esta pergunta com honestidade. Atualizar tem um custo real (trabalho de migração + novos testes), então o benefício precisa ser igualmente real.

Atualize se…

Um bug já corrigido na engine está travando você. Se o seu problema já foi resolvido em uma versão mais recente, atualizar costuma sair mais barato do que conviver com a gambiarra para sempre.
Um novo recurso beneficia seu jogo de forma concreta. Não é "parece legal" — é algo que economiza tempo real de desenvolvimento ou viabiliza um design de que você precisa.
Seu cronograma de desenvolvimento é longo. Se o projeto vai levar anos, saltos pequenos e frequentes (uma versão menor de cada vez) são muito mais seguros do que um salto gigante no final. A distância só aumenta.

Não atualize se…

Você está perto do lançamento. As semanas que antecedem o lançamento são o pior momento possível para introduzir mudanças no nível da engine. Lance primeiro, atualize depois.
Você precisa de C# + exportação para Web. A exportação Web para projetos em C# ainda não está disponível no Godot 4.x (acompanhada em godot#70796). Se você depende dela no 3.x, migrar para o 4.x a elimina.
Seu público usa hardware antigo. O Godot 3.x roda em GPUs da classe OpenGL 2; o renderizador Compatibility do Godot 4 exige OpenGL 3.3 / WebGL 2. Se seus jogadores usam máquinas antigas, o 3.x pode ser genuinamente a engine certa.
Addons críticos ainda não foram atualizados. Se um plugin do qual seu projeto depende não suporta a nova versão, você herda o problema de migração dele além do seu.

Regra prática: atualize quando um benefício concreto superar um custo concreto que você estimou — e não porque uma nova versão existe.

Antes de Atualizar — Checklist de Preparação

Cada etapa aqui existe para que, se a atualização der errado, você perca uma tarde, e não um projeto.

Faça commit de tudo e crie um branch de atualização. Nunca atualize a única cópia do seu projeto. Um branch dedicado (ou uma cópia completa da pasta, se você não usa git) faz da reversão um único comando, e não uma missão de resgate.
Registre sua versão exata atual (por exemplo, qual build 4.x.y, standard ou .NET). Você vai precisar dela se tiver que voltar atrás ou reportar um bug.
Guarde o binário do editor antigo. As versões do Godot podem ser instaladas lado a lado — o editor é um único executável, então manter os dois não custa nada e permite abrir o branch antigo com o editor antigo a qualquer momento.
Liste seus addons e confira as versões suportadas por cada um. Percorra a pasta addons/, anote a origem de cada addon e confirme no repositório ou na página da Asset Library que ele suporta a versão de destino.
Leia as notas oficiais de atualização de cada versão que você vai atravessar. Os guias oficiais de migração são escritos por versão — se você for da 4.2 para a 4.4, leia tanto as notas da 4.3 quanto as da 4.4.
Capture evidências do "estado bom conhecido". Tire screenshots das suas cenas principais, grave um clipe curto de gameplay ou — melhor ainda — escreva cenários de teste automatizados (mais sobre isso na seção de testes abaixo). Depois da atualização, a pergunta "está com a mesma aparência e o mesmo comportamento?" só tem resposta se você registrou antes o que significa "o mesmo".

O Procedimento de Atualização

Abra a cópia do branch com o novo editor. O branch de atualização, não o main. O novo editor vai se oferecer para converter/reimportar — aceite.
Deixe a reimportação acontecer. A pasta .godot é regenerada do zero. A primeira importação pode demorar em projetos grandes, e os avisos exibidos nessa primeira passagem geralmente são inofensivos.
Verifique os painéis Output e Debugger em busca de erros novos. Compare com os erros que você já tinha antes (você anotou, certo?). Os erros novos são a lista de tarefas da migração.
Jogue pelos caminhos críticos. Inicie um novo jogo, carregue um save, execute o loop principal de gameplay, abra os menus principais. Erros em tempo de editor são os fáceis — é no comportamento em tempo de execução que as regressões se escondem.
Execute seus cenários de teste (aqueles que você preparou antes de atualizar) e compare com a linha de base.
Revise o diff da árvore de trabalho no git antes de fazer commit. O editor reescreve arquivos durante a migração: o project.godot recebe novos valores de configuração, arquivos .tscn são salvos de novo e novos arquivos .uid podem aparecer. Revise o diff para saber exatamente o que mudou — e então faça um único commit de migração, claramente identificado.

Pontos de Quebra Conhecidos Entre Versões 4.x

As versões menores do Godot 4 são compatíveis em sua maior parte, mas esse "em sua maior parte" carrega bastante peso. Aqui estão as mudanças com mais chance de causar problemas, com base nas notas oficiais e em relatos da comunidade.

4.2 → 4.3: TileMap descontinuado em favor do TileMapLayer

O Godot 4.3 descontinuou o node TileMap em favor do TileMapLayer — um node por camada, em vez de camadas dentro de um único node. TileMaps existentes continuam funcionando, mas código e projetos novos devem usar o TileMapLayer. O editor inclui uma ferramenta de extração: selecione seu TileMap, abra o painel inferior do TileMap, clique no ícone de caixa de ferramentas no canto superior direito e escolha "Extract TileMap layers as individual TileMapLayer nodes".

Armadilha relatada pela comunidade: há relatos de bits de colisão das camadas de física do TileSet sendo redefinidos para os padrões após a migração para TileMapLayer. Não acontece com todo mundo, mas o modo de falha é desagradável (as coisas param de colidir, silenciosamente). Verifique explicitamente as colisões dos seus tiles depois de converter.

4.3 → 4.4: arquivos .uid e adições ao GDScript

O Godot 4.4 adicionou arquivos companheiros .uid ao lado de scripts e shaders. Faça commit deles no controle de versão — apagá-los pode quebrar referências uid:// onde quer que sejam usadas (as notas oficiais de atualização da 4.4 cobrem mudanças relacionadas, como caminhos de @export_file passando a usar uid://). Eles parecem lixo; não são.
Dictionaries tipados e outras adições ao GDScript são retrocompatíveis — seu código antigo continua rodando. Mas addons que adotam os novos recursos deixam de funcionar em versões mais antigas, então o comportamento de um addon pode mudar de um lado para o outro do salto.

Geral: mudanças sutis entre quaisquer versões menores

Ajustes de renderização entre versões menores podem mudar sutilmente a aparência do seu jogo — iluminação, anti-aliasing, snapping 2D. As discussões da comunidade também incluem regressões específicas de cena que não se reproduzem em projetos novos: uma cena se comporta mal depois da atualização, mas reconstruir a mesma cena em um projeto limpo funciona bem. Se algo quebrar de forma inexplicável, tente esta sequência de isolamento: feche o editor, apague a pasta .godot, reabra e deixe tudo reimportar; se o problema persistir, reproduza a cena em um projeto limpo para determinar se o culpado é o estado acumulado do seu projeto ou uma mudança real na engine.

3.x → 4.x é outra história

Tudo acima trata de saltos de 4.x para 4.x. Migrar do Godot 3 para o Godot 4 é uma categoria completamente diferente: a sintaxe do GDScript mudou, muitos nodes foram renomeados, e TileMap, física e renderização foram refeitos do zero — e a maioria dos addons precisa de versões dedicadas para o 4.x. Em projetos 3.x grandes, o custo da migração pode se aproximar do custo de uma reconstrução, e se vale a pena é uma decisão genuinamente caso a caso. Essa migração merece (e tem) documentação própria; este artigo não vai fingir que a cobre.

Testar Depois da Atualização — o Verdadeiro Gargalo

Aqui vai a parte honesta: o motivo número 1 pelo qual desenvolvedores evitam atualizar não é a migração em si — é que verificar manualmente que "nada quebrou" sai caro. Uma passagem completa de regressão manual em um jogo de porte médio pode consumir um fim de semana inteiro. E um bug em tempo de execução que seus jogadores encontram após o lançamento é muito pior do que qualquer erro de editor, porque aí vira um problema de reputação, e não um item de lista de tarefas.

Smoke test manual mínimo

Iniciar um novo jogo a partir da tela de título
Carregar um arquivo de save existente
Jogar o loop principal de gameplay por alguns minutos
Conferir a UI em cada resolução e modo de janela que você suporta

Automatize a comparação antes/depois

A passagem manual não escala e não é capaz de avisar que um sprite se deslocou dois pixels. Foi exatamente para isso que o Godot QA foi criado — um executor de testes para Godot gratuito, de código aberto e com licença MIT. O fluxo de trabalho encaixa perfeitamente em atualizações de versão:

Antes de atualizar, escreva (ou grave) arquivos JSON de cenário cobrindo seus caminhos críticos e capture screenshots de linha de base na versão antiga.
Depois de atualizar, execute exatamente os mesmos cenários mais um diff de pixels contra as linhas de base na versão nova.
As falhas apontam as regressões em minutos, em vez de um fim de semana de replay manual.

Um cenário é apenas uma lista JSON de passos — entradas, esperas, asserções, screenshots:

{
  "name": "core_loop_smoke",
  "steps": [
    {"type": "wait", "seconds": 1.0},
    {"type": "input", "action": "ui_accept", "pressed": true},
    {"type": "wait", "seconds": 0.5},
    {"type": "assert", "node_path": "/root/Main/Player",
     "property": "health", "expected": 100, "operator": "eq"},
    {"type": "input", "action": "move_right", "pressed": true},
    {"type": "wait", "seconds": 2.0},
    {"type": "input", "action": "move_right", "pressed": false},
    {"type": "assert", "node_path": "/root/Main/Player",
     "property": "position:x", "expected": 100.0, "operator": "gt"},
    {"type": "screenshot", "name": "after_move"}
  ]
}

Esse mesmo formato de cenário é o que a ferramenta run_test_scenario do Godot MCP Pro usa, então um assistente de IA conectado ao seu editor pode escrever esses cenários para você.

Se Algo Quebrar

Faça bissecção por versão. Se você saltou várias versões menores de uma vez, refaça a atualização uma versão menor por vez para descobrir exatamente onde quebrou. Isso reduz a busca de "tudo" para um único changelog.
Apague a pasta .godot e deixe o projeto reimportar. Caches de importação obsoletos causam uma parcela surpreendente das esquisitices pós-atualização.
Pesquise nos issues do GitHub da engine pela sua mensagem de erro exata. Se for uma regressão de verdade, muitas vezes alguém já reportou — às vezes com uma solução alternativa.
Verifique se um addon é o culpado. Desative seus addons nas Configurações do Projeto e teste de novo. Se o problema sumir, o culpado é o addon — procure uma versão atualizada antes de culpar a engine.
Aceite que permanecer na versão antiga é um desfecho válido. Se o custo da correção superar o benefício da atualização, reverta o branch, fique onde está e agende um lembrete para tentar de novo quando a próxima versão sair. Isso não é fracasso — é o gerenciamento de risco funcionando.

Quando Ficar Onde Está É a Decisão Certa

Alguns projetos simplesmente não deveriam atualizar, e isso merece ser dito com todas as letras: jogos lançados ou prestes a lançar, projetos em C# que precisam de exportação Web, jogos voltados para hardware antigo e projetos em builds de engine customizadas com muitas modificações. Em todos esses casos, a versão em que você está fazendo o trabalho dela. Atualizar é uma ferramenta, não uma virtude — o objetivo é um jogo terminado, não uma engine novinha em folha.

Perguntas Frequentes

Posso fazer downgrade depois de atualizar?

Não de forma confiável. Assim que o novo editor salva de novo suas cenas e recursos, eles deixam de ser retrocompatíveis com editores mais antigos. O único caminho seguro de volta é restaurar a partir do controle de versão — que é exatamente a razão de existir o branch de atualização.

Devo pular várias versões de uma vez?

Saltos pequenos são mais seguros. As notas oficiais de atualização são escritas por versão, então cada salto tem um checklist conhecido — um salto de várias versões empilha todos eles de uma vez e dificulta saber qual mudança quebrou o quê.

Versões menores realmente quebram coisas?

Raramente, mas sim. A maioria dos projetos atravessa versões menores sem problemas, mas existem casos extremos relatados pela comunidade — bits de colisão sendo redefinidos, regressões de renderização específicas de cena. É justamente por isso que os testes de linha de base antes da atualização importam: eles transformam "será que algo quebrou?" de uma sensação em uma medição.

Este checklist se aplica ao 3.x → 4.x?

O checklist em si, sim — criar branch, guardar o binário antigo, capturar linhas de base, testar depois. A lista de pontos de quebra, não: a migração do 3 para o 4 é muito maior (sintaxe do GDScript, nodes renomeados, sistemas refeitos) e tem sua própria documentação oficial dedicada.