Atualizando do Godot 4.0 para o Godot 4.1

Para a maioria dos jogos e aplicativos feitos com a versão 4.0, deve ser relativamente seguro migrar para a versão 4.1. Esta página tem a intenção de cobrir tudo o que você precisa para prestar atenção ao migrar seu projeto.

Breaking changes

Se você estiver migrando da versão 4.0 para a 4.1, as alterações significativas listadas aqui podem afetá-lo. As alterações são agrupadas por áreas/sistemas.

Aviso

A API GDExtension quebra completamente a compatibilidade na versão 4.1, portanto, não está incluída na tabela abaixo. Consulte a seção Atualizando seu GDExtension para 4.1 para obter mais informaçõ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 com binários - Os binários existentes serão carregados e executados com sucesso sem recompilação, e o comportamento em tempo de execução não mudará.

• 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
Basis
O método looking_at adiciona um novo parâmetro opcional use_model_front	✔️	✔️	✔️	GH-76082
Object
O método get_meta_list altera o tipo de retorno de PackedStringArray para Array[StringName]	✔️	❌	❌	GH-76418
Transform3D
O método looking_at adiciona um novo parâmetro opcional use_model_front	✔️	✔️	✔️	GH-76082
UndoRedo
O método create_action adiciona um novo parâmetro opcional backward_undo_ops	✔️	✔️	✔️	GH-76688
WorkerThreadPool
O método wait_for_task_completion altera o tipo de retorno de void para Error	✔️	❌	✔️	GH-77143

Animação

Change	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduced
AnimationNode
Método _process adiciona um novo parâmetro test_only	❌	❌	❌	GH-75759
Adiciona o novo parâmetro opcional test_only ao método blend_input	✔️	✔️	✔️	GH-75759
Adiciona o novo parâmetro opcional test_only ao método blend_node	✔️	✔️	✔️	GH-75759
AnimationNodeStateMachinePlayback
Alterado o tipo do retorno do método get_travel_path de PackedStringArray para Array[StringName]	✔️	❌	❌	GH-76418

2D nodes

Change	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduced
PathFollow2D
Propriedade lookahead removida	❌	❌	❌	GH-72842

3D nodes

Change	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduced
Geometry3D
Alterado o tipo do parâmetro planes do método segment_intersects_convex de Array não tipado para Array[Plane]	✔️	✔️	❌	GH-76418
MeshInstance3D
Adicionado novo parâmetro opcional settings ao método create_multiple_convex_collisions	✔️	✔️	✔️	GH-72152
Node3D
Adicionado novo parâmetro opcional use_model_front ao método look_at	✔️	✔️	✔️	GH-76082
Adicionado novo parâmetro opcional use_model_front ao método look_at_from_position	✔️	✔️	✔️	GH-76082

GUI nodes

Change	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduced
CodeEdit
Adicionado novo parâmetro opcional location ao método add_code_completion_option	✔️	✔️	✔️	GH-75746
RichTextLabel
Adicionado novo parâmetro opcional bullet ao método push_list	✔️	✔️	✔️	GH-75017
Adicionado novo parâmetro opcional justification_flags ao método push_paragraph	✔️	✔️	✔️	GH-75250
Adicionado novo parâmetro opcional tab_stops ao método push_paragraph	✔️	✔️	✔️	GH-76401
Tree
Adicionado novo parâmetro opcional force_edit ao método edit_selected	✔️	✔️	✔️	GH-76794

Física

Change	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduced
Area2D
A propriedade priority teve o seu tipo alterado de float para int	❌	❌	❌	GH-72749
Area3D
A propriedade priority teve o seu tipo alterado de float para int	❌	❌	❌	GH-72749
PhysicsDirectSpaceState2D
Alterado o tipo do retorno do método collide_shape de Array[PackedVector2Array] para Array[Vector2]	❌	❌	❌	GH-75260
PhysicsDirectSpaceState3D
Alterado o tipo do retorno do método collide_shape de Array[PackedVector3Array] para Array[Vector3]	❌	❌	❌	GH-75260

Renderização

Change	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduced
RDShaderFile
Modificado o tipo de retorno do método get_version_list de PackedStringArray para Array[StringName]	✔️	❌	❌	GH-76418
RenderingDevice
Alterado o tipo do parâmetro storage_textures do método draw_list_begin de Array não tipado para Array[RID]	✔️	✔️	❌	GH-76418
RenderingServer
Modificado o tipo de retorno do método global_shader_parameter_get_list de PackedStringArray para Array[StringName]	✔️	❌	❌	GH-76418
SurfaceTool
Alterado o tipo do parâmetro tangents do método add_triangle_fan de Array não tipado para Array[Plane]	✔️	✔️	❌	GH-76418

Navegação

Change	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduced
NavigationAgent2D
Método set_velocity substituído pela propriedade velocity	✔️	❌	❌	GH-69988
Propriedade time_horizon dividida em time_horizon_agents e time_horizon_obstacles	❌	❌	❌	GH-69988
NavigationAgent3D
Propriedade agent_height_offset renomeada para path_height_offset	❌	❌	❌	GH-69988
Propriedade ignore_y removida	❌	❌	❌	GH-69988
Método set_velocity substituído pela propriedade velocity	✔️	❌	❌	GH-69988
Propriedade time_horizon dividida em time_horizon_agents e time_horizon_obstacles	❌	❌	❌	GH-69988
NavigationObstacle2D
Propriedade estimate_radius removida	❌	❌	❌	GH-69988
Método get_rid renomeado para get_agent_rid	❌	❌	❌	GH-69988
NavigationObstacle3D
Propriedade estimate_radius removida	❌	❌	❌	GH-69988
Método get_rid renomeado para get_agent_rid	❌	❌	❌	GH-69988
NavigationServer2D
Método agent_set_callback renomeado para agent_set_avoidance_callback	❌	❌	❌	GH-69988
Método agent_set_target_velocity removido	❌	❌	❌	GH-69988
Método agent_set_time_horizon dividido em agent_set_time_horizon_agents e agent_set_time_horizon_obstacles	❌	❌	❌	GH-69988
NavigationServer3D
Método agent_set_callback renomeado para agent_set_avoidance_callback	❌	❌	❌	GH-69988
Método agent_set_target_velocity removido	❌	❌	❌	GH-69988
Método agent_set_time_horizon dividido em agent_set_time_horizon_agents e agent_set_time_horizon_obstacles	❌	❌	❌	GH-69988

Trabalho em rede

Change	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduced
WebRTCPeerConnectionExtension
Modificado o tipo de retorno do método _create_data_channel de Object para WebRTCDataChannel	✔️	❌	✔️	GH-78237

Plugins do editor

Change	GDScript Compatible	Compatível com C# Binário	Compatível com fonte C#	Introduced
AnimationTrackEditPlugin
Type AnimationTrackEditPlugin removed	❌	❌	❌	GH-76413
EditorInterface
Alterada a herança do tipo EditorInterface de Node para Object	✔️	❌	❌	GH-76176
Método set_movie_maker_enabled substituído pela propriedade movie_maker_enabled	✔️	❌	❌	GH-76176
Método is_movie_maker_enabled substituído pela propriedade movie_maker_enabled	✔️	❌	❌	GH-76176
EditorResourcePreviewGenerator
Adicionado novo parâmetro metadata ao método _generate	❌	❌	❌	GH-64628
Adicionado novo parâmetro metadata ao método _generate_from_path	❌	❌	❌	GH-64628
EditorUndoRedoManager
O método create_action adiciona um novo parâmetro opcional backward_undo_ops	✔️	✔️	✔️	GH-76688

Behavior changes

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

Change	Introduced
SubViewportContainer
Quando eventos de entrada devem ser reconhecidos pelo SubViewports e seus filhos, SubViewportContainer.mouse_filter agora precisa ser MOUSE_FILTER_STOP ou MOUSE_FILTER_PASS. Consulte GH-79271 para obter detalhes.	GH-57894
Vários nós SubViewportContainer em camadas, que deveriam receber eventos de entrada do mouse, agora precisam ser substituídos por nós Area2D. Veja GH-79128 para mais detalhes.	GH-57894
Viewport
Nós Viewport que têm Physics Picking habilitado agora definem automaticamente os InputEvents como "handled". Veja GH-79897 para soluções alternativas.	GH-77595

Atualizando seu GDExtension para 4.1

Para corrigir um bug sério, no Godot 4.1 tivemos que quebrar a compatibilidade binária de uma forma significativa e a compatibilidade de código-fonte de uma forma pequena.

Isso significa que GDExtensions feito para o Godot 4.0 precisarão ser recompiladas para o Godot 4.1 (usando a ramificação 4.1 do godot-cpp), com uma pequena alteração em seu código-fonte.

In Godot 4.0, your "entry_symbol" function looks something like this:

GDExtensionBool GDE_EXPORT example_library_init(const GDExtensionInterface *p_interface, const GDExtensionClassLibraryPtr p_library, GDExtensionInitialization *r_initialization) {
    godot::GDExtensionBinding::InitObject init_obj(p_interface, p_library, r_initialization);

    init_obj.register_initializer(initialize_example_module);
    init_obj.register_terminator(uninitialize_example_module);
    init_obj.set_minimum_library_initialization_level(MODULE_INITIALIZATION_LEVEL_SCENE);

    return init_obj.init();
}

Entretanto, para o Godot 4.1, deve ficar assim:

GDExtensionBool GDE_EXPORT example_library_init(GDExtensionInterfaceGetProcAddress p_get_proc_address, const GDExtensionClassLibraryPtr p_library, GDExtensionInitialization *r_initialization) {
    godot::GDExtensionBinding::InitObject init_obj(p_get_proc_address, p_library, r_initialization);

    init_obj.register_initializer(initialize_example_module);
    init_obj.register_terminator(uninitialize_example_module);
    init_obj.set_minimum_library_initialization_level(MODULE_INITIALIZATION_LEVEL_SCENE);

    return init_obj.init();
}

There are two small changes:

1. O primeiro argumento muda de const GDExtensionInterface *p_interface para GDExtensionInterfaceGetProcAddress p_get_proc_address

2. O construtor da variável init_obj agora recebe p_get_proc_address como seu primeiro parâmetro

You also need to add an extra compatibility_minimum line to your .gdextension file, so that it looks something like:

[configuration]

entry_symbol = "example_library_init"
compatibility_minimum = 4.1

Isso permite que o Godot saiba que o seu GDExtension foi atualizado e está seguro para carregar no Godot 4.1.