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.

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.

警告

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 looking_at adds a new use_model_front optional parameter

✔️

✔️

✔️

GH-76082

Object

Method get_meta_list changes return type from PackedStringArray to Array[StringName]

✔️

GH-76418

Transform3D

Method looking_at adds a new use_model_front optional parameter

✔️

✔️

✔️

GH-76082

UndoRedo

Method create_action adds a new backward_undo_ops optional parameter

✔️

✔️

✔️

GH-76688

WorkerThreadPool

Method wait_for_task_completion changes return type from void to Error

✔️

✔️

GH-77143

动画

Change

GDScript Compatible

C# Binary Compatible

C# Source Compatible

Introduced

AnimationNode

Method _process adds a new test_only parameter

GH-75759

Method blend_input adds a new test_only optional parameter

✔️

✔️

✔️

GH-75759

Method blend_node adds a new test_only optional parameter

✔️

✔️

✔️

GH-75759

AnimationNodeStateMachinePlayback

Method get_travel_path changes return type from PackedStringArray to Array[StringName]

✔️

GH-76418

2D nodes

Change

GDScript Compatible

C# Binary Compatible

C# Source Compatible

Introduced

PathFollow2D

Property lookahead removed

GH-72842

3D nodes

Change

GDScript Compatible

C# Binary Compatible

C# Source Compatible

Introduced

Geometry3D

Method segment_intersects_convex changes planes parameter type from untyped Array to Array[Plane]

✔️

✔️

GH-76418

MeshInstance3D

Method create_multiple_convex_collisions adds a new settings optional parameter

✔️

✔️

✔️

GH-72152

Node3D

Method look_at adds a new use_model_front optional parameter

✔️

✔️

✔️

GH-76082

Method look_at_from_position adds a new use_model_front optional parameter

✔️

✔️

✔️

GH-76082

GUI nodes

Change

GDScript Compatible

C# Binary Compatible

C# Source Compatible

Introduced

CodeEdit

Method add_code_completion_option adds a new location optional parameter

✔️

✔️

✔️

GH-75746

RichTextLabel

Method push_list adds a new bullet optional parameter

✔️

✔️

✔️

GH-75017

Method push_paragraph adds a new justification_flags optional parameter

✔️

✔️

✔️

GH-75250

Method push_paragraph adds a new tab_stops optional parameter

✔️

✔️

✔️

GH-76401

Tree

Method edit_selected adds a new force_edit optional parameter

✔️

✔️

✔️

GH-76794

物理学

Change

GDScript Compatible

C# Binary Compatible

C# Source Compatible

Introduced

Area2D

Property priority changes type from float to int

GH-72749

Area3D

Property priority changes type from float to int

GH-72749

PhysicsDirectSpaceState2D

Method collide_shape changes return type from Array[PackedVector2Array] to Array[Vector2]

GH-75260

PhysicsDirectSpaceState3D

Method collide_shape changes return type from Array[PackedVector3Array] to Array[Vector3]

GH-75260

渲染

Change

GDScript Compatible

C# Binary Compatible

C# Source Compatible

Introduced

RDShaderFile

Method get_version_list changes return type from PackedStringArray to Array[StringName]

✔️

GH-76418

RenderingDevice

Method draw_list_begin changes storage_textures parameter type from untyped Array to Array[RID]

✔️

✔️

GH-76418

RenderingServer

Method global_shader_parameter_get_list changes return type from PackedStringArray to Array[StringName]

✔️

GH-76418

SurfaceTool

Method add_triangle_fan changes tangents parameter type from untyped Array to Array[Plane]

✔️

✔️

GH-76418

网络

Change

GDScript Compatible

C# Binary Compatible

C# Source Compatible

Introduced

WebRTCPeerConnectionExtension

Method _create_data_channel changes return type from Object to WebRTCDataChannel

✔️

✔️

GH-78237

编辑器插件

Change

GDScript Compatible

C# Binary Compatible

C# Source Compatible

Introduced

AnimationTrackEditPlugin

Type AnimationTrackEditPlugin removed

GH-76413

EditorInterface

Type EditorInterface changes inheritance from Node to Object

✔️

GH-76176

Method set_movie_maker_enabled replaced with movie_maker_enabled property

✔️

GH-76176

Method is_movie_maker_enabled replaced with movie_maker_enabled property

✔️

GH-76176

EditorResourcePreviewGenerator

Method _generate adds a new metadata parameter

GH-64628

Method _generate_from_path adds a new metadata parameter

GH-64628

EditorUndoRedoManager

Method create_action adds a new backward_undo_ops optional parameter

✔️

✔️

✔️

GH-76688

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, SubViewportContainer.mouse_filter now needs to be MOUSE_FILTER_STOP or MOUSE_FILTER_PASS. See GH-79271 for details.

GH-57894

Multiple layered SubViewportContainer nodes, that should all receive mouse input events, now need to be replaced by Area2D nodes. See GH-79128 for details.

GH-57894

Viewport

Viewport nodes, that have Physics Picking enabled, now automatically set InputEvents as handled. See GH-79897 for workarounds.

GH-77595

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:

  1. The first argument changes from const GDExtensionInterface *p_interface to GDExtensionInterfaceGetProcAddress p_get_proc_address

  2. 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.