|
|
@@ -0,0 +1,215 @@
|
|
|
+.. _doc_upgrading_to_godot_4.1:
|
|
|
+
|
|
|
+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 list. GDExtensions built against 4.0 need to be upgraded.
|
|
|
+
|
|
|
+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 |✔️| |✔️ with compat| |✔️| `GH-76688`_
|
|
|
+**WorkerThreadPool**
|
|
|
+Method ``wait_for_task_completion`` changes return type from ``void`` to ``Error`` |✔️| |❌| |✔️| `GH-77143`_
|
|
|
+======================================================================================================================== =================== ==================== ==================== ===========
|
|
|
+
|
|
|
+Animation
|
|
|
+^^^^^^^^^
|
|
|
+
|
|
|
+======================================================================================================================== =================== ==================== ==================== ===========
|
|
|
+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 |✔️| |✔️ with compat| |✔️| `GH-75759`_
|
|
|
+Method ``blend_node`` adds a new ``test_only`` optional parameter |✔️| |✔️ with compat| |✔️| `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]`` |✔️| |✔️ with compat| |❌| `GH-76418`_
|
|
|
+**MeshInstance3D**
|
|
|
+Method ``create_multiple_convex_collisions`` adds a new ``settings`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-72152`_
|
|
|
+**Node3D**
|
|
|
+Method ``look_at`` adds a new ``use_model_front`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-76082`_
|
|
|
+Method ``look_at_from_position`` adds a new ``use_model_front`` optional parameter |✔️| |✔️ with compat| |✔️| `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 |✔️| |✔️ with compat| |✔️| `GH-75746`_
|
|
|
+**RichTextLabel**
|
|
|
+Method ``push_list`` adds a new ``bullet`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-75017`_
|
|
|
+Method ``push_paragraph`` adds a new ``justification_flags`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-75250`_
|
|
|
+Method ``push_paragraph`` adds a new ``tab_stops`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-76401`_
|
|
|
+**Tree**
|
|
|
+Method ``edit_selected`` adds a new ``force_edit`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-76794`_
|
|
|
+======================================================================================================================== =================== ==================== ==================== ===========
|
|
|
+
|
|
|
+Physics
|
|
|
+^^^^^^^
|
|
|
+
|
|
|
+======================================================================================================================== =================== ==================== ==================== ===========
|
|
|
+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`_
|
|
|
+======================================================================================================================== =================== ==================== ==================== ===========
|
|
|
+
|
|
|
+Rendering
|
|
|
+^^^^^^^^^
|
|
|
+
|
|
|
+======================================================================================================================== =================== ==================== ==================== ===========
|
|
|
+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]`` |✔️| |✔️ with compat| |❌| `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]`` |✔️| |✔️ with compat| |❌| `GH-76418`_
|
|
|
+======================================================================================================================== =================== ==================== ==================== ===========
|
|
|
+
|
|
|
+Navigation
|
|
|
+^^^^^^^^^^
|
|
|
+
|
|
|
+======================================================================================================================== =================== ==================== ==================== ===========
|
|
|
+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
|
|
|
+^^^^^^^^^^
|
|
|
+
|
|
|
+======================================================================================================================== =================== ==================== ==================== ===========
|
|
|
+Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced
|
|
|
+======================================================================================================================== =================== ==================== ==================== ===========
|
|
|
+**WebRTCPeerConnectionExtension**
|
|
|
+Method ``_create_data_channel`` changes return type from ``Object`` to ``WebRTCDataChannel`` |✔️| |❌| |✔️| `GH-78237`_
|
|
|
+======================================================================================================================== =================== ==================== ==================== ===========
|
|
|
+
|
|
|
+Editor plugins
|
|
|
+^^^^^^^^^^^^^^
|
|
|
+
|
|
|
+======================================================================================================================== =================== ==================== ==================== ===========
|
|
|
+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 |✔️| |✔️ with compat| |✔️| `GH-76688`_
|
|
|
+======================================================================================================================== =================== ==================== ==================== ===========
|
|
|
+
|
|
|
+
|
|
|
+.. |❌| replace:: :abbr:`❌ (This API breaks compatibility.)`
|
|
|
+.. |✔️| replace:: :abbr:`✔️ (This API does not break compatibility.)`
|
|
|
+.. |✔️ with compat| replace:: :abbr:`✔️ (This API does not break compatibility. A compatibility method was added.)`
|
|
|
+
|
|
|
+.. _GH-64628: https://github.com/godotengine/godot/pull/64628
|
|
|
+.. _GH-69988: https://github.com/godotengine/godot/pull/69988
|
|
|
+.. _GH-72152: https://github.com/godotengine/godot/pull/72152
|
|
|
+.. _GH-72749: https://github.com/godotengine/godot/pull/72749
|
|
|
+.. _GH-72842: https://github.com/godotengine/godot/pull/72842
|
|
|
+.. _GH-75017: https://github.com/godotengine/godot/pull/75017
|
|
|
+.. _GH-75250: https://github.com/godotengine/godot/pull/75250
|
|
|
+.. _GH-75260: https://github.com/godotengine/godot/pull/75260
|
|
|
+.. _GH-75746: https://github.com/godotengine/godot/pull/75746
|
|
|
+.. _GH-75759: https://github.com/godotengine/godot/pull/75759
|
|
|
+.. _GH-76082: https://github.com/godotengine/godot/pull/76082
|
|
|
+.. _GH-76176: https://github.com/godotengine/godot/pull/76176
|
|
|
+.. _GH-76401: https://github.com/godotengine/godot/pull/76401
|
|
|
+.. _GH-76413: https://github.com/godotengine/godot/pull/76413
|
|
|
+.. _GH-76418: https://github.com/godotengine/godot/pull/76418
|
|
|
+.. _GH-76688: https://github.com/godotengine/godot/pull/76688
|
|
|
+.. _GH-76794: https://github.com/godotengine/godot/pull/76794
|
|
|
+.. _GH-77143: https://github.com/godotengine/godot/pull/77143
|
|
|
+.. _GH-78237: https://github.com/godotengine/godot/pull/78237
|
Raul Santos