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.

Checking the stable version of the documentation...

Upgrade von Godot 4.0 auf Godot 4.1

Für die meisten Spiele und Anwendungen, die mit 4.0 entwickelt wurden, sollte es relativ sicher sein, auf 4.1 zu migrieren. Diese Seite soll alles abdecken, was Sie bei der Migration Ihres Projekts beachten müssen.

Änderungen, die etwas kaputtmachen können

Wenn Sie von 4.0 auf 4.1 migrieren, könnten Sie von den hier aufgeführten Brüchen betroffen sein. Die Änderungen sind nach Bereichen/Systemen gruppiert.

Warnung

Die GDExtension-API ist in 4.1 nicht mehr kompatibel, daher ist sie in der Tabelle unten nicht enthalten. Siehe den Abschnitt Aktualisieren Ihrer GDExtension für 4.1 für weitere Informationen.

Dieser Artikel gibt an, ob die einzelnen Änderungen GDScript betreffen und ob die C#-Änderung binärkompatibel oder quelltextkompatibel ist:

• Binary compatible - Existing binaries will load and execute successfully without recompilation, and the runtime behavior won't change.

• Quellcodekompatibel - Der Quellcode wird beim Upgrade von Godot ohne Änderungen erfolgreich kompiliert.

Kern

Veränderung	GDScript- kompatibel	C#-binär- kompatibel	C#-quellcode- kompatibel	Eingeführt in
Basis
Methode looking_at fügt einen neuen optionalen Parameter use_model_front hinzu	✔️	✔️	✔️	GH-76082
Object
Methode get_meta_list ändert Rückgabetyp von PackedStringArray auf Array[StringName]	✔️	❌	❌	GH-76418
Transform3D
Methode looking_at fügt einen neuen optionalen Parameter use_model_front hinzu	✔️	✔️	✔️	GH-76082
UndoRedo
Methode create_action fügt einen neuen optionalen Parameter backward_undo_ops hinzu	✔️	✔️	✔️	GH-76688
WorkerThreadPool
Methode wait_for_task_completion ändert Rückgabetyp von void auf Error	✔️	❌	✔️	GH-77143

Animation

Veränderung	GDScript- kompatibel	C#-binär- kompatibel	C#-quellcode- kompatibel	Eingeführt in
AnimationNode
Methode _process fügt einen neuen Parameter test_only hinzu	❌	❌	❌	GH-75759
Methode blend_input fügt einen neuen optionalen Parameter test_only hinzu	✔️	✔️	✔️	GH-75759
Methode blend_node fügt einen neuen optionalen Parameter test_only hinzu	✔️	✔️	✔️	GH-75759
AnimationNodeStateMachinePlayback
Methode get_travel_path ändert Rückgabetyp von PackedStringArray auf Array[StringName]	✔️	❌	❌	GH-76418

2D-Nodes

Veränderung	GDScript- kompatibel	C#-binär- kompatibel	C#-quellcode- kompatibel	Eingeführt in
PathFollow2D
Property lookahead entfernt	❌	❌	❌	GH-72842

3D-Nodes

Veränderung	GDScript- kompatibel	C#-binär- kompatibel	C#-quellcode- kompatibel	Eingeführt in
Geometry3D
Methode segment_intersects_convex ändert den planes-Parametertyp von untypisierten Array auf Array[Plane]	✔️	✔️	❌	GH-76418
MeshInstance3D
Methode create_multiple_convex_collisions fügt einen neuen optionalen Parameter settings hinzu	✔️	✔️	✔️	GH-72152
Node3D
Methode look_at fügt einen neuen optionalen Parameter use_model_front hinzu	✔️	✔️	✔️	GH-76082
Methode look_at_from_position fügt einen neuen optionalen Parameter use_model_front hinzu	✔️	✔️	✔️	GH-76082

GUI-Nodes

Veränderung	GDScript- kompatibel	C#-binär- kompatibel	C#-quellcode- kompatibel	Eingeführt in
CodeEdit
Methode add_code_completion_option fügt einen neuen optionalen Parameter location hinzu	✔️	✔️	✔️	GH-75746
RichTextLabel
Methode push_list fügt einen neuen optionalen Parameter bullet hinzu	✔️	✔️	✔️	GH-75017
Methode push_paragraph fügt einen neuen optionalen Parameter justification_flags hinzu	✔️	✔️	✔️	GH-75250
Methode push_paragraph fügt einen neuen optionalen Parameter tab_stops hinzu	✔️	✔️	✔️	GH-76401
Tree
Methode edit_selected fügt einen neuen optionalen Parameter force_edit hinzu	✔️	✔️	✔️	GH-76794

Physik

Veränderung	GDScript- kompatibel	C#-binär- kompatibel	C#-quellcode- kompatibel	Eingeführt in
Area2D
Property Priorität ändert Typ von float auf int	❌	❌	❌	GH-72749
Area3D
Property Priorität ändert Typ von float auf int	❌	❌	❌	GH-72749
PhysicsDirectSpaceState2D
Methode collide_shape ändert Rückgabetyp von Array[PackedVector2Array] auf Array[Vector2]	❌	❌	❌	GH-75260
PhysicsDirectSpaceState3D
Methode collide_shape ändert Rückgabetyp von Array[PackedVector3Array] auf Array[Vector3]	❌	❌	❌	GH-75260

Rendern

Veränderung	GDScript- kompatibel	C#-binär- kompatibel	C#-quellcode- kompatibel	Eingeführt in
RDShaderFile
Methode get_version_list ändert Rückgabetyp von PackedStringArray auf Array[StringName]	✔️	❌	❌	GH-76418
RenderingDevice
Methode draw_list_begin ändert storage_textures Parametertyp von untypisiertem Array auf Array[RID]	✔️	✔️	❌	GH-76418
RenderingServer
Methode global_shader_parameter_get_list ändert Rückgabetyp von PackedStringArray auf Array[StringName]	✔️	❌	❌	GH-76418
SurfaceTool
Die Methode add_triangle_fan ändert den Typ des Parameters tangents von untypisiertem Array auf Array[Plane]	✔️	✔️	❌	GH-76418

Navigation

Veränderung	GDScript- kompatibel	C#-binär- kompatibel	C#-quellcode- kompatibel	Eingeführt in
NavigationAgent2D
Methode set_velocity ersetzt durch Property velocity	✔️	❌	❌	GH-69988
Property time_horizon aufgeteilt in time_horizon_agents und time_horizon_obstacles	❌	❌	❌	GH-69988
NavigationAgent3D
Property agent_height_offset umbenannt in path_height_offset	❌	❌	❌	GH-69988
Property ignore_y entfernt	❌	❌	❌	GH-69988
Methode set_velocity ersetzt durch Property velocity	✔️	❌	❌	GH-69988
Property time_horizon aufgeteilt in time_horizon_agents und time_horizon_obstacles	❌	❌	❌	GH-69988
NavigationObstacle2D
Property estimate_radius entfernt	❌	❌	❌	GH-69988
Methode get_rid umbenannt in get_agent_rid	❌	❌	❌	GH-69988
NavigationObstacle3D
Property estimate_radius entfernt	❌	❌	❌	GH-69988
Methode get_rid umbenannt in get_agent_rid	❌	❌	❌	GH-69988
NavigationServer2D
Methode agent_set_callback umbenannt in agent_set_avoidance_callback	❌	❌	❌	GH-69988
Methode agent_set_target_velocity entfernt	❌	❌	❌	GH-69988
Methode agent_set_time_horizon aufgeteilt in agent_set_time_horizon_agents und agent_set_time_horizon_obstacles	❌	❌	❌	GH-69988
NavigationServer3D
Methode agent_set_callback umbenannt in agent_set_avoidance_callback	❌	❌	❌	GH-69988
Methode agent_set_target_velocity entfernt	❌	❌	❌	GH-69988
Methode agent_set_time_horizon aufgeteilt in agent_set_time_horizon_agents und agent_set_time_horizon_obstacles	❌	❌	❌	GH-69988

Netzwerkfunktionen

Veränderung	GDScript- kompatibel	C#-binär- kompatibel	C#-quellcode- kompatibel	Eingeführt in
WebRTCPeerConnectionExtension
Methode _create_data_channel ändert Rückgabetyp von Object auf WebRTCDataChannel	✔️	❌	✔️	GH-78237

Editor-Plugins

Veränderung	GDScript- kompatibel	C#-binär- kompatibel	C#-quellcode- kompatibel	Eingeführt in
AnimationTrackEditPlugin
Typ AnimationTrackEditPlugin entfernt	❌	❌	❌	GH-76413
EditorInterface
Typ EditorInterface ändert Vererbung von Node auf Object	✔️	❌	❌	GH-76176
Methode set_movie_maker_enabled ersetzt durch Property movie_maker_enabled	✔️	❌	❌	GH-76176
Methode is_movie_maker_enabled ersetzt durch Property movie_maker_enabled	✔️	❌	❌	GH-76176
EditorResourcePreviewGenerator
Methode _generate fügt einen neuen Parameter metadata hinzu	❌	❌	❌	GH-64628
Methode _generate_from_path fügt einen neuen Parameter metadata hinzu	❌	❌	❌	GH-64628
EditorUndoRedoManager
Methode create_action fügt einen neuen optionalen Parameter backward_undo_ops hinzu	✔️	✔️	✔️	GH-76688

Änderungen am Verhalten

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

Veränderung	Eingeführt in
SubViewportContainer
Wenn Eingabeereignisse SubViewports und deren Unterelemente erreichen sollen, muss SubViewportContainer.mouse_filter nun MOUSE_FILTER_STOP oder MOUSE_FILTER_PASS sein. Siehe GH-79271 für Details.	GH-57894
SubViewportContainer-Nodes mit mehreren Ebenen, die alle Maus-Eingabe-Ereignisse empfangen sollten, müssen nun durch Area2D-Nodes ersetzt werden. Siehe GH-79128 für Details.	GH-57894
Viewport
Viewport-Nodes, die Physics Picking aktiviert haben, setzen nun automatisch InputEvents auf "handled". Siehe GH-79897 für Workarounds.	GH-77595

Aktualisieren Ihrer GDExtension für 4.1

Um einen schwerwiegenden Fehler zu beheben, mussten wir in Godot 4.1 die Binärkompatibilität in großem und die Quellcodekompatibilität in kleinem Umfang brechen.

Dies bedeutet, dass GDExtensions, die für Godot 4.0 erstellt wurden, für Godot 4.1 neu kompiliert werden müssen (unter Verwendung des 4.1-Zweigs von godot-cpp), wobei eine kleine Änderung am Quellcode vorgenommen wird.

In Godot 4.0 sieht Ihre "entry_symbol"-Funktion etwa so aus:

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();
}

Für Godot 4.1 sollte es jedoch wie folgt aussehen:

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();
}

Es gibt zwei kleine Änderungen:

1. Das erste Argument ändert sich von const GDExtensionInterface *p_interface zu GDExtensionInterfaceGetProcAddress p_get_proc_address

2. Der Konstruktor für die Variable init_obj erhält nun p_get_proc_address als ersten 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

Damit wird Godot mitgeteilt, dass Ihre GDExtension aktualisiert wurde und sicher in Godot 4.1 geladen werden kann.