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 do Godot 4.4 para o Godot 4.5

Para a maioria dos jogos e aplicativos feitos com a versão 4.4, deve ser relativamente seguro migrar para a 4.5. Esta página tem como objetivo cobrir tudo o que você precisa observar ao migrar seu projeto.

Alterações incompatíveis

Se você estiver migrando da 4.4 para a 4.5, as mudanças incompatíveis listadas aqui podem afetá-lo. As alterações estão agrupadas por áreas/sistemas.

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:

• Compatível em nível binário - Binários existentes serão carregados e executados com sucesso sem recompilação, e o comportamento em tempo de execução não será alterado.

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

Componentes Principais

Mudança	Compatível com GDScript	Compatível com C# Binário	Compatível com fonte C#	Introduzido
JSONRPC
Método set_scope substituído por set_method	❌	❌	❌	GH-104890
Node
Método get_rpc_config renomeado para get_node_rpc_config	❌	✔️	✔️	GH-106848
Método set_name altera o tipo do parâmetro name de String para StringName	✔️	✔️	✔️	GH-76560

Renderização

Mudança	Compatível com GDScript	Compatível com C# Binário	Compatível com fonte C#	Introduzido
DisplayServer
Método file_dialog_show adiciona um novo parâmetro opcional parent_window_id	✔️	✔️	✔️	GH-98194
Método file_dialog_with_options_show adiciona um novo parâmetro opcional parent_window_id	✔️	✔️	✔️	GH-98194
Dispositivo de Renderização
Método texture_create_from_extension adiciona um novo parâmetro opcional mipmaps	✔️	✔️	✔️	GH-105570
Dispositivo de Servidor
Método instance_reset_physics_interpolation removido	❌	✔️	✔️	GH-104269
Método instance_set_interpolated removido	❌	✔️	✔️	GH-104269

Nota

No C#, o enum RenderingDevice.Features quebra a compatibilidade por causa da maneira como o gerador de vínculos (bindings generator) detecta o prefixo do enum. Novos membros foram adicionados ao enum em GH-103941, o que fez com que o membro do enum Address fosse renomeado para BufferDeviceAddress.

GLTF

Mudança	Compatível com GDScript	Compatível com C# Binário	Compatível com fonte C#	Introduzido
GLTFAccessor
Propriedade byte_offset altera os metadados do tipo de int32 para int64	✔️	❌	❌	GH-106220
Propriedade component_type altera o tipo de int para GLTFAccessor::GLTFComponentType	✔️	❌	❌	GH-106220
Propriedade count altera os metadados do tipo de int32 para int64	✔️	❌	❌	GH-106220
Propriedade sparse_count altera os metadados do tipo de int32 para int64	✔️	❌	❌	GH-106220
Propriedade sparse_indices_byte_offset altera os metadados do tipo de int32 para int64	✔️	❌	❌	GH-106220
Propriedade sparse_indices_component_type altera o tipo de int para GLTFAccessor::GLTFComponentType	✔️	❌	❌	GH-106220
Propriedade sparse_values_byte_offset altera os metadados do tipo de int32 para int64	✔️	❌	❌	GH-106220
GLTFBufferView
Propriedade byte_length altera os metadados do tipo de int32 para int64	✔️	❌	❌	GH-106220
Propriedade byte_offset altera os metadados do tipo de int32 para int64	✔️	❌	❌	GH-106220
Propriedade byte_stride altera os metadados do tipo de int32 para 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).

Texto

Mudança	Compatível com GDScript	Compatível com C# Binário	Compatível com fonte C#	Introduzido
CanvasItem
Método draw_char adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método draw_char_outline adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método draw_multiline_string adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método draw_multiline_string_outline adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método draw_string adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método draw_string_outline adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Fonte
Método draw_char adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método draw_char_outline adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método draw_multiline_string adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método draw_multiline_string_outline adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método draw_string adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método draw_string_outline adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Texto Formatado
Método add_image adiciona um novo parâmetro opcional alt_text	✔️	✔️	✔️	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
Método push_strikethrough adiciona o parâmetro opcional color	✔️	✔️	✔️	GH-106300
Método push_table adiciona um novo parâmetro opcional name	✔️	✔️	✔️	GH-76829
Método push_underline adiciona o parâmetro opcional color	✔️	✔️	✔️	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
Método draw adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método draw_outline adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
TextParagraph
Método draw adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método draw_dropcap adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método draw_dropcap_outline adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método draw_line adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método draw_line_outline adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método draw_outline adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
TextServer
Método font_draw_glyph adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método font_draw_glyph_outline adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método shaped_text_draw adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
Método shaped_text_draw_outline adiciona um novo parâmetro opcional oversampling	✔️	✔️	✔️	GH-104872
TreeItem
Método add_button adiciona um novo parâmetro opcional alt_text	✔️	✔️	✔️	GH-76829
TextServerExtension
Método _font_draw_glyph adiciona um novo parâmetro opcional oversampling	❌	❌	❌	GH-104872
Método _font_draw_glyph_outline adiciona um novo parâmetro opcional oversampling	❌	❌	❌	GH-104872
Método _shaped_text_draw adiciona um novo parâmetro opcional oversampling	❌	❌	❌	GH-104872
Método _shaped_text_draw_outline adiciona um novo parâmetro opcional oversampling	❌	❌	❌	GH-104872

Realidade Aumentada (XR)

Mudança	Compatível com GDScript	Compatível com C# Binário	Compatível com fonte C#	Introduzido
OpenXRAPIExtension
Método register_composition_layer_provider altera o tipo do parâmetro extension de OpenXRExtensionWrapperExtension para OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
Método register_projection_views_extension altera o tipo do parâmetro extension de OpenXRExtensionWrapperExtension para OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
Método unregister_composition_layer_provider altera o tipo do parâmetro extension de OpenXRExtensionWrapperExtension para OpenXRExtensionWrapper	✔️	✔️	✔️	GH-104087
Método unregister_projection_views_extension altera o tipo do parâmetro extension de OpenXRExtensionWrapperExtension para 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	Compatível com GDScript	Compatível com C# Binário	Compatível com fonte C#	Introduzido
EditorExportPlatform
Método get_forced_export_files adiciona um novo parâmetro opcional preset	✔️	✔️	✔️	GH-71542
EditorUndoRedoManager
Método create_action adiciona um novo parâmetro opcional mark_unsaved	✔️	✔️	✔️	GH-106121
EditorExportPlatformExtension
Método _get_option_icon altera o tipo de retorno de ImageTexture para Texture2D	✔️	❌	❌	GH-108825

Mudanças de comportamento

No 4.5, algumas mudanças de comportamento foram introduzidas, o que pode exigir ajustes no seu projeto.

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

Resource.duplicate(true) (que realiza uma duplicação profunda) agora duplica apenas os recursos internos ao arquivo de recurso no qual é chamado. Na versão 4.4, ele duplicava tudo, incluindo recursos externos. Se você estivesse 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. Em vez disso, você deve chamar Resource.duplicate_deep(DEEP_DUPLICATE_ALL) para manter o comportamento anterior.

Nota

ProjectSettings.add_property_info() agora exibe um aviso quando o parâmetro de dicionário possui chaves ausentes ou inválidas. Mais importante ainda, ele agora avisará quando uma chave usage for passada, pois essa chave não é utilizada. Esse também era o comportamento antes da versão 4.5, mas ela era ignorada silenciosamente. Como lembrete, para definir corretamente as informações de uso da propriedade, você deve usar 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

By default, the regions in a NavigationServer map update asynchronously using threads to improve performance. This can cause additional delay in the update due to thread synchronization. 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 synchronization 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.

Texto

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.