For most games and apps made with 4.0, it should be relatively safe to migrate to 4.1. This page intends to cover everything you need to pay attention to when migrating your project.
If you are migrating from 4.0 to 4.1, the breaking changes listed here might affect you. Changes are grouped by areas/systems.
Warning
The GDExtension API completely breaks compatibility in 4.1, so it's not included in the table below. See the updating_your_gdextension_for_godot_4_1 section for more information.
This article indicates whether each breaking change affects GDScript and whether the C# breaking change is binary compatible or source compatible:
- Binary compatible - Existing binaries will load and execute successfully without recompilation, and the run-time behavior won't change.
- Source compatible - Source code will compile successfully without changes when upgrading Godot.
| Change | GDScript Compatible | C# Binary Compatible | C# Source Compatible | Introduced |
|---|---|---|---|---|
| Basis | ||||
Method |
|
|
|
|
Method |
|
|
❌| `G |
H-76418`_ |
Method |
|
|
|
|
Method |
|
|
|
|
Method wait_for_task_completion changes return type from void to Error |
✔️ (This API does not break compatibility.) |
❌ (This API breaks compatibility.) | |
✔️| ` | GH-77143`_ |
| Change | GDScript Compatible | C# Binary Compatible | C# Source Compatible | Introduced |
|---|---|---|---|---|
| AnimationNode | ||||
Method _process adds a new test_only parameter |
❌ (This API breaks compatibility.) | |
❌| |❌ | `GH |
-75759`_ |
Method blend_input adds a new test_only optional parameter |
✔️ (This API does not break compatibility.) |
✔️ (This API does not break compatibility. A compatibility method was added.) |
✔️ (This API does not break compatibility.) |
GH-75759 |
Method |
|
|
|
|
Method get_travel_path changes return type from PackedStringArray to Array[StringName] |
✔️ (This API does not break compatibility.) |
❌ (This API breaks compatibility.) | |
❌| `G | H-76418`_ |
| Change | GDScript Compatible | C# Binary Compatible | C# Source Compatible | Introduced |
|---|---|---|---|---|
| PathFollow2D | ||||
Property lookahead removed |
❌ (This API breaks compatibility.) | |
❌| |❌ | `GH |
-72842`_ |
| Change | GDScript Compatible | C# Binary Compatible | C# Source Compatible | Introduced |
|---|---|---|---|---|
| Geometry3D | ||||
Method |
|
|
|
GH-76418`_ |
Method |
|
|
|
|
Method look_at adds a new use_model_front optional parameter |
✔️ (This API does not break compatibility.) |
✔️ (This API does not break compatibility. A compatibility method was added.) |
✔️ (This API does not break compatibility.) |
GH-76082 |
Method look_at_from_position adds a new use_model_front optional parameter |
✔️ (This API does not break compatibility.) |
✔️ (This API does not break compatibility. A compatibility method was added.) |
✔️ (This API does not break compatibility.) |
GH-76082 |
| Change | GDScript Compatible | C# Binary Compatible | C# Source Compatible | Introduced |
|---|---|---|---|---|
| CodeEdit | ||||
Method |
|
|
|
|
Method push_list adds a new bullet optional parameter |
✔️ (This API does not break compatibility.) |
✔️ (This API does not break compatibility. A compatibility method was added.) |
✔️ (This API does not break compatibility.) |
GH-75017 |
Method push_paragraph adds a new justification_flags optional parameter |
✔️ (This API does not break compatibility.) |
✔️ (This API does not break compatibility. A compatibility method was added.) |
✔️ (This API does not break compatibility.) |
GH-75250 |
Method |
|
|
|
|
Method edit_selected adds a new force_edit optional parameter |
✔️ (This API does not break compatibility.) |
✔️ (This API does not break compatibility. A compatibility method was added.) |
✔️ (This API does not break compatibility.) |
GH-76794 |
| Change | GDScript Compatible | C# Binary Compatible | C# Source Compatible | Introduced |
|---|---|---|---|---|
| Area2D | ||||
Property |
|
❌| |❌ |
`GH |
-72749`_ |
Property |
|
❌| |❌ |
`GH |
-72749`_ |
Method |
|
❌| |❌ |
`GH |
-75260`_ |
Method collide_shape changes return type from Array[PackedVector3Array] to Array[Vector3] |
❌ (This API breaks compatibility.) | |
❌| |❌ | `GH |
-75260`_ |
| Change | GDScript Compatible | C# Binary Compatible | C# Source Compatible | Introduced |
|---|---|---|---|---|
| RDShaderFile | ||||
Method |
|
|
❌| `G |
H-76418`_ |
Method |
|
|
|
GH-76418`_ |
Method |
|
|
❌| `G |
H-76418`_ |
Method add_triangle_fan changes tangents parameter type from untyped Array to Array[Plane] |
✔️ (This API does not break compatibility.) |
✔️ (This API does not break compatibility. A compatibility method was added.) |
❌ (This API breaks compatibility.) ` |
GH-76418`_ |
| Change | GDScript Compatible | C# Binary Compatible | C# Source Compatible | Introduced |
|---|---|---|---|---|
| NavigationAgent2D | ||||
Method set_velocity replaced with velocity property |
✔️ (This API does not break compatibility.) |
❌ (This API breaks compatibility.) | |
❌| `G | H-69988`_ |
Property |
|
❌| |❌ |
`GH |
-69988`_ |
Property agent_height_offset renamed to path_height_offset |
❌ (This API breaks compatibility.) | |
❌| |❌ | `GH |
-69988`_ |
Property ignore_y removed |
❌ (This API breaks compatibility.) | |
❌| |❌ | `GH |
-69988`_ |
Method set_velocity replaced with velocity property |
✔️ (This API does not break compatibility.) |
❌ (This API breaks compatibility.) | |
❌| `G | H-69988`_ |
Property |
|
❌| |❌ |
`GH |
-69988`_ |
Property estimate_radius removed |
❌ (This API breaks compatibility.) | |
❌| |❌ | `GH |
-69988`_ |
Method |
|
❌| |❌ |
`GH |
-69988`_ |
Property estimate_radius removed |
❌ (This API breaks compatibility.) | |
❌| |❌ | `GH |
-69988`_ |
Method |
|
❌| |❌ |
`GH |
-69988`_ |
Method agent_set_callback renamed to agent_set_avoidance_callback |
❌ (This API breaks compatibility.) | |
❌| |❌ | `GH |
-69988`_ |
Method agent_set_target_velocity removed |
❌ (This API breaks compatibility.) | |
❌| |❌ | `GH |
-69988`_ |
Method |
|
❌| |❌ |
`GH |
-69988`_ |
Method agent_set_callback renamed to agent_set_avoidance_callback |
❌ (This API breaks compatibility.) | |
❌| |❌ | `GH |
-69988`_ |
Method agent_set_target_velocity removed |
❌ (This API breaks compatibility.) | |
❌| |❌ | `GH |
-69988`_ |
Method agent_set_time_horizon split into agent_set_time_horizon_agents and agent_set_time_horizon_obstacles |
❌ (This API breaks compatibility.) | |
❌| |❌ | `GH |
-69988`_ |
| Change | GDScript Compatible | C# Binary Compatible | C# Source Compatible | Introduced |
|---|---|---|---|---|
| WebRTCPeerConnectionExtension | ||||
Method _create_data_channel changes return type from Object to WebRTCDataChannel |
✔️ (This API does not break compatibility.) |
❌ (This API breaks compatibility.) | |
✔️| ` | GH-78237`_ |
| Change | GDScript Compatible | C# Binary Compatible | C# Source Compatible | Introduced |
|---|---|---|---|---|
| AnimationTrackEditPlugin | ||||
Type |
|
❌| |❌ |
`GH |
-76413`_ |
Type EditorInterface changes inheritance from Node to Object |
✔️ (This API does not break compatibility.) |
❌ (This API breaks compatibility.) | |
❌| `G | H-76176`_ |
Method set_movie_maker_enabled replaced with movie_maker_enabled property |
✔️ (This API does not break compatibility.) |
❌ (This API breaks compatibility.) | |
❌| `G | H-76176`_ |
Method |
|
|
❌| `G |
H-76176`_ |
Method _generate adds a new metadata parameter |
❌ (This API breaks compatibility.) | |
❌| |❌ | `GH |
-64628`_ |
Method |
|
❌| |❌ |
`GH |
-64628`_ |
Method create_action adds a new backward_undo_ops optional parameter |
✔️ (This API does not break compatibility.) |
✔️ (This API does not break compatibility. A compatibility method was added.) |
✔️ (This API does not break compatibility.) |
GH-76688 |
In 4.1 some behavior changes have been introduced, which might require you to adjust your project.
| Change | Introduced |
|---|---|
| SubViewportContainer | |
When input events should reach SubViewports and their children, SubViewportContainer.mouse_filter now needs to be MOUSE_FILTER_STOP or MOUSE_FILTER_PASS. See GH-79271 for details. |
GH-57894 |
Multiple layered |
|
Viewport nodes, that have Physics Picking enabled, now automatically set InputEvents as handled. See GH-79897 for workarounds. |
GH-77595 |
GDExtension is still in beta. Until it's marked as stable, compatibility may break when upgrading to a new minor version of Godot.
In order to fix a serious bug, in Godot 4.1 we had to break binary compatibility in a big way and source compatibility in a small way.
This means that GDExtensions made for Godot 4.0 will need to be recompiled for Godot 4.1 (using the 4.1 branch of godot-cpp), with a small change to their source code.
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();
}However, for Godot 4.1, it should look like:
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:
- The first argument changes from
const GDExtensionInterface *p_interfacetoGDExtensionInterfaceGetProcAddress p_get_proc_address - The constructor for the init_obj variable now receives
p_get_proc_addressas its first parameter
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.1This lets Godot know that your GDExtension has been updated and is safe to load in Godot 4.1.