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...

Atualizando de Godot 3 para a Godot 4

Eu deveria atualizar para Godot 4?

Antes de iniciar o processo de atualização, vale a pena pensar sobre as vantagens e desvantagens que a atualização levaria ao seu projeto.

As vantagens de atualizar

Along with the new features present in 4.0, upgrading gives the following advantages:

• Muitos erros estão corrigidos na 4.0, mas não podem ser resolvidos na 3.x por várias razões (como diferenças de API gráficas ou compatibilidade retroativa).

• 4.x terá um período de suporte mais longo. A Godot 3.x continuará a ser suportada por algum tempo depois que 4.0 é liberado, mas deixará eventualmente de receber suporte.

Veja Alterações da Documentação para uma lista de páginas que documentam novos recursos na Godot 4, e veja também Lista de funcionalidades para ver uma lista de todos os recursos da Godot.

As desvantagens de atualizar

Se você não precisa de nenhum recurso presente na Godot 4.x, você provavelmente desejaria ficar na Godot 3.x pelos seguintes motivos:

• Os requisitos básicos de hardware do Godot 4 (como o uso de memória) são ligeiramente maiores, tanto para o editor quanto para projetos exportados. Isso foi necessário para a implementação de algumas otimizações centrais.

• Já que o Godot 4 inclui mais recursos do que o Godot 3, o tamanho do binário dos projetos exportados do Godot 4 é maior. Embora isso possa ser mitigado otimizando a compilação para tamanho, uma compilação 4.0 com um determinado conjunto de módulos habilitados continuará maior quando comparado com uma compilação 3.x com os mesmos módulos. Isso pode ser um problema quando exportando para a Web, já que o tamanho do binário influencia diretamente o quão rápido o motor pode inicializar (independente da velocidade de download).

• Godot 4 does not and will not have support for GLES2 rendering. (There is still support for GLES3 rendering using the new Compatibility renderer, which means that devices without Vulkan support can still run Godot 4.)

  • Se você pretende atender hardware muito antigo como os gráficos integrados Intel Sandy Bridge (2ª generation), isso impedirá que o projeto seja executado nesse hardware após a atualização. Implementações de softwares OpenGL podem ser usadas para contornar essa limitação, mas elas são muito lentas para jogos.

Considerações ao atualizar

Como o Godot 4 é uma reescrita completa em muitos aspectos, algumas funcionalidades foram infelizmente perdidas no processo. Algumas dessas funcionalidades podem ser restauradas em futuras versões do Godot:

• A física da bala foi removida em favor da GodotPhysics. Isso afeta apenas projetos 3D que usaram o motor de física padrão (que foi Bullet) e não o mudaram manualmente para GodotPhysics. Não há planos para re-adicionar a física Bullet no núcleo, mas um add-on de terceiros poderia ser criado para ele graças à GDExtension.

• Por padrão, a renderização em 2D não é mais realizada em HDR, o que significa que valores de modulação "superbrilhantes" não têm efeito visível. Desde o Godot 4.2, você pode ativar a configuração de projeto HDR 2D para realizar a renderização em 2D com HDR. Veja também Using glow in 2D.

• Embora a renderização ainda ocorra em HDR em 3D ao usar os renderizadores Avançado+ ou Mobile, as Viewports não podem mais retornar dados HDR. Há planos para que isso seja restaurado em algum momento no futuro.

• O Mono foi substituído pelo .NET 6. Isso significa que a exportação de projetos C# para Android, iOS e HTML5 não é mais suportada por enquanto. A exportação de projetos C# para plataformas desktop ainda é suportada e, a partir da versão 4.2, há suporte experimental para exportação para plataformas móveis. O suporte para exportação de projetos C# para mais plataformas será restaurado em futuras versões 4.x, conforme o suporte upstream for aprimorado.

You can find a more complete list of functional regressions by searching for issues labeled "regression" but not "bug" on GitHub.

Preparing before the upgrade (optional)

Se você quiser estar pronto para atualizar para o Godot 4 no futuro, considere usar Tweener e o singleton Time no seu projeto. Ambas as classes estão disponíveis no Godot 3.5 e versões posteriores.

Dessa forma, você não dependerá das funções obsoletas de nó Tween e de tempo do sistema operacional, ambas removidas no Godot 4.0.

Também é uma boa ideia renomear os shaders externos para que sua extensão seja .gdshader em vez de .shader. O Godot 3.x suporta ambas as extensões, mas somente .gdshader é suportado no Godot 4.0.

Running the project upgrade tool

Perigo

Faça um backup completo do seu projeto antes de atualizar! A ferramenta de atualização de projeto não fará backup do projeto que está sendo atualizado.

Você pode fazer backup de um projeto usando o controle de versão ou copiando a pasta do projeto para outro local.

Usando o Gerenciador de Projetos

Para usar a ferramenta de atualização do projeto:

1. Abra o Gerenciador de Projetos da Godot 4.

2. Importe o projeto Godot 3.x usando o botão Importar ou use o botão Escanear para encontrar o projeto em uma pasta.

3. Clique duas vezes no projeto importado (ou selecione o projeto e escolha Editar).

4. Você verá uma caixa de diálogo com duas opções: Converter apenas project.godot e Converter projeto completo. Após garantir que o backup do seu projeto esteja concluído (veja o aviso acima), escolha Converter projeto completo. Converter apenas project.godot deve ser usado apenas em casos de uso avançado, caso a ferramenta de conversão falhe.

5. Aguarde a conclusão do processo de conversão do projeto. Isso pode levar alguns minutos para projetos grandes com muitas cenas.

6. Quando a interface do Gerenciador de Projetos estiver disponível novamente, clique duas vezes no projeto (ou selecione o projeto e escolha Editar) para abri-lo no editor.

Se você tiver problemas de conversão devido a alguns arquivos de projeto serem muito grandes ou longos, você pode usar a linha de comando para atualizar o projeto (veja abaixo). Isso permitirá que você substitua os limites de tamanho do conversor.

Using the command line

Para usar a ferramenta de atualização de projeto da linha de comando, é recomendável validar a conversão do projeto executando o executável do editor Godot com os seguintes argumentos:

# [<max_file_kb>] [<max_line_size>] are optional arguments.
# Remove them if you aren't changing their values.
path/to/godot.binary --path /path/to/project/folder --validate-conversion-3to4 [<max_file_kb>] [<max_line_size>]

Se a lista de atualizações planejadas parecer boa para você, execute o seguinte comando no executável do editor do Godot para atualizar os arquivos do projeto:

# [<max_file_kb>] [<max_line_size>] are optional arguments.
# Remove them if you aren't changing their values.
path/to/godot.binary --path /path/to/project/folder --convert-3to4 [<max_file_kb>] [<max_line_size>]

[<max_file_kb>] e [<max_line_size>] são argumentos opcionais usados para especificar o tamanho máximo dos arquivos a serem convertidos (em kilobytes e linhas). Os limites padrão são 4 MB e 100.000 linhas, respectivamente. Se um arquivo atingir qualquer um desses limites, ele não será atualizado pela ferramenta de conversão de projeto. Isso é útil para evitar que recursos muito grandes deixem o processo de atualização extremamente lento.

Se você ainda quiser que arquivos grandes sejam convertidos pela ferramenta de atualização de projeto, aumente os limites de tamanho ao executá-la. Por exemplo, executar o executável do editor Godot com esses argumentos aumenta ambos os limites em um fator de 10x:

path/to/godot.binary --path /path/to/project/folder --convert-3to4 40000 1000000

Nota

Somente projetos do Godot 3.0 e posteriores podem ser atualizados usando a ferramenta de conversão de projetos encontrada no editor do Godot 4.

É recomendável garantir que seu projeto esteja atualizado com a versão estável 3.x mais recente antes de executar a ferramenta de atualização do projeto.

Corrigindo o projeto após executar a ferramenta de atualização do projeto

Após atualizar o projeto, você poderá notar que algumas coisas não estão como deveriam. Os scripts provavelmente também conterão vários erros (possivelmente centenas em projetos grandes). Isso ocorre porque a ferramenta de atualização do projeto não consegue atender a todas as situações. Portanto, grande parte do processo de atualização permanece manual.

Automatically renamed nodes and resources

A lista abaixo refere-se aos nós que foram simplesmente renomeados para consistência ou clareza no Godot 4.0. A ferramenta de atualização do projeto os renomeia automaticamente nos seus scripts.

Um conjunto notável de renomeações são os nós 3D, que receberam o sufixo 3D para manter a consistência com suas contrapartes 2D. Por exemplo, Area agora é Area3D.

Para facilitar a pesquisa, esta tabela lista todos os nós e recursos, que foram renomeados e convertidos automaticamente, excluindo aqueles que envolveram apenas a adição de um sufixo 3D ao nome antigo:

Nome antigo (Godot 3.x)	Novo nome (Godot 4)
AnimatedSprite (Sprite animado)	AnimatedSprite2D
ARVRCamera (Câmera de Realidade Aumentada e Realidade Virtual)	XRCamera3D (Câmera 3D de Realidade Estendida)
ARVRController (Controle de Realidade Aumentada e Realidade Virtual)	XRController3D (Controle 3D de Realidade Estendida)
ARVRAnchor	XRAnchor3D
ARVRInterface	XRInterface (Interface de Realidade Estendida)
ARVROrigin	XROrigin3D
ARVRPositionalTracker	XRPositionalTracker
ARVRServer (Servidor de Realidade Aumentada e Realidade Virtual)	XRServer (Servidor de Realidade Estendida)
BoxShape	BoxShape3D
CapsuleShape	CapsuleShape3D
CubeMesh (Malha de Cubo)	BoxMesh (Malha de Caixa)
EditorSpatialGizmo (Editor de Gizmo Espacial)	EditorNode3DGizmo
EditorSpatialGizmoPlugin (Plugin de Editor de Gizmo Espacial)	EditorNode3DGizmoPlugin (Editor de Nó 3D de Plugin de Gizmo)
GIProbe	VoxelGI
GIProbeData	VoxelGIData
GradientTexture (Textura de Gradiente)	GradientTexture1D (Textura de Gradiente 1D)
KinematicBody (Corpo Cinemático)	CharacterBody3D
KinematicBody2D	CharacterBody2D
Light2D (Luz 2D)	PointLight2D (Ponto de Luz 2D)
LineShape2D	WorldBoundaryShape2D
Ouvinte (Listener)	AudioListener3D (Ouvinte de Áudio 3D)
NavigationMeshInstance (Instância de Malha de Navegação)	NavigationRegion3D (Região de Navegação 3D)
NavigationPolygonInstance (Instância de Polígono de Navegação)	NavigationRegion2D (Região de Navegação 2D)
Navigation2DServer (Servidor de Navegação 2D)	NavigationServer2D (Servidor 2D de Navegação)
PanoramaSky	Sky (Céu)
Partículas	GPUParticles3D (Partículas 3D da GPU)
Particles2D (Partículas 2D)	GPUParticles2D (Partículas 2D da GPU)
ParticlesMaterial	ParticleProcessMaterial (Material do Processo de Partículas)
Physics2DDirectBodyState	PhysicsDirectBodyState2D
Physics2DDirectSpaceState	PhysicsDirectSpaceState2D
Physics2DServer (Servidor de Física 2D)	PhysicsServer2D
Physics2DShapeQueryParameters	PhysicsShapeQueryParameters2D
Physics2DTestMotionResult	PhysicsTestMotionResult2D
PlaneShape	WorldBoundaryShape3D
Position2D	Marker2D
Position3D	Marker3D
ProceduralSky (Céu Procedural)	Sky (Céu)
RayShape	SeparationRayShape3D
RayShape2D	SeparationRayShape2D
ShortCut	Shortcut
Espacial	Node3D
SpatialGizmo (Gizmo Espacial)	Node3DGizmo
SpatialMaterial (Material de Gizmo)	StandardMaterial3D (Material Padrão 3D)
Sprite	Sprite2D
StreamTexture (Textura de Fluxo)	CompressedTexture2D (Textura 2D Compactada)
TextureProgress (Textura de Progresso)	TextureProgressBar (Textura de Barra de Progresso)
VideoPlayer (Reprodutor de Vídeo)	VideoStreamPlayer (Reprodutor de Fluxo de Vídeo)
ViewportContainer	SubViewportContainer
Viewport (Janela de Exibição)	SubViewport (Sub Janela de Exibição)
VisibilityEnabler (Habilitador de Visibilidade)	VisibleOnScreenEnabler3D
VisibilityNotifier (Notiicador de Visibilidade)	VisibleOnScreenNotifier3D
VisibilityNotifier2D (Notiicador de Visibilidade 2D)	VisibleOnScreenNotifier2D
VisibilityNotifier3D (Notiicador de Visibilidade 3D)	VisibleOnScreenNotifier3D
VisualServer (Servidor Visual)	RenderingServer (Servidor de Renderização)
VisualShaderNodeScalarConstant	VisualShaderNodeFloatConstant
VisualShaderNodeScalarFunc	VisualShaderNodeFloatFunc
VisualShaderNodeScalarOp	VisualShaderNodeFloatOp
VisualShaderNodeScalarClamp	VisualShaderNodeClamp (Nó Shader Visual de Alinhamento)
VisualShaderNodeVectorClamp (Nó Shader Visual de Alinhamento de Vetor)	VisualShaderNodeClamp (Nó Shader Visual de Alinhamento)
VisualShaderNodeScalarInterp (Nó Shader Visual de Interpolação Escalar)	VisualShaderNodeMix (Nó Shader Visual de Mistura)
VisualShaderNodeVectorInterp (Nó Shader Visual de Interpolação de Vetor)	VisualShaderNodeMix (Nó Shader Visual de Mistura)
VisualShaderNodeVectorScalarMix (Nó Shader Visual de Mistura Escalar de Vetores)	VisualShaderNodeMix (Nó Shader Visual de Mistura)
VisualShaderNodeScalarSmoothStep	VisualShaderNodeSmoothStep (Nó Shader Visual de Passo Suave)
VisualShaderNodeVectorSmoothStep	VisualShaderNodeSmoothStep (Nó Shader Visual de Passo Suave)
VisualShaderNodeVectorScalarSmoothStep	VisualShaderNodeSmoothStep (Nó Shader Visual de Passo Suave)
VisualShaderNodeVectorScalarStep	VisualShaderNodeStep (Nó Shader Visual de Passos)
VisualShaderNodeScalarSwitch (Nó Shader Visual de Interruptor Escalar)	VisualShaderNodeSwitch (Nó Shader Visual de Interruptor)
VisualShaderNodeScalarTransformMult	VisualShaderNodeTransformOp
VisualShaderNodeScalarDerivativeFunc	VisualShaderNodeDerivativeFunc
VisualShaderNodeVectorDerivativeFunc	VisualShaderNodeDerivativeFunc
VisualShaderNodeBooleanUniform	VisualShaderNodeBooleanParameter
VisualShaderNodeColorUniform	VisualShaderNodeColorParameter
VisualShaderNodeScalarUniform	VisualShaderNodeFloatParameter
VisualShaderNodeCubeMapUniform	VisualShaderNodeCubeMapParameter
VisualShaderNodeTextureUniform	VisualShaderNodeTexture2DParameter
VisualShaderNodeTextureUniformTriplanar	VisualShaderNodeTextureParameterTriplanar
VisualShaderNodeTransformUniform	VisualShaderNodeTransformParameter
VisualShaderNodeVec3Uniform	VisualShaderNodeVec3Parameter
VisualShaderNodeUniform (Nó Shader Visual de ...)	VisualShaderNodeParameter
VisualShaderNodeUniformRef	VisualShaderNodeParameterRef

Renomear manualmente, métodos, sinais e constantes

Due to how the project upgrade tool works, not all API renames can be performed automatically. The list below contains all renames that must be performed manually using the script editor.

Se você não conseguir encontrar um nó ou recurso na lista abaixo, consulte a tabela acima para encontrar seu novo nome.

Dica

Você pode usar a caixa de diálogo Substituir em Arquivos para agilizar substituições pressionando Ctrl + Shift + R enquanto o editor de scripts estiver aberto. No entanto, tenha cuidado, pois essa caixa de diálogo não oferece nenhuma forma de desfazer uma substituição. Use controle de versão para confirmar regularmente o progresso do seu trabalho de atualização. Ferramentas de linha de comando como sd também podem ser usadas se você precisar de algo mais flexível do que a caixa de diálogo Substituir em Arquivos do editor.

Se estiver usando C#, lembre-se de procurar por uso obsoleto da API com a notação PascalCase no projeto (e realizar a substituição com a notação PascalCase).

Métodos

• As classes File e Directory foram substituídas por FileAccess e DirAccess, que possuem uma API totalmente diferente. Vários métodos agora são estáticos, o que significa que você pode chamá-los diretamente em FileAccess ou DirAccess sem precisar criar uma instância dessa classe.

• Métodos relacionados à tela e à janela do singleton OS (como OS.get_screen_size()) foram movidos para o singleton DisplayServer. A nomenclatura dos métodos também foi alterada para o formato DisplayServer.<objeto>_<get/set>_property(). Por exemplo, OS.get_screen_size() passou a ser DisplayServer.screen_get_size().

• Os métodos de hora e data do singleton OS foram movidos para o singleton Time. (O singleton Time também está disponível no Godot 3.5 e versões posteriores.)

• Talvez seja necessário substituir algumas chamadas instance() por instantiate(). O conversor deve lidar com isso automaticamente, mas isso depende de código personalizado que pode não funcionar em 100% das situações.

• O set_autowrap() do AcceptDialog agora é set_autowrap_mode().

• process() do AnimationNode agora é _process() (observe o sublinhado inicial, que denota um método virtual).

• add_animation() do AnimationPlayer agora é add_animation_library() e agora usa uma AnimationLibrary.

• AnimationTree's set_process_mode() is now set_process_callback().

• Array's empty() is now is_empty().

• Array's invert() is now reverse().

• Array's remove() is now remove_at().

• get_points() do AStar2D e AStar3D agora é get_points_id().

• set_event() do BaseButton agora é set_shortcut().

• Camera2D's get_h_offset() is now get_drag_horizontal_offset().

• get_v_offset() do Camera2D agora é get_drag_vertical_offset().

• Camera2D's set_h_offset() is now set_drag_horizontal_offset().

• set_v_offset() do Camera2D agora é set_drag_vertical_offset().

• raise() do CanvasItem agora é move_to_front().

• update() do CanvasItem agora é queue_redraw().

• Control's get_stylebox() is now get_theme_stylebox().

• set_tooltip() do controle agora é set_tooltip_text().

• create_gizmo() do EditorNode3DGizmoPlugin agora é _create_gizmo() (observe o sublinhado inicial, que denota um método virtual).

• get_peer_port() de ENetMultiplayerPeer agora é get_peer().

• FileDialog get_mode() agora é get_file_mode().

• FileDialog set_mode() agora é set_file_mode().

• get_offset() do GraphNode agora é get_position_offset().

• map_to_world() do GridMap agora é map_to_local().

• world_to_map() do GridMap agora é local_to_map().

• get_rect() do Image agora é get_region().

• ImmediateGeometry's set_normal() is now surface_set_normal().

• ImmediateMesh's set_color() is now surface_set_color().

• ImmediateMesh's set_uv() is now surface_set_uv().

• get_v_scroll() do ItemList agora é get_v_scroll_bar().

• get_network_connected_peers() do MultiPlayerAPI agora é get_peers().

• get_network_peer() do MultiPlayerAPI agora é get_peer().

• get_network_unique_id() do MultiPlayerAPI agora é get_unique_id().

• has_network_peer() do MultiPlayerAPI agora é has_multiplayer_peer().

• is_refusing_new_network_connections() da MultiplayerAPI agora é is_refusing_new_connections().

• is_listening() do PacketPeerUDP agora é is_bound().

• listen() do PacketPeerUDP agora é bind().

• set_flag() do ParticleProcessMaterial agora é set_particle_flag().

• PhysicsTestMotionResult2D's get_motion() is now get_travel().

• RenderingServer's get_render_info() is now get_rendering_info().

• get_dependencies() do ResourceFormatLoader agora é _get_dependencies() (observe o sublinhado inicial, que denota um método virtual).

• ResourceFormatLoader's load() is now _load().

• change_scene() do SceneTree agora é change_scene_to_file().

• O atalho is_valid() agora é has_valid_event().

• map_to_world() do TileMap agora é map_to_local().

• world_to_map() do TileMap agora é local_to_map().

• xform() do Transform2D é mat * vec e xform_inv() é vec * mat.

• XRPositionalTracker's get_name() is now get_tracker_name().

• XRPositionalTracker's get_type() is now get_tracker_type().

• XRPositionalTracker's _set_name() is now get_tracker_name().

Propriedades

Nota

Se uma propriedade estiver listada aqui, seus métodos getter e setter associados também deverão ser renomeados manualmente, se utilizados no projeto. Por exemplo, set_offset() e get_offset() de PathFollow2D e PathFollow3D devem ser renomeados para set_progress() e get_progress(), respectivamente.

• O device do AudioServer agora é output_device.

• O group do BaseButton agora é button_group.

• zfar do Camera3D agora é far.

• znear do Camera3D agora é near

• A margem do Control agora é deslocamento.

• O doubleclick do InputEventMouseButton agora é double_click.

• alt de InputEventWithModifiers agora é alt_pressed.

• O command de InputEventWithModifiers agora é command_pressed.

• O control de InputEventWithModifiers agora é ctrl_pressed.

• meta de InputEventWithModifiers agora é meta_pressed.

• shift de InputEventWithModifiers agora é shift_pressed.

• percent_visible do Label agora é visible_ratio.

• refuse_new_network_connections do MultiPlayerAPI agora é refuse_new_connections.

• Node's filename is now scene_file_path.

• rotate do PathFollow2D agora é rotates.

• O offset do PathFollow2D e PathFollow3D agora é progress.

• extents do RectangleShape2D agora é size

• percent_visible do TextureProgressBar agora é show_percentage.

• off do Theme agora é unchecked.

• ofs do Theme agora é offset.

• on do Theme agora é checked.

• window_title do Window agora é title.

• d do WorldMarginShape2D agora é distance.

• A propriedade extents nos nós CSG e VoxelGI terá que ser substituída por size, com o valor definido reduzido pela metade (já que não são mais extensões pela metade). Isso também afeta seus métodos setter/getter set_extents() e get_extents().

• A propriedade Engine.editor_hint foi removida em favor do método Engine.is_editor_hint(). Isso ocorre porque ela é somente leitura, e propriedades no Godot não são usadas para valores somente leitura.

Enumeradores

• FLAG_MAX do CPUParticles2D agora é PARTICLE_FLAG_MAX.

Sinais

• instantiate do FileSystemDock agora é instance.

• hide do CanvasItem agora é hidden. Esta renomeação não se aplica ao método hide(), apenas ao sinal.

• tween_all_completed do Tween agora é loop_finished.

• changed do EditorSettings agora é settings_changed.

Constantes

• Os nomes das cores agora são escritos em letras maiúsculas e usam sublinhados entre as palavras. Por exemplo, Color.palegreen agora é Color.PALE_GREEN.

• As constantes NOTIFICATION_ do MainLoop foram duplicadas para Node, o que significa que você pode remover o prefixo MainLoop. ao referenciá-las.

• NOTIFICATION_WM_QUIT_REQUEST do MainLoop agora é NOTIFICATION_WM_CLOSE_REQUEST.

Checking project settings

Várias configurações do projeto foram renomeadas, e algumas delas tiveram suas enumerações alteradas de maneiras incompatíveis (como a qualidade do filtro de sombra). Isso significa que você pode precisar redefinir alguns valores das configurações do projeto. Certifique-se de que a opção Avançado esteja habilitada na caixa de diálogo de configurações do projeto para que você possa ver todas as configurações do projeto.

Checking Environment settings

As configurações de qualidade gráfica foram movidas das propriedades do Environment para as configurações do projeto. Isso foi feito para facilitar os ajustes de qualidade em tempo de execução, sem a necessidade de acessar o recurso do Environment ativo e, em seguida, modificar suas propriedades.

Como resultado, você terá que configurar as configurações de qualidade do Environment nas configurações do projeto, pois as configurações antigas de qualidade do Environment não são convertidas automaticamente para as configurações do projeto.

Se você tiver um menu de configurações gráficas que alterou as propriedades do ambiente no Godot 3.x, será necessário alterar o código para chamar os métodos RenderingServer que afetam a qualidade dos efeitos do ambiente. Somente o botão de alternância "base" de cada efeito do ambiente e seus botões visuais permanecem no recurso do Environment.

Updating shaders

Houve algumas alterações nos shaders que não são cobertas pela ferramenta de atualização. Você precisará fazer algumas alterações manuais, especialmente se o seu shader usar transformações de espaço de coordenadas ou uma função light() personalizada.

A extensão de arquivo .shader não é mais suportada, o que significa que você deve renomear os arquivos .shader para .gdshader e atualizar as referências adequadamente nos arquivos de cena/recurso usando um editor de texto externo.

Algumas mudanças notáveis que você precisará realizar nos shaders são:

• Os modos de filtragem e repetição de textura agora são definidos individualmente por uniforme, em vez de nos próprios arquivos de textura.

• hint_albedo agora é source_color.

• hint_color agora é source_color.

• Built in matrix variables were renamed.

• Os shaders de partículas não usam mais a função de processador vertex(). Em vez disso, eles usam start() e process().

• Nos renderizadores Avançado+ e Mobile, as coordenadas normalizadas de dispositivo (NDC) agora possuem um intervalo Z de [0.0,1.0] em vez de [-1.0,1.0]. Ao reconstruir as NDC a partir de SCREEN_UV e profundidade, use vec3 ndc = vec3(SCREEN_UV * 2.0 - 1.0, depth); em vez de vec3 ndc = vec3(SCREEN_UV, depth) * 2.0 - 1.0;. O renderizador Compatibilidade permanece inalterado, utilizando o mesmo intervalo Z de NDC da versão 3.x.

• O modelo de iluminação mudou. Se o seu shader tiver uma função light() personalizada, talvez seja necessário fazer alterações para obter o mesmo resultado visual.

• Na versão 4.3 e posteriores, a técnica de buffer de profundidade Z reverso foi implementada, o que pode danificar shaders avançados. Veja Apresentando o Z Reverso (também conhecido como "Desculpe por danificar seu shader").

See Linguagem de shading for more information.

This list is not exhaustive. If you made all the changes mentioned here and your shader still doesn't work, try asking for help in one of the community channels.

Atualizando scripts para considerar alterações incompatíveis com versões anteriores

Algumas alterações realizadas entre o Godot 3.x e 4 não são renomeações, mas ainda quebram a compatibilidade com versões anteriores devido ao comportamento padrão diferente.

Os exemplos mais notáveis disto são:

• Funções de ciclo de vida como _ready() e _process() não chamam mais implicitamente funções de classes pai com o mesmo nome. Em vez disso, você deve usar super() no topo de uma função de ciclo de vida na classe filha para que a função da classe pai seja chamada primeiro.

• Tanto String quanto StringName agora estão expostos ao GDScript. Isso permite maior otimização, já que StringName foi projetado especificamente para ser usado com strings "constantes" que são criadas uma vez e reutilizadas diversas vezes. Esses tipos não são estritamente equivalentes entre si, o que significa que is_same("example", &"example") retorna false. Embora na maioria dos casos sejam intercambiáveis ("example" == &"example" retorna true), às vezes pode ser necessário substituir "example" por &"example".

• A sintaxe de setter e getter do GDScript foi alterada, mas é convertida somente parcialmente pela ferramenta de conversão. Na maioria dos casos, alterações manuais são necessárias para que setters e getters voltem a funcionar.

• A sintaxe de conexão dos sinais no GDScript foi alterada. A ferramenta de conversão usará a sintaxe baseada em strings, que continua presente no Godot 4, mas é recomendável mudar para a sintaxe baseada em Signal descrita na página vinculada. Dessa forma, strings não são mais envolvidas, evitando problema com erros de nome de sinal que só podem ser descobertos em tempo de execução.

• Scripts integrados que são scripts de ferramentas não têm a palavra-chave tool convertida na anotação @tool.

• O nó Tween foi removido em favor dos Tweeners, que também estão disponíveis no Godot 3.5 e versões posteriores. Veja o pull request original para mais detalhes.

• randomize() agora é chamado automaticamente no carregamento do projeto, portanto a aleatoriedade determinística com a instância global RandomNumberGenerate requer a configuração manual de uma semente na função _ready() de um script.

• call_group(), set_group() e notify_group() agora são imediatos por padrão. Se estiver chamando uma função custosa, isso pode causar travamentos quando usado em um grupo com um grande número de nós. Para utilizar chamadas adiadas como antes, substitua call_group(...) por call_group_flags(SceneTree.GROUP_CALL_DEFERRED, ...) (e faça o mesmo com set_group() e notify_group() respectivamente).

• Em vez de rotation_degrees, a propriedade rotation é exposta ao editor, sendo exibida automaticamente como graus na aba do Inspetor. Isso pode interromper as animações, pois a conversão não é realizada automaticamente pela ferramenta de conversão.

• O método has_no_surface() da AABB foi invertido e renomeado para has_surface().

• has_no_area() de AABB e Rect2 foi invertido e renomeado para has_area().

• A propriedade fps do AnimatedTexture foi substituída por speed_scale, que funciona da mesma forma que a propriedade playback_speed do AnimationPlayer.

• AnimatedSprite2D e AnimatedSprite3D agora permitem valores speed_scale negativos. Isso pode interromper as animações se você depender de speed_scale ser fixado internamente em 0.0.

• A propriedade playing de AnimatedSprite2D e AnimatedSprite3D foi removida. Use o método play()/stop() OU configure a animação autoplay através do painel inferior SpriteFrames (mas não ambos ao mesmo tempo).

• O segundo parâmetro slice() de Array (end) agora é exclusivo, em vez de inclusivo. Por exemplo, isso significa que [1, 2, 3].slice(0, 1) agora retorna [1] em vez de [1, 2].

• Os sinais de BaseButton agora são button_up e button_down. A propriedade pressed agora é button_pressed.

• A propriedade rotating de Camera2D foi substituída por ignore_rotation, que tem comportamento invertido.

• A propriedade zoom do Camera2D foi invertida: valores mais altos agora são mais ampliados, em vez de menos.

• O método remove_and_skip() da Node foi removido. Se precisar reimplementá-lo em um script, você pode usar a implementação antiga em C++ como referência.

• OS.get_system_time_secs() deve ser convertido para Time.get_time_dict_from_system()["second"].

• O método save() de ResourceSaver agora tem seus argumentos trocados (resource: Resource, path: String). Isso também se aplica ao método _save() de ResourceFormatSaver.

• Um StreamPeerTCP deve ter poll() chamado para atualizar seu estado, em vez de depender de get_status() para pesquisar automaticamente: GH-59582

• O método right() da String teve seu comportamento alterado: agora ele retorna um número de caracteres a partir da direita da string, em vez de retornar a parte direita da string a partir de uma posição fornecida. Se você precisar do comportamento antigo, pode usar substr() no lugar.

• is_connected_to_host() foi removido do StreamPeerTCP e PacketPeerUDP conforme GH-59582. Em vez disso, get_status() pode ser usado no StreamPeerTCP e is_socket_connected() pode ser usado em PacketPeerUDP.

• Em _get_property_list(), a string de dica de propriedade or_lesser agora é or_less.

• Em _get_property_list(), a string de dica de propriedade noslider agora é no_slider.

• VisualShaderNodeVec4Parameter agora aceita um Vector4 como parâmetro em vez de um Quaternion.

Nós/recursos removidos ou substituídos

Esta lista contém todos os nós substituídos por outro nó que requer configuração diferente. A configuração deve ser feita do zero novamente, pois o conversor de projeto não suporta a atualização de configurações existentes:

Removed node	Closest approximation	Comente
AnimationTreePlayer (Reprodutor de Árvore de Animação)	AnimationTree (Árvore de Animação)	AnimationTreePlayer está obsoleto desde Godot 3.1.
BakedLightmap (Lightmaps Pré-Calculados)	LightmapGI	Veja Usando a iluminação global Lightmap.
BakedLightmapData (Dados de Lightmaps Pré-Calculados)	LightmapGIData
BitmapFont	FontFile (Arquivo de Fonte)	Veja Using Fonts.
Fonte Dinâmica	FontFile (Arquivo de Fonte)
DynamicFontData (Dados de Fontes Dinâmicas)	FontFile (Arquivo de Fonte)
ClippedCamera	Camera2D or Camera3D	O formato de pirâmide da câmera foi movido para :ref:'class_Camera3D'.
InterpolatedCamera	Camera2D or Camera3D
Navigation2D (Navegação 2D)	Node2D (Nó 2D)	Substituído por outros nós de navegação 2D.
Navigation3D (Navegação 3D)	Node3D	Substituído por outros nós de navegação 3D.
OpenSimplexNoise	FastNoiseLite	Possui parâmetros diferentes e mais tipos de ruído, como o celular (ruído de Worley). Não há suporte para ruído 4D por estar ausente na biblioteca FastNoiseLite.
ToolButton (Botão de ferramentas)	Botão	ToolButton era um botão com a propriedade Flat habilitada por padrão.
YSort	Node2D or Control	CanvasItem tem uma nova propriedade Y Sort Enabled na versão 4.0.
ProximityGroup	Node3D	VisibleOnScreenNotifier3D pode atuar como um substituto.
Portal	Node3D	Oclusão de portais e de salas foi substituída por raster occlusion culling (nó OccluderInstance3D), que requer um processo de configuração diferente.
Quarto	Node3D
RoomManager	Node3D
RoomGroup (Grupo de Sala)	Node3D
Occluder (Oclusor)	Node3D	O abate por oclusão Geométrica foi substituído por raster occlusion culling (nó OccluderInstance3D), que requer um processo de configuração diferente.
OccluderShapeSphere	Recurso

Ao carregar um projeto antigo, o nó será substituído automaticamente por sua Aproximação mais próxima (mesmo que você não esteja usando a ferramenta de atualização do projeto).

Threading changes

Threading As APIs mudaram na versão 4.0. Por exemplo, o seguinte trecho de código no Godot 3.x deve ser modificado para funcionar no 4.0:

# 3.x
var start_success = new_thread.start(self, "__threaded_background_loader",
    [resource_path, thread_num]
)

# 4.0
var start_success = new_thread.start(__threaded_background_loader.bind(resource_path, thread_num))

Thread.is_active() não é mais usado e deve ser convertido para Thread.is_alive().

Ver também

Veja o changelog para uma lista completa de mudanças entre o Godot 3.x e 4.

Quebra de compatibilidade de recursos do ArrayMesh

Se você salvou um recurso ArrayMesh em um arquivo .res ou .tres, o formato usado na versão 4.0 não é compatível com o usado na versão 3.x. Você precisará passar pelo processo de importar o arquivo de malha de origem e salvá-lo como um recurso ArrayMesh novamente.

Lista de métodos, propriedades, sinais e constantes renomeados automaticamente

The editor/project_upgrade/renames_map_3_to_4.cpp source file lists all automatic renames performed by the project upgrade tool. Lines that are commented out refer to API renames that cannot be performed automatically.

Porting editor settings

Godot 3.x e 4.0 usam arquivos de configurações de editor diferentes. Isso significa que suas configurações podem ser alteradas independentemente uma da outra.

Se você deseja transferir suas configurações do Godot 3.x para o Godot 4, abra a pasta de configurações do editor e copie editor_settings-3.tres para editor_settings-4.tres enquanto o editor do Godot 4 estiver fechado.

Nota

Muitos nomes e categorias de configurações foram alterados desde o Godot 3.x. As configurações do editor cujo nome ou categoria foram alterados não serão transferidas para o Godot 4.0; você terá que definir seus valores novamente.

Updating version control settings

O Godot 3.x e o 4.x possuem listas completamente diferentes de arquivos e pastas que devem ser ignorados pelo seu version control system.