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

Upgrading from Godot 4.4 to Godot 4.5

For most games and apps made with 4.4 it should be relatively safe to migrate to 4.5. This page intends to cover everything you need to pay attention to when migrating your project.

Breaking changes

If you are migrating from 4.4 to 4.5, the breaking changes listed here might affect you. Changes are grouped by areas/systems.

Aviso

A fim de dar suporte aos novos requisitos do Google Play, o Android agora exige que os projetos C# tenham como alvo o .NET 9 ao serem exportados para Android. Outras plataformas continuam a usar o .NET 8 como a versão mínima exigida, mas versões mais novas são suportadas e encorajadas.

Se você estiver usando C# em seu projeto e quiser exportar para Android, precisará atualizar seu projeto para o .NET 9 (consulte Upgrading to a new .NET version para obter instruções).

Este artigo indica se cada alteração drástica afeta o GDScript e se a alteração drástica do C# é compatível com o binário ou compatível com o código-fonte:

• Binary compatible - Existing binaries will load and execute successfully without recompilation, and the run-time behavior won't change.

• Compatível com a fonte - O código fonte será compilado com sucesso, sem alterações, ao atualizar o Godot.

Componentes Principais

Mudança	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduzido
JSONRPC
Method set_scope replaced by set_method	❌	|❌ com stub|	|❌ com stub|	GH-104890
Node
Method get_rpc_config renamed to get_node_rpc_config	❌	✔️	✔️	GH-106848
Method set_name changes name parameter type from String to StringName	✔️	✔️	✔️	GH-76560

Renderização

Mudança	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduzido
DisplayServer
Method file_dialog_show adds a new parent_window_id optional parameter	✔️	✔️	✔️	GH-98194
Method file_dialog_with_options_show adds a new parent_window_id optional parameter	✔️	✔️	✔️	GH-98194
Dispositivo de Renderização
Method texture_create_from_extension adds a new mipmaps optional parameter	✔️	✔️	✔️	GH-105570
Dispositivo de Servidor
Method instance_reset_physics_interpolation removed	❌	✔️	✔️	GH-104269
Method instance_set_interpolated removed	❌	✔️	✔️	GH-104269

Nota

In C#, the enum RenderingDevice.Features breaks compatibility because of the way the bindings generator detects the enum prefix. New members were added to the enum in GH-103941 that caused the enum member Address to be renamed to BufferDeviceAddress.

GLTF

Mudança	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduzido
GLTFAccessor
Property byte_offset changes type metadata from int32 to int64	✔️	❌	❌	GH-106220
Property component_type changes type from int to GLTFAccessor::GLTFComponentType	✔️	❌	❌	GH-106220
Property count changes type metadata from int32 to int64	✔️	❌	❌	GH-106220
Property sparse_count changes type metadata from int32 to int64	✔️	❌	❌	GH-106220
Property sparse_indices_byte_offset changes type metadata from int32 to int64	✔️	❌	❌	GH-106220
Property sparse_indices_component_type changes type from int to GLTFAccessor::GLTFComponentType	✔️	❌	❌	GH-106220
Property sparse_values_byte_offset changes type metadata from int32 to int64	✔️	❌	❌	GH-106220
GLTFBufferView
Property byte_length changes type metadata from int32 to int64	✔️	❌	❌	GH-106220
Property byte_offset changes type metadata from int32 to int64	✔️	❌	❌	GH-106220
Property byte_stride changes type metadata from int32 to int64	✔️	❌	❌	GH-106220

Nota

Como resultado da alteração dos metadados de tipo, os bindings de C# mudaram o tipo de int (32-bytes) para long (64-bytes).

Text

Mudança	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduzido
CanvasItem
Method draw_char adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method draw_char_outline adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method draw_multiline_string adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method draw_multiline_string_outline adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method draw_string adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method draw_string_outline adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Fonte
Method draw_char adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method draw_char_outline adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method draw_multiline_string adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method draw_multiline_string_outline adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method draw_string adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method draw_string_outline adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Texto Formatado
Method add_image adds a new alt_text optional parameter	✔️	✔️	✔️	GH-76829
Método add_image (adicionar imagem) replaced size_in_percent (tamanho em porcentagem) parâmetro por width_in_percent (largura em porcentagem) e height_in_percent (haltura em porcentagem)	✔️	✔️	✔️	GH-107347
Method push_strikethrough adds optional color parameter	✔️	✔️	✔️	GH-106300
Method push_table adds a new name optional parameter	✔️	✔️	✔️	GH-76829
Method push_underline adds optional color parameter	✔️	✔️	✔️	GH-106300
O parâmetro size_in_percent do método update_image foi substituído por width_in_percent e height_in_percent	✔️	✔️	✔️	GH-107347
TextLine
Method draw adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method draw_outline adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
TextParagraph
Method draw adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method draw_dropcap adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method draw_dropcap_outline adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method draw_line adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method draw_line_outline adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method draw_outline adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
TextServer
Method font_draw_glyph adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method font_draw_glyph_outline adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method shaped_text_draw adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
Method shaped_text_draw_outline adds a new oversampling optional parameter	✔️	✔️	✔️	GH-104872
TreeItem
Method add_button adds a new alt_text optional parameter	✔️	✔️	✔️	GH-76829
TextServerExtension
Method _font_draw_glyph adds a new oversampling optional parameter	❌	❌	❌	GH-104872
Method _font_draw_glyph_outline adds a new oversampling optional parameter	❌	❌	❌	GH-104872
Method _shaped_text_draw adds a new oversampling optional parameter	❌	❌	❌	GH-104872
Method _shaped_text_draw_outline adds a new oversampling optional parameter	❌	❌	❌	GH-104872

Realidade Aumentada (XR)

Mudança	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduzido
OpenXRAPIExtension
Method register_composition_layer_provider changes extension parameter type from OpenXRExtensionWrapperExtension to OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
Method register_projection_views_extension changes extension parameter type from OpenXRExtensionWrapperExtension to OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
Method unregister_composition_layer_provider changes extension parameter type from OpenXRExtensionWrapperExtension to OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
Method unregister_projection_views_extension changes extension parameter type from OpenXRExtensionWrapperExtension to OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
OpenXRBindingModifierEditor
O tipo OpenXRBindingModifierEditor mudou o tipo de API de Core para Editor	❌	❌	❌	GH-103869
OpenXRInteractionProfileEditor
O tipo OpenXRInteractionProfileEditor mudou o tipo de API de Core para Editor	❌	❌	❌	GH-103869
OpenXRInteractionProfileEditorBase
O tipo OpenXRInteractionProfileEditor mudou o tipo de API de Core para Editor	❌	❌	❌	GH-103869

Nota

As classes OpenXRBindingModifierEditor, OpenXRInteractionProfileEditor e OpenXRInteractionProfileEditorBase estão disponíveis apenas no editor. Usá-las fora do editor resultará em um erro de compilação.

Em C#, isso significa que os tipos são movidos do assembly GodotSharp para o assembly GodotSharpEditor. Certifique-se de envolver o código que usa esses tipos em um bloco #if TOOLS para garantir que eles não sejam incluídos em um jogo exportado.

Essa mudança também foi aplicada na versão 4.4.1.

Plugins do editor

Mudança	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduzido
EditorExportPlatform
Method get_forced_export_files adds a new preset optional parameter	✔️	✔️	✔️	GH-71542
EditorUndoRedoManager
Method create_action adds a new mark_unsaved optional parameter	✔️	✔️	✔️	GH-106121
EditorExportPlatformExtension
Method _get_option_icon changes return type from ImageTexture to Texture2D	✔️	❌	❌	GH-108825

Behavior changes

In 4.5, some behavior changes have been introduced, which might require you to adjust your project.

TileMapLayer

TileMapLayer.get_coords_for_body_rid() retornará valores diferentes na versão 4.5 em relação à versão 4.4, já que a divisão em chunks físicos do TileMapLayer é ativada por padrão. Valores maiores de TileMapLayer.physics_quadrant_size farão esta função menos precisa. Para obter as coordenadas exatas da célula como na 4.4 e versões anteriores, é preciso definir TileMapLayer.physics_quadrant_size para 1, o que desativa a divisão em chunks físicos.

Importação de modelo 3D

Uma correção foi feita nos importadores de modelos 3D para lidar corretamente com nós que não sejam juntas dentro de uma hierarquia de esqueleto (GH-104184). Para preservar a compatibilidade, o comportamento padrão é importar arquivos existentes com o mesmo comportamento de antes (GH-107352). Novos arquivos .gltf, .glb, .blend e .fbx (sem um arquivo .import correspondente) serão importados com o novo comportamento. No entanto, para arquivos existentes, se você quiser usar o novo comportamento, deve alterar a opção "Naming Version" na parte inferior do painel Import:

Componentes Principais

Nota

O método Resource.duplicate(true) <class_Resource_method_duplicate> (que realiza duplicação profunda) agora duplica apenas os recursos internos ao arquivo de recurso em que é chamado. Na versão 4.4, ele duplicava tudo, incluindo recursos externos. Se você estava realizando uma duplicação profunda de um recurso que continha referências a outros recursos externos, esses recursos externos não serão mais duplicados. Você deve chamar Resource.duplicate_deep(DEEP_DUPLICATE_ALL) <class_Resource_method_duplicate_deep> para manter o comportamento anterior.

Nota

O método ProjectSettings.add_property_info() agora exibe um aviso quando o parâmetro do dicionário contém chaves ausentes ou inválidas. Mais importante ainda, agora ele avisa quando uma chave usage é passada, pois essa chave não é utilizada. Isso também ocorria antes da versão 4.5, mas era ignorado silenciosamente. Como lembrete, para definir as informações de uso da propriedade corretamente, você deve usar os métodos ProjectSettings.set_as_basic(), ProjectSettings.set_restart_if_changed() ou ProjectSettings.set_as_internal().

Nota

Em C#, StringExtensions.PathJoin agora evita adicionar um separador de caminho extra quando a string original está vazia, ou quando o caminho anexado começa com um separador de caminho (GH-105281).

Nota

Em C#, StringExtensions.GetExtension agora retorna uma string vazia em vez da string original quando a string original não contém uma extensão (GH-108041).

Nota

Em C#, o construtor Quaternion(Vector3, Vector3) agora cria corretamente um quatérnion representando o arco mais curto entre os dois vetores de entrada. Anteriormente, ele retornava valores incorretos para certas entradas (GH-107618).

Navegação

Nota

Por padrão, as regiões em um mapa do NavigationServer agora são atualizadas de forma assíncrona usando threads para melhorar o desempenho. Isso pode causar atrasos adicionais na atualização devido à sincronização de threads. A atualização assíncrona de regiões pode ser ativada ou desativada com a configuração de projeto navigation/world/region_use_async_iterations.

Nota

A fusão de navmeshes no NavigationServer mudou a ordem de processamento. As regiões agora mesclam e cache navmeshes internos primeiro, então as bordas livres restantes são mescladas pelo mapa de navegação. Se um projeto tivesse erros de sincronização de mapa de navegação antes, agora poderia ter deslocado bordas afetadas, tornando erros já existentes em um layout mais perceptível na procura de caminho(pathfinding). A configuração do projeto navigation/2d_or_3d/merge_rasterizer_cell_scale pode ser definida como um valor menor para aumentar o detalhe de rasterização de grade(com 0.01 sendo o menor tamanho da célula possível). Se os erros de mesclagem de borda ainda persistirem com o menor valor de escala de rasterização possível, o erro pode ser causado pela sobreposição: dois navmeshes são empilhados em cima um do outro, causando conflito de geometria.

Física

Nota

Quando a engine de física 3D está configurado para Jolt Physics, agora você sempre terá sobreposições entre Area3D e corpos estáticos sendo relatadas por padrão, pois a configuração de projeto physics/jolt_physics_3d/simulation/areas_detect_static_bodies foi removida (GH-105746). Se você ainda quiser que essas sobreposições sejam ignoradas, será necessário alterar a máscara de colisão ou a camada do Area3D ou do corpo estático.

Text

Nota

Em GDScript, as chamadas para as funções RichTextLabel::add_image e RichTextLabel::update_image continuarão a funcionar, mas o argumento size_in_percent agora será usado como o valor para width_in_percent e height_in_percent terá como padrão false (GH-107347). Para restaurar o comportamento anterior, você pode definir explicitamente height_in_percent para o mesmo valor que você estava passando como size_in_percent.