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

Change	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduced
JSONRPC
Method set_scope replaced by set_method	❌	❌	❌	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

Change	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduced
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
RenderingDevice
Method texture_create_from_extension adds a new mipmaps optional parameter	✔️	✔️	✔️	GH-105570
RenderingServer
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

Change	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduced
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

Change	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduced
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
RichTextLabel
Method add_image adds a new alt_text optional parameter	✔️	✔️	✔️	GH-76829
O parâmetro size_in_percent do método add_image foi substituído por width_in_percent e height_in_percent.	✔️	✔️	✔️	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

XR

Change	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduced
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

Change	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduced
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() will return different values in 4.5 compared to 4.4, as TileMapLayer physics chunking is enabled by default. Higher values of TileMapLayer.physics_quadrant_size will make this function less precise. To get the exact cell coordinates like in 4.4 and prior versions, you need to set TileMapLayer.physics_quadrant_size to 1, which disables physics chunking.

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

Resource.duplicate(true) (which performs deep duplication) now only duplicates resources internal to the resource file it's called on. In 4.4, this duplicated everything instead, including external resources. If you were deep-duplicating a resource that contained references to other external resources, those external resources aren't duplicated anymore. You must call Resource.duplicate_deep(RESOURCE_DEEP_DUPLICATE_ALL) instead to keep the old behavior.

Nota

ProjectSettings.add_property_info() now prints a warning when the dictionary parameter has missing keys or invalid keys. Most importantly, it will now warn when a usage key is passed, as this key is not used. This was also the case before 4.5, but it was silently ignored instead. As a reminder, to set property usage information correctly, you must use ProjectSettings.set_as_basic(), ProjectSettings.set_restart_if_changed(), or ProjectSettings.set_as_internal() instead.

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

By default, the regions in a NavigationServer map now update asynchronously using threads to improve performance. This can cause additional delay in the update due to thread synchronisation. The asynchronous region update can be toggled with the navigation/world/region_use_async_iterations project setting.

Nota

The merging of navmeshes in the NavigationServer has changed processing order. Regions now merge and cache internal navmeshes first, then the remaining free edges are merged by the navigation map. If a project had navigation map synchronisation errors before, it might now have shifted affected edges, making already existing errors in a layout more noticeable in the pathfinding. The navigation/2d_or_3d/merge_rasterizer_cell_scale project setting can be set to a lower value to increase the detail of the rasterization grid (with 0.01 being the smallest cell size possible). If edge merge errors still persist with the lowest possible rasterization scale value, the error may be caused by overlap: two navmeshes are stacked on top of each other, causing geometry conflict.

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.