From efaf8b669e303331b297a5c09585e409d168c215 Mon Sep 17 00:00:00 2001 From: Raul Santos Date: Fri, 24 Jan 2025 18:38:30 +0100 Subject: [PATCH 1/2] Add "Upgrading from Godot 4.3 to Godot 4.4" page --- tutorials/migrating/index.rst | 1 + .../migrating/upgrading_to_godot_4.4.rst | 216 ++++++++++++++++++ 2 files changed, 217 insertions(+) create mode 100644 tutorials/migrating/upgrading_to_godot_4.4.rst diff --git a/tutorials/migrating/index.rst b/tutorials/migrating/index.rst index 90291dc2136..eb0e8e7f1da 100644 --- a/tutorials/migrating/index.rst +++ b/tutorials/migrating/index.rst @@ -23,3 +23,4 @@ path. upgrading_to_godot_4.1 upgrading_to_godot_4.2 upgrading_to_godot_4.3 + upgrading_to_godot_4.4 diff --git a/tutorials/migrating/upgrading_to_godot_4.4.rst b/tutorials/migrating/upgrading_to_godot_4.4.rst new file mode 100644 index 00000000000..c0b49b6966d --- /dev/null +++ b/tutorials/migrating/upgrading_to_godot_4.4.rst @@ -0,0 +1,216 @@ +.. _doc_upgrading_to_godot_4.4: + +Upgrading from Godot 4.3 to Godot 4.4 +===================================== + +For most games and apps made with 4.3 it should be relatively safe to migrate to 4.4. +This page intends to cover everything you need to pay attention to when migrating +your project. + +Breaking changes +---------------- + +If you are migrating from 4.3 to 4.4, the breaking changes listed here might +affect you. Changes are grouped by areas/systems. + +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 +======================================================================================================================== =================== ==================== ==================== ============ +**FileAccess** +Method ``open_encrypted`` adds a new ``iv`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-98918`_ +Method ``store_8`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_ +Method ``store_16`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_ +Method ``store_32`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_ +Method ``store_64`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_ +Method ``store_buffer`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_ +Method ``store_csv_line`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_ +Method ``store_double`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_ +Method ``store_float`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_ +Method ``store_half`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_ +Method ``store_line`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_ +Method ``store_pascal_string`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_ +Method ``store_real`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_ +Method ``store_string`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_ +Method ``store_var`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_ +**OS** +Method ``execute_with_pipe`` adds a new ``blocking`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-94434`_ +Method ``read_string_from_stdin`` adds a new ``buffer_size`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-91201`_ +**RegEx** +Method ``compile`` adds a new ``show_error`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-95212`_ +Method ``create_from_string`` adds a new ``show_error`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-95212`_ +**Semaphore** +Method ``post`` adds a new ``count`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-93605`_ +**TranslationServer** +Method ``standardize_locale`` adds a new ``add_defaults`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-98972`_ +======================================================================================================================== =================== ==================== ==================== ============ + +GUI nodes +~~~~~~~~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**RichTextLabel** +Method ``push_meta`` adds a new ``tooltip`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-99481`_ +Method ``set_table_column_expand`` adds a new ``shrink`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-101482`_ +**GraphEdit** +Method ``connect_node`` adds a new ``keep_alive`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-97449`_ +Signal ``frame_rect_changed`` changes ``new_rect`` parameter type from ``Vector2`` to ``Rect2`` |❌| |❌| |❌| `GH-102796`_ +======================================================================================================================== =================== ==================== ==================== ============ + +Physics +~~~~~~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**SoftBody3D** +Method ``set_point_pinned`` adds a new ``insert_at`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-94684`_ +======================================================================================================================== =================== ==================== ==================== ============ + +Rendering +~~~~~~~~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**CPUParticles2D** +Method ``restart`` adds a new ``keep_seed`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-92089`_ +**CPUParticles3D** +Method ``restart`` adds a new ``keep_seed`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-92089`_ +**GPUParticles2D** +Method ``restart`` adds a new ``keep_seed`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-92089`_ +**GPUParticles3D** +Method ``restart`` adds a new ``keep_seed`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-92089`_ +**RenderingDevice** +Method ``draw_list_begin`` adds a new ``breadcrumb`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-90993`_ +Method ``draw_list_begin`` removes many parameters |❌| |✔️ with compat| |✔️ with compat| `GH-98670`_ +Method ``index_buffer_create`` adds a new ``enable_device_address`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-100062`_ +Method ``uniform_buffer_create`` adds a new ``enable_device_address`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-100062`_ +Method ``vertex_buffer_create`` adds a new ``enable_device_address`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-100062`_ +**RenderingServer** +Method ``multimesh_allocate_data`` adds a new ``use_indirect`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-99455`_ +**Shader** +Method ``get_default_texture_parameter`` changes return type from ``Texture2D`` to ``Texture`` |✔️| |❌| |❌| `GH-95126`_ +Method ``set_default_texture_parameter`` changes ``texture`` parameter type from ``Texture2D`` to ``Texture`` |✔️| |❌| |✔️| `GH-95126`_ +**VisualShaderNodeCubemap** +Property ``cube_map`` changes type from ``Cubemap`` to ``TextureLayered`` |✔️| |❌| |❌| `GH-95126`_ +**VisualShaderNodeTexture2DArray** +Property ``texture_array`` changes type from ``Texture2DArray`` to ``TextureLayered`` |✔️| |❌| |❌| `GH-95126`_ +======================================================================================================================== =================== ==================== ==================== ============ + +.. note:: + + In C#, the enum ``RenderingDevice.StorageBufferUsage`` breaks compatibility because of the way the bindings generator + detects the enum prefix. New members where added in `GH-100062`_ to the enum that caused the enum members to be renamed. + +Navigation +~~~~~~~~~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**NavigationServer2D** +Method ``query_path`` adds a new ``callback`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-100129`_ +**NavigationServer3D** +Method ``query_path`` adds a new ``callback`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-100129`_ +======================================================================================================================== =================== ==================== ==================== ============ + +Editor plugins +~~~~~~~~~~~~~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**EditorInterface** +Method ``open_scene_from_path`` adds a new ``set_inherited`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-90057`_ +Method ``popup_node_selector`` adds a new ``current_value`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-94323`_ +Method ``popup_property_selector`` adds a new ``current_value`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-94323`_ +**EditorSceneFormatImporter** +Method ``_get_import_flags`` removed |❌| |❌| |❌| `GH-101531`_ +**EditorTranslationParserPlugin** +Method ``_parse_file`` changes return type to ``Array`` and removes ``msgids`` and ``msgids_context_plural`` parameters |❌| |❌| |❌| `GH-99297`_ +======================================================================================================================== =================== ==================== ==================== ============ + +.. note:: + + The method ``_get_import_flags`` was never used by the engine, since it was open source. So it was removed + despite the compat breakage as there's no way for users to rely on this affecting engine behavior. + +Behavior changes +---------------- + +Core +~~~~ + +.. note:: + + The ``Curve`` resource now enforces its value range, so ``min_value`` and ``max_value`` need to be changed + if any of the points fall outside of the default ``[0, 1]`` range. + +Rendering +~~~~~~~~~ + +.. note:: + + The ``VisualShaderNodeVec4Constant`` shader node had its input type changed to ``Vector4``. Users need to + recreate the values in their constants. + +CSG +~~~ + +.. note:: + + The CSG implementation now uses Emmett Lalish's `Manifold `_ library (`GH-94321`_). + The new implementation is more consistent with manifold definitions and fixes a number of bugs and stability + issues. As a result, non-manifold meshes are no longer supported. Use ``MeshInstance3D`` for rendering quads + and other non-manifold geometry. + +Android +~~~~~~~ + +.. note:: + + Android sensor events are no longer enabled by default (`GH-94799`_), projects that use sensor events can + enable them as needed in Project Settings under "input_devices/sensors/". + +.. |❌| 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-78289: https://github.com/godotengine/godot/pull/78289 +.. _GH-90057: https://github.com/godotengine/godot/pull/90057 +.. _GH-90993: https://github.com/godotengine/godot/pull/90993 +.. _GH-91201: https://github.com/godotengine/godot/pull/91201 +.. _GH-92089: https://github.com/godotengine/godot/pull/92089 +.. _GH-93605: https://github.com/godotengine/godot/pull/93605 +.. _GH-94321: https://github.com/godotengine/godot/pull/94321 +.. _GH-94323: https://github.com/godotengine/godot/pull/94323 +.. _GH-94434: https://github.com/godotengine/godot/pull/94434 +.. _GH-99455: https://github.com/godotengine/godot/pull/99455 +.. _GH-94684: https://github.com/godotengine/godot/pull/94684 +.. _GH-94799: https://github.com/godotengine/godot/pull/94799 +.. _GH-95212: https://github.com/godotengine/godot/pull/95212 +.. _GH-95126: https://github.com/godotengine/godot/pull/95126 +.. _GH-97449: https://github.com/godotengine/godot/pull/97449 +.. _GH-98670: https://github.com/godotengine/godot/pull/98670 +.. _GH-98918: https://github.com/godotengine/godot/pull/98918 +.. _GH-98972: https://github.com/godotengine/godot/pull/98972 +.. _GH-99297: https://github.com/godotengine/godot/pull/99297 +.. _GH-99481: https://github.com/godotengine/godot/pull/99481 +.. _GH-100062: https://github.com/godotengine/godot/pull/100062 +.. _GH-100129: https://github.com/godotengine/godot/pull/100129 +.. _GH-101482: https://github.com/godotengine/godot/pull/101482 +.. _GH-101531: https://github.com/godotengine/godot/pull/101531 +.. _GH-102796: https://github.com/godotengine/godot/pull/102796 From aa17d7a76001ad0517917471f37f0d75836734ed Mon Sep 17 00:00:00 2001 From: Raul Santos Date: Mon, 24 Feb 2025 23:28:43 +0100 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: tetrapod <145553014+tetrapod00@users.noreply.github.com> --- tutorials/migrating/upgrading_to_godot_4.4.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/tutorials/migrating/upgrading_to_godot_4.4.rst b/tutorials/migrating/upgrading_to_godot_4.4.rst index c0b49b6966d..1559ee2704b 100644 --- a/tutorials/migrating/upgrading_to_godot_4.4.rst +++ b/tutorials/migrating/upgrading_to_godot_4.4.rst @@ -145,8 +145,8 @@ Method ``_parse_file`` changes return type to ``Array`` and removes ``msgids`` a .. note:: - The method ``_get_import_flags`` was never used by the engine, since it was open source. So it was removed - despite the compat breakage as there's no way for users to rely on this affecting engine behavior. + The method ``_get_import_flags`` was never used by the engine. It was removed despite the + compatibility breakage as there's no way for users to rely on this affecting engine behavior. Behavior changes ---------------- @@ -174,16 +174,16 @@ CSG The CSG implementation now uses Emmett Lalish's `Manifold `_ library (`GH-94321`_). The new implementation is more consistent with manifold definitions and fixes a number of bugs and stability - issues. As a result, non-manifold meshes are no longer supported. Use ``MeshInstance3D`` for rendering quads - and other non-manifold geometry. + issues. As a result, non-manifold meshes are no longer supported. You can use ``MeshInstance3D`` for + rendering non-manifold geometry, such as quads or planes. Android ~~~~~~~ .. note:: - Android sensor events are no longer enabled by default (`GH-94799`_), projects that use sensor events can - enable them as needed in Project Settings under "input_devices/sensors/". + Android sensor events are no longer enabled by default (`GH-94799`_). Projects that use sensor events can + enable them as needed in Project Settings under **Input Devices > Sensors**. .. |❌| replace:: :abbr:`❌ (This API breaks compatibility.)` .. |✔️| replace:: :abbr:`✔️ (This API does not break compatibility.)`