|
|
@@ -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
|
Raul Santos