mirror of
https://github.com/godotengine/godot-docs.git
synced 2026-01-04 14:11:02 +03:00
295 lines
26 KiB
ReStructuredText
295 lines
26 KiB
ReStructuredText
.. _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 table below. See the :ref:`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
|
|
~~~~
|
|
|
|
======================================================================================================================== =================== ==================== ==================== ===========
|
|
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`_
|
|
======================================================================================================================== =================== ==================== ==================== ===========
|
|
|
|
|
|
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`_
|
|
================================================================================================================================================================================================== ===========
|
|
|
|
|
|
.. |❌| 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-57894: https://github.com/godotengine/godot/pull/57894
|
|
.. _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-77595: https://github.com/godotengine/godot/pull/77595
|
|
.. _GH-78237: https://github.com/godotengine/godot/pull/78237
|
|
.. _GH-79128: https://github.com/godotengine/godot/issues/79128
|
|
.. _GH-79271: https://github.com/godotengine/godot/issues/79271
|
|
.. _GH-79897: https://github.com/godotengine/godot/issues/79897
|
|
|
|
.. _updating_your_gdextension_for_godot_4_1:
|
|
|
|
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:
|
|
|
|
.. code-block:: cpp
|
|
|
|
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:
|
|
|
|
.. code-block:: cpp
|
|
|
|
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.
|