mirror of
https://github.com/godotengine/godot-docs.git
synced 2026-01-04 14:11:02 +03:00
Add "Upgrading from Godot 4.4 to Godot 4.5" page
This commit is contained in:
Raul Santos
@@ -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
|
||||
|
||||
259
tutorials/migrating/upgrading_to_godot_4.5.rst
Normal file
259
tutorials/migrating/upgrading_to_godot_4.5.rst
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user