Upgrading from Godot 4.0 to Godot 4.1¶
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.
Breaking changes¶
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 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.
Core¶
Change |
GDScript Compatible |
C# Binary Compatible |
C# Source Compatible |
Introduced |
---|---|---|---|---|
Basis |
||||
Method |
✔️ |
✔️ |
✔️ |
|
Object |
||||
Method |
✔️ |
❌ |
❌ |
|
Transform3D |
||||
Method |
✔️ |
✔️ |
✔️ |
|
UndoRedo |
||||
Method |
✔️ |
✔️ |
✔️ |
|
WorkerThreadPool |
||||
Method |
✔️ |
❌ |
✔️ |
Animation¶
Change |
GDScript Compatible |
C# Binary Compatible |
C# Source Compatible |
Introduced |
---|---|---|---|---|
AnimationNode |
||||
Method |
❌ |
❌ |
❌ |
|
Method |
✔️ |
✔️ |
✔️ |
|
Method |
✔️ |
✔️ |
✔️ |
|
AnimationNodeStateMachinePlayback |
||||
Method |
✔️ |
❌ |
❌ |
2D nodes¶
Change |
GDScript Compatible |
C# Binary Compatible |
C# Source Compatible |
Introduced |
---|---|---|---|---|
PathFollow2D |
||||
Property |
❌ |
❌ |
❌ |
3D nodes¶
Change |
GDScript Compatible |
C# Binary Compatible |
C# Source Compatible |
Introduced |
---|---|---|---|---|
Geometry3D |
||||
Method |
✔️ |
✔️ |
❌ |
|
MeshInstance3D |
||||
Method |
✔️ |
✔️ |
✔️ |
|
Node3D |
||||
Method |
✔️ |
✔️ |
✔️ |
|
Method |
✔️ |
✔️ |
✔️ |
GUI nodes¶
Change |
GDScript Compatible |
C# Binary Compatible |
C# Source Compatible |
Introduced |
---|---|---|---|---|
CodeEdit |
||||
Method |
✔️ |
✔️ |
✔️ |
|
RichTextLabel |
||||
Method |
✔️ |
✔️ |
✔️ |
|
Method |
✔️ |
✔️ |
✔️ |
|
Method |
✔️ |
✔️ |
✔️ |
|
Tree |
||||
Method |
✔️ |
✔️ |
✔️ |
Physics¶
Change |
GDScript Compatible |
C# Binary Compatible |
C# Source Compatible |
Introduced |
---|---|---|---|---|
Area2D |
||||
Property |
❌ |
❌ |
❌ |
|
Area3D |
||||
Property |
❌ |
❌ |
❌ |
|
PhysicsDirectSpaceState2D |
||||
Method |
❌ |
❌ |
❌ |
|
PhysicsDirectSpaceState3D |
||||
Method |
❌ |
❌ |
❌ |
Rendering¶
Change |
GDScript Compatible |
C# Binary Compatible |
C# Source Compatible |
Introduced |
---|---|---|---|---|
RDShaderFile |
||||
Method |
✔️ |
❌ |
❌ |
|
RenderingDevice |
||||
Method |
✔️ |
✔️ |
❌ |
|
RenderingServer |
||||
Method |
✔️ |
❌ |
❌ |
|
SurfaceTool |
||||
Method |
✔️ |
✔️ |
❌ |
Networking¶
Change |
GDScript Compatible |
C# Binary Compatible |
C# Source Compatible |
Introduced |
---|---|---|---|---|
WebRTCPeerConnectionExtension |
||||
Method |
✔️ |
❌ |
✔️ |
Editor plugins¶
Change |
GDScript Compatible |
C# Binary Compatible |
C# Source Compatible |
Introduced |
---|---|---|---|---|
AnimationTrackEditPlugin |
||||
Type |
❌ |
❌ |
❌ |
|
EditorInterface |
||||
Type |
✔️ |
❌ |
❌ |
|
Method |
✔️ |
❌ |
❌ |
|
Method |
✔️ |
❌ |
❌ |
|
EditorResourcePreviewGenerator |
||||
Method |
❌ |
❌ |
❌ |
|
Method |
❌ |
❌ |
❌ |
|
EditorUndoRedoManager |
||||
Method |
✔️ |
✔️ |
✔️ |
Behavior changes¶
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, |
|
Multiple layered |
|
Viewport |
|
|
Updating your GDExtension for 4.1¶
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_interface
toGDExtensionInterfaceGetProcAddress p_get_proc_address
The constructor for the init_obj variable now receives
p_get_proc_address
as 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.1
This lets Godot know that your GDExtension has been updated and is safe to load in Godot 4.1.