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_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 runtime behavior won't change.
Source compatible - Source code will compile successfully without changes when upgrading Godot.

Core

Animation

2D nodes

3D nodes

GUI nodes

Physics

Rendering

======================================================================================================================== =================== ==================== ==================== =========== Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced ======================================================================================================================== =================== ==================== ==================== =========== NavigationAgent2D Method set_velocity replaced with velocity property |✔️| |❌| |❌| GH-69988 Property time_horizon split into time_horizon_agents and time_horizon_obstacles |❌| |❌| |❌| GH-69988 NavigationAgent3D Property agent_height_offset renamed to path_height_offset |❌| |❌| |❌| GH-69988 Property ignore_y removed |❌| |❌| |❌| GH-69988 Method set_velocity replaced with velocity property |✔️| |❌| |❌| GH-69988 Property time_horizon split into time_horizon_agents and time_horizon_obstacles |❌| |❌| |❌| GH-69988 NavigationObstacle2D Property estimate_radius removed |❌| |❌| |❌| GH-69988 Method get_rid renamed to get_agent_rid |❌| |❌| |❌| GH-69988 NavigationObstacle3D Property estimate_radius removed |❌| |❌| |❌| GH-69988 Method get_rid renamed to get_agent_rid |❌| |❌| |❌| GH-69988 NavigationServer2D Method agent_set_callback renamed to agent_set_avoidance_callback |❌| |❌| |❌| GH-69988 Method agent_set_target_velocity removed |❌| |❌| |❌| GH-69988 Method agent_set_time_horizon split into agent_set_time_horizon_agents and agent_set_time_horizon_obstacles |❌| |❌| |❌| GH-69988 NavigationServer3D Method agent_set_callback renamed to agent_set_avoidance_callback |❌| |❌| |❌| GH-69988 Method agent_set_target_velocity removed |❌| |❌| |❌| GH-69988 Method agent_set_time_horizon split into agent_set_time_horizon_agents and agent_set_time_horizon_obstacles |❌| |❌| |❌| GH-69988 ======================================================================================================================== =================== ==================== ==================== ===========

Networking

Editor plugins

Behavior changes

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

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 to GDExtensionInterfaceGetProcAddress 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.

Breaking changes​

Core​

Animation​

2D nodes​

3D nodes​

GUI nodes​

Physics​

Rendering​

Navigation​

Networking​

Editor plugins​

Behavior changes​

Updating your GDExtension for 4.1​