From 01e331e28a21573e47a29133b5a1bc17e50e485a Mon Sep 17 00:00:00 2001 From: Raul Santos Date: Sat, 16 Aug 2025 05:31:28 +0200 Subject: [PATCH] Add "Upgrading from Godot 4.4 to Godot 4.5" page --- tutorials/migrating/index.rst | 1 + .../migrating/upgrading_to_godot_4.5.rst | 259 ++++++++++++++++++ 2 files changed, 260 insertions(+) create mode 100644 tutorials/migrating/upgrading_to_godot_4.5.rst diff --git a/tutorials/migrating/index.rst b/tutorials/migrating/index.rst index eb0e8e7f1da..4dbe3c206cd 100644 --- a/tutorials/migrating/index.rst +++ b/tutorials/migrating/index.rst @@ -24,3 +24,4 @@ path. upgrading_to_godot_4.2 upgrading_to_godot_4.3 upgrading_to_godot_4.4 + upgrading_to_godot_4.5 diff --git a/tutorials/migrating/upgrading_to_godot_4.5.rst b/tutorials/migrating/upgrading_to_godot_4.5.rst new file mode 100644 index 00000000000..6cbbf8351d2 --- /dev/null +++ b/tutorials/migrating/upgrading_to_godot_4.5.rst @@ -0,0 +1,259 @@ +.. _doc_upgrading_to_godot_4.5: + +Upgrading from Godot 4.4 to Godot 4.5 +===================================== + +For most games and apps made with 4.4 it should be relatively safe to migrate to 4.5. +This page intends to cover everything you need to pay attention to when migrating +your project. + +Breaking changes +---------------- + +If you are migrating from 4.4 to 4.5, the breaking changes listed here might +affect you. Changes are grouped by areas/systems. + +.. warning:: + + In order to support `new Google Play requirements`_ Android now requires + targeting .NET 9 when exporting C# projects to Android, other platforms + continue to use .NET 8 as the minimum required version but newer versions + are supported and encouraged. + + If you are using C# in your project and want to export to Android, you will + need to upgrade your project to .NET 9 (see `Upgrading to a new .NET version`_ + for instructions). + +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 +======================================================================================================================== =================== ==================== ==================== ============ +**JSONRPC** +Method ``set_scope`` replaced by ``set_method`` optional parameter |❌| |✔️ with compat| |✔️ with compat| `GH-104890`_ +**Node** +Method ``get_rpc_config`` renamed to ``get_node_rpc_config`` |❌| |✔️ with compat| |✔️ with compat| `GH-106848`_ +Method ``set_name`` changes ``name`` parameter type from ``String`` to ``StringName`` |✔️| |✔️ with compat| |✔️ with compat| `GH-76560`_ +======================================================================================================================== =================== ==================== ==================== ============ + +Rendering +~~~~~~~~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**DisplayServer** +Method ``file_dialog_show`` adds a new ``parent_window_id`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-98194`_ +Method ``file_dialog_with_options_show`` adds a new ``parent_window_id`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-98194`_ +**RenderingDevice** +Method ``texture_create_from_extension`` adds a new ``mipmaps`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-105570`_ +**RenderingServer** +Method ``instance_reset_physics_interpolation`` removed |❌| |✔️ with compat| |✔️ with compat| `GH-104269`_ +Method ``instance_set_interpolated`` removed |❌| |✔️ with compat| |✔️ with compat| `GH-104269`_ +======================================================================================================================== =================== ==================== ==================== ============ + +.. note:: + + In C#, the enum ``RenderingDevice.Features`` breaks compatibility because of the way the bindings generator + detects the enum prefix. New members where added to the enum in `GH-103941`_ that caused the enum member + ``Address`` to be renamed to ``BufferDeviceAddress``. + +GLTF +~~~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**GLTFAccessor** +Property ``byte_offset`` changes type metadata from ``int32`` to ``int64`` |✔️| |❌| |❌| `GH-106220`_ +Property ``component_type`` changes type from ``int`` to ``GLTFAccessor::GLTFComponentType`` |✔️| |❌| |❌| `GH-106220`_ +Property ``count`` changes type metadata from ``int32`` to ``int64`` |✔️| |❌| |❌| `GH-106220`_ +Property ``sparse_count`` changes type metadata from ``int32`` to ``int64`` |✔️| |❌| |❌| `GH-106220`_ +Property ``sparse_indices_byte_offset`` changes type metadata from ``int32`` to ``int64`` |✔️| |❌| |❌| `GH-106220`_ +Property ``sparse_indices_component_type`` changes type from ``int`` to ``GLTFAccessor::GLTFComponentType`` |✔️| |❌| |❌| `GH-106220`_ +Property ``sparse_values_byte_offset`` changes type metadata from ``int32`` to ``int64`` |✔️| |❌| |❌| `GH-106220`_ +**GLTFBufferView** +Property ``byte_length`` changes type metadata from ``int32`` to ``int64`` |✔️| |❌| |❌| `GH-106220`_ +Property ``byte_offset`` changes type metadata from ``int32`` to ``int64`` |✔️| |❌| |❌| `GH-106220`_ +Property ``byte_stride`` changes type metadata from ``int32`` to ``int64`` |✔️| |❌| |❌| `GH-106220`_ +======================================================================================================================== =================== ==================== ==================== ============ + +.. note:: + + As a result of changing the type metadata, the C# bindings changed the type from ``int`` (32-bytes) to ``long`` (64-bytes). + +Text +~~~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**CanvasItem** +Method ``draw_char`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``draw_char_outline`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``draw_multiline_string`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``draw_multiline_string_outline`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``draw_string`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``draw_string_outline`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +**Font** +Method ``draw_char`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``draw_char_outline`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``draw_multiline_string`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``draw_multiline_string_outline`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``draw_string`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``draw_string_outline`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +**RichTextLabel** +Method ``add_image`` adds a new ``alt_text`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-76829`_ +Method ``add_image`` replaced ``size_in_percent`` parameter by ``width_in_percent`` and ``height_in_percent`` |✔️| |✔️ with compat| |✔️ with compat| `GH-107347`_ +Method ``push_strikethrough`` adds optional ``color`` parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-106300`_ +Method ``push_table`` adds a new ``name`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-76829`_ +Method ``push_underline`` adds optional ``color`` parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-106300`_ +Method ``update_image`` replaced ``size_in_percent`` parameter by ``width_in_percent`` and ``height_in_percent`` |✔️| |✔️ with compat| |✔️ with compat| `GH-107347`_ +**TextLine** +Method ``draw`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``draw_outline`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +**TextParagraph** +Method ``draw`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``draw_dropcap`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``draw_dropcap_outline`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``draw_line`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``draw_line_outline`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``draw_outline`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +**TextServer** +Method ``font_draw_glyph`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``font_draw_glyph_outline`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``shaped_text_draw`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +Method ``shaped_text_draw_outline`` adds a new ``oversampling`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-104872`_ +**TreeItem** +Method ``add_button`` adds a new ``alt_text`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-76829`_ +**TextServerExtension** +Method ``_font_draw_glyph`` adds a new ``oversampling`` optional parameter |❌| |❌| |❌| `GH-104872`_ +Method ``_font_draw_glyph_outline`` adds a new ``oversampling`` optional parameter |❌| |❌| |❌| `GH-104872`_ +Method ``_shaped_text_draw`` adds a new ``oversampling`` optional parameter |❌| |❌| |❌| `GH-104872`_ +Method ``_shaped_text_draw_outline`` adds a new ``oversampling`` optional parameter |❌| |❌| |❌| `GH-104872`_ +======================================================================================================================== =================== ==================== ==================== ============ + +XR +~~ + +============================================================================================================================================================ =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +============================================================================================================================================================ =================== ==================== ==================== ============ +**OpenXRAPIExtension** +Method ``register_composition_layer_provider`` changes ``extension`` parameter type from ``OpenXRExtensionWrapperExtension`` to ``OpenXRExtensionWrapper`` |✔️| |✔️ with compat| |✔️ with compat| `GH-104087`_ +Method ``register_projection_views_extension`` changes ``extension`` parameter type from ``OpenXRExtensionWrapperExtension`` to ``OpenXRExtensionWrapper`` |✔️| |✔️ with compat| |✔️ with compat| `GH-104087`_ +Method ``unregister_composition_layer_provider`` changes ``extension`` parameter type from ``OpenXRExtensionWrapperExtension`` to ``OpenXRExtensionWrapper`` |✔️| |✔️ with compat| |✔️ with compat| `GH-104087`_ +Method ``unregister_projection_views_extension`` changes ``extension`` parameter type from ``OpenXRExtensionWrapperExtension`` to ``OpenXRExtensionWrapper`` |✔️| |✔️ with compat| |✔️ with compat| `GH-104087`_ +**OpenXRBindingModifierEditor** +Type ``OpenXRBindingModifierEditor`` changed API type from Core to Editor |❌| |❌| |❌| `GH-103869`_ +**OpenXRInteractionProfileEditor** +Type ``OpenXRInteractionProfileEditor`` changed API type from Core to Editor |❌| |❌| |❌| `GH-103869`_ +**OpenXRInteractionProfileEditorBase** +Type ``OpenXRInteractionProfileEditorBase`` changed API type from Core to Editor |❌| |❌| |❌| `GH-103869`_ +============================================================================================================================================================ =================== ==================== ==================== ============ + +.. note:: + + Classes ``OpenXRBindingModifierEditor``, ``OpenXRInteractionProfileEditor``, and ``OpenXRInteractionProfileEditorBase`` + are only available in the editor. Using them outside of the editor will result in a compilation error. + + In C#, this means the types are moved from the ``GodotSharp`` assembly to the ``GodotSharpEditor`` assembly. + Make sure to wrap code that uses these types in a ``#if TOOLS`` block to ensure they are not included in an exported game. + + **This change was also backported to 4.4.1.** + +Editor plugins +~~~~~~~~~~~~~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**EditorExportPlatform** +Method ``get_forced_export_files`` adds a new ``preset`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-71542`_ +**EditorUndoRedoManager** +Method ``create_action`` adds a new ``mark_unsaved`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-106121`_ +**EditorExportPlatformExtension** +Method ``_get_option_icon`` changes return type from ``ImageTexture`` to ``Texture2D`` |✔️| |❌| |❌| `GH-108825`_ +======================================================================================================================== =================== ==================== ==================== ============ + +Behavior changes +---------------- + +In 4.5 some behavior changes have been introduced, which might require you to adjust your project. + +Core +~~~~ + +.. note:: + + In C#, ``StringExtensions.PathJoin`` now avoids adding an extra path separator when the original string is empty, + or when the appended path starts with a path separator (`GH-105281`_). + +.. note:: + + In C#, ``StringExtensions.GetExtension`` now returns an empty string instead of the original string + when the original string does not contain an extension (`GH-108041`_). + +.. note:: + + In C#, the ``Quaternion(Vector3, Vector3)`` constructor now correctly creates a quaternion representing + the shortest arc between the two input vectors. Previously, it would return incorrect values for certain inputs + (`GH-107618`_). + +Physics +~~~~~~~ + +.. note:: + + When the 3D physics engine is set to Jolt Physics, you will now always have overlaps between ``Area3D`` and static + bodies reported by default, as the ``physics/jolt_physics_3d/simulation/areas_detect_static_bodies`` project setting + has been removed (`GH-105746`_). If you still want such overlaps to be ignored, you will need to change the collision mask + or layer of either the ``Area3D`` or the static body instead. + +Text +~~~~ + +.. note:: + + In GDScript, calls to functions ``RichTextLabel::add_image`` and ``RichTextLabel::update_image`` will continue to work, + but the ``size_in_percent`` argument will now be used as the value for ``width_in_percent`` and ``height_in_percent`` + will default to ``false`` (`GH-107347`_). To restore the previous behavior, you can explicitly set ``height_in_percent`` + to the same value you were passing as ``size_in_percent``. + +.. |❌| 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-71542: https://github.com/godotengine/godot/pull/71542 +.. _GH-76560: https://github.com/godotengine/godot/pull/76560 +.. _GH-76829: https://github.com/godotengine/godot/pull/76829 +.. _GH-98194: https://github.com/godotengine/godot/pull/98194 +.. _GH-103869: https://github.com/godotengine/godot/pull/103869 +.. _GH-103941: https://github.com/godotengine/godot/pull/103941 +.. _GH-104087: https://github.com/godotengine/godot/pull/104087 +.. _GH-104269: https://github.com/godotengine/godot/pull/104269 +.. _GH-104872: https://github.com/godotengine/godot/pull/104872 +.. _GH-104890: https://github.com/godotengine/godot/pull/104890 +.. _GH-105281: https://github.com/godotengine/godot/pull/105281 +.. _GH-105570: https://github.com/godotengine/godot/pull/105570 +.. _GH-105746: https://github.com/godotengine/godot/pull/105746 +.. _GH-106121: https://github.com/godotengine/godot/pull/106121 +.. _GH-106220: https://github.com/godotengine/godot/pull/106220 +.. _GH-106300: https://github.com/godotengine/godot/pull/106300 +.. _GH-106848: https://github.com/godotengine/godot/pull/106848 +.. _GH-107347: https://github.com/godotengine/godot/pull/107347 +.. _GH-107618: https://github.com/godotengine/godot/pull/107618 +.. _GH-108041: https://github.com/godotengine/godot/pull/108041 +.. _GH-108825: https://github.com/godotengine/godot/pull/108825 + +.. _new Google Play requirements: https://android-developers.googleblog.com/2025/05/prepare-play-apps-for-devices-with-16kb-page-size.html +.. _Upgrading to a new .NET version: https://learn.microsoft.com/en-us/dotnet/core/install/upgrade