From 142d191c3b4e5da99e3f50c8dec855c95861b3f9 Mon Sep 17 00:00:00 2001 From: Raul Santos Date: Wed, 29 Apr 2026 18:40:57 +0200 Subject: [PATCH] Add "Upgrading from Godot 4.6 to Godot 4.7" page --- tutorials/migrating/index.rst | 1 + .../migrating/upgrading_to_godot_4.7.rst | 277 ++++++++++++++++++ 2 files changed, 278 insertions(+) create mode 100644 tutorials/migrating/upgrading_to_godot_4.7.rst diff --git a/tutorials/migrating/index.rst b/tutorials/migrating/index.rst index 42fa5f64d7a..b57b48a9bf3 100644 --- a/tutorials/migrating/index.rst +++ b/tutorials/migrating/index.rst @@ -26,3 +26,4 @@ path. upgrading_to_godot_4.4 upgrading_to_godot_4.5 upgrading_to_godot_4.6 + upgrading_to_godot_4.7 diff --git a/tutorials/migrating/upgrading_to_godot_4.7.rst b/tutorials/migrating/upgrading_to_godot_4.7.rst new file mode 100644 index 00000000000..0a6c875248d --- /dev/null +++ b/tutorials/migrating/upgrading_to_godot_4.7.rst @@ -0,0 +1,277 @@ +.. _doc_upgrading_to_godot_4.7: + +Upgrading from Godot 4.6 to Godot 4.7 +===================================== + +For most games and apps made with 4.6 it should be relatively safe to migrate to 4.7. +This page intends to cover everything you need to pay attention to when migrating +your project. + +Breaking changes +---------------- + +If you are migrating from 4.6 to 4.7, 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 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 +======================================================================================================================== =================== ==================== ==================== ============ +**Object** +Method ``is_class`` changes ``class`` parameter type from ``String`` to ``StringName`` |✔️| |✔️ with compat| |✔️| `GH-118582`_ +**ZIPPacker** +Method ``start_file`` adds new ``permissions`` and ``modified_time`` optional parameters |✔️| |✔️ with compat| |✔️| `GH-115946`_ +======================================================================================================================== =================== ==================== ==================== ============ + +2D +~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**CPUParticles2D** +Method ``request_particles_process`` adds new ``process_time_residual`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-109142`_ +**GPUParticles2D** +Method ``request_particles_process`` adds new ``process_time_residual`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-109142`_ +======================================================================================================================== =================== ==================== ==================== ============ + +3D +~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**CPUParticles3D** +Method ``request_particles_process`` adds new ``process_time_residual`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-109142`_ +**GPUParticles3D** +Method ``request_particles_process`` adds new ``process_time_residual`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-109142`_ +======================================================================================================================== =================== ==================== ==================== ============ + +GUI nodes +~~~~~~~~~ + +================================================================================================================================================= =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +================================================================================================================================================= =================== ==================== ==================== ============ +**Control** +Property ``accessibility_live`` changes type from ``DisplayServer.AccessibilityLiveMode`` to ``AccessibilityServer.AccessibilityLiveMode`` |✔️| |❌| |❌| `GH-116839`_ +**RichTextLabel** +Enum field ``ImageUpdateMask.UPDATE_WIDTH_IN_PERCENT`` renamed to ``ImageUpdateMask.UPDATE_WIDTH_UNIT`` |❌| |✔️| |❌| `GH-112617`_ +Method ``add_image`` changes ``width`` parameter type from ``int`` to ``float`` |✔️| |✔️ with compat| |✔️| `GH-112617`_ +Method ``add_image`` changes ``height`` parameter type from ``int`` to ``float`` |✔️| |✔️ with compat| |✔️| `GH-112617`_ +Method ``add_image`` renames ``width_in_percent`` parameter to ``width_unit`` and changes type from ``bool`` to ``RichTextLabel.ImageUnit`` |✔️| |✔️ with compat| |✔️ with compat| `GH-112617`_ +Method ``add_image`` renames ``height_in_percent`` parameter to ``height_unit`` and changes type from ``bool`` to ``RichTextLabel.ImageUnit`` |✔️| |✔️ with compat| |✔️ with compat| `GH-112617`_ +Method ``update_image`` changes ``width`` parameter type from ``int`` to ``float`` |✔️| |✔️ with compat| |✔️| `GH-112617`_ +Method ``update_image`` changes ``height`` parameter type from ``int`` to ``float`` |✔️| |✔️ with compat| |✔️| `GH-112617`_ +Method ``update_image`` renames ``width_in_percent`` parameter to ``width_unit`` and changes type from ``bool`` to ``RichTextLabel.ImageUnit`` |✔️| |✔️ with compat| |✔️ with compat| `GH-112617`_ +Method ``update_image`` renames ``height_in_percent`` parameter to ``height_unit`` and changes type from ``bool`` to ``RichTextLabel.ImageUnit`` |✔️| |✔️ with compat| |✔️ with compat| `GH-112617`_ +================================================================================================================================================= =================== ==================== ==================== ============ + +Text +~~~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**Font** +Method ``find_variation`` adds new ``palette_index`` and ``custom_colors`` optional parameters |✔️| |✔️ with compat| |✔️| `GH-117149`_ +======================================================================================================================== =================== ==================== ==================== ============ + +Rendering +~~~~~~~~~ + +================================================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +================================================================================================================================================== =================== ==================== ==================== ============ +**Image** +Method ``save_exr`` adds new ``color_image`` and ``max_linear_value`` optional parameters |✔️| |✔️ with compat| |✔️| `GH-117800`_ +Method ``save_exr_to_buffer`` adds new ``color_image`` and ``max_linear_value`` optional parameters |✔️| |✔️ with compat| |✔️| `GH-117800`_ +**ImageTexture** +Method ``get_format`` moved to base class ``Texture2D`` |✔️| |✔️| |✔️| `GH-109004`_ +**PortableCompressedTexture2D** +Method ``get_format`` moved to base class ``Texture2D`` |✔️| |✔️| |✔️| `GH-109004`_ +**RenderingServer** +Method ``particles_request_process_time`` renames ``time`` parameter to ``process_time`` and adds new ``process_time_residual`` optional parameter |✔️| |✔️ with compat| |❌| `GH-109142`_ +Method ``viewport_set_size`` adds new ``view_count`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-115799`_ +================================================================================================================================================== =================== ==================== ==================== ============ + +Animation +~~~~~~~~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**Animation** +Property ``length`` changes type metadata from ``float`` to ``double`` |✔️| |❌| |❌| `GH-116394`_ +**AnimationNodeBlendSpace1D** +Method ``add_blend_point`` adds new ``name`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-110369`_ +**AnimationNodeBlendSpace2D** +Method ``add_blend_point`` adds new ``name`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-110369`_ +======================================================================================================================== =================== ==================== ==================== ============ + +Physics +~~~~~~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**PhysicsServer2D** +Method ``body_set_shape_as_one_way_collision`` adds new ``direction`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-104736`_ +**PhysicsServer2DExtension** +Method ``_body_set_shape_as_one_way_collision`` adds new ``direction`` parameter |❌| |❌| |❌| `GH-104736`_ +======================================================================================================================== =================== ==================== ==================== ============ + +Audio +~~~~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**AudioEffectSpectrumAnalyzer** +Property ``tap_back_pos`` removed |❌| |❌| |❌| `GH-114355`_ +======================================================================================================================== =================== ==================== ==================== ============ + +XR +~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**OpenXRExtensionWrapper** +Method ``_on_register_metadata`` adds new ``interaction_profile_metadata`` parameter |❌| |❌| |❌| `GH-117399`_ +**OpenXRSpatialAnchorCapability** +Method ``create_new_anchor`` adds new ``next`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-118128`_ +======================================================================================================================== =================== ==================== ==================== ============ + +Editor +~~~~~~ + +======================================================================================================================== =================== ==================== ==================== ============ +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== ============ +**EditorSceneFormatImporter** +Constant ``IMPORT_ANIMATION`` moved to enum ``ImportFlags`` |✔️| |✔️| |❌| `GH-115788`_ +Constant ``IMPORT_DISCARD_MESHES_AND_MATERIALS`` moved to enum ``ImportFlags`` |✔️| |✔️| |❌| `GH-115788`_ +Constant ``IMPORT_FAIL_ON_MISSING_DEPENDENCIES`` moved to enum ``ImportFlags`` |✔️| |✔️| |❌| `GH-115788`_ +Constant ``IMPORT_FORCE_DISABLE_MESH_COMPRESSION`` moved to enum ``ImportFlags`` |✔️| |✔️| |❌| `GH-115788`_ +Constant ``IMPORT_GENERATE_TANGENT_ARRAYS`` moved to enum ``ImportFlags`` |✔️| |✔️| |❌| `GH-115788`_ +Constant ``IMPORT_SCENE`` moved to enum ``ImportFlags`` |✔️| |✔️| |❌| `GH-115788`_ +Constant ``IMPORT_USE_NAMED_SKIN_BINDS`` moved to enum ``ImportFlags`` |✔️| |✔️| |❌| `GH-115788`_ +**EditorVCSInterface** +Method ``_commit`` adds new ``amend`` parameter |❌| |❌| |❌| `GH-117968`_ +======================================================================================================================== =================== ==================== ==================== ============ + +Behavior changes +---------------- + +Rendering +~~~~~~~~~ + +.. note:: + + The ``LinearToSRGB`` visual shader no longer clamps to the range ``[0.0, 1.0]`` + when using the Mobile or Forward+ renderer (`GH-113956`_). + +.. note:: + + ``CanvasItem`` now avoids adding the antialiasing feather when drawing lines (`GH-105122`_). + The feather made lines appear thicker than intended, projects that relied on this behavior + will have to be updated to draw a thicker line width. + +Physics +~~~~~~~ + +.. note:: + + The default ``area_mask`` for ``AudioStreamPlayer`` was changed to ``0`` (disabled) (`GH-107679`_). + If you use the ``audio_bus_override`` feature on ``Area2D`` or ``Area3D``, **and** you + use the ``AudioStreamPlayer`` default ``area_mask`` (just layer ``1`` ticked), you will need + to reset the mask to layer ``1`` — otherwise, the bus overrides will stop working. + If the mask was set to anything except layer ``1``, it will continue to work as expected. + +Changed defaults +---------------- + +The following default values have been changed. If your project uses any of these properties +with their default value, you can achieve a similar behavior to the previous version by manually +setting the values to match the old defaults. + +Animation +~~~~~~~~~ + +================================================================================ ========================= ========================= +Property/Parameter Old Default New Default +================================================================================ ========================= ========================= +**LookAtModifier3D** +Property ``relative`` true false +================================================================================ ========================= ========================= + +Core +~~~~ + +================================================================================ ========================= ========================= +Property/Parameter Old Default New Default +================================================================================ ========================= ========================= +**ProjectSettings** +Property ``rendering/reflections/sky_reflections/roughness_layers`` 7 8 +================================================================================ ========================= ========================= + +GUI nodes +~~~~~~~~~ + +================================================================================ ========================= ========================= +Property/Parameter Old Default New Default +================================================================================ ========================= ========================= +**RichTextLabel** +Method ``add_image`` parameter ``width_in_percent`` false 0 +Method ``add_image`` parameter ``height_in_percent`` false 0 +Method ``update_image`` parameter ``width_in_percent`` false 0 +Method ``update_image`` parameter ``height_in_percent`` false 0 +================================================================================ ========================= ========================= + +Import +~~~~~~ + +================================================================================ ========================= ========================= +Property/Parameter Old Default New Default +================================================================================ ========================= ========================= +**ResourceImporterDynamicFont** +Property ``hinting`` 1 3 +================================================================================ ========================= ========================= + +.. |N/A| replace:: :abbr:`N/A (This API is not available so compatibility is not applicable.)` +.. |❌| replace:: :abbr:`❌ (This API breaks compatibility.)` +.. |❌ with stub| replace:: :abbr:`❌ (Stub compatibility methods were added to prevent crashes. However, this API is not functional anymore.)` +.. |✔️| replace:: :abbr:`✔️ (This API does not break compatibility.)` +.. |✔️ with compat| replace:: :abbr:`✔️ (This API does not break compatibility. A compatibility method was added.)` + +.. _GH-104736: https://github.com/godotengine/godot/pull/104736 +.. _GH-105122: https://github.com/godotengine/godot/pull/105122 +.. _GH-107679: https://github.com/godotengine/godot/pull/107679 +.. _GH-109004: https://github.com/godotengine/godot/pull/109004 +.. _GH-109142: https://github.com/godotengine/godot/pull/109142 +.. _GH-110369: https://github.com/godotengine/godot/pull/110369 +.. _GH-112617: https://github.com/godotengine/godot/pull/112617 +.. _GH-113956: https://github.com/godotengine/godot/pull/113956 +.. _GH-114355: https://github.com/godotengine/godot/pull/114355 +.. _GH-115788: https://github.com/godotengine/godot/pull/115788 +.. _GH-115799: https://github.com/godotengine/godot/pull/115799 +.. _GH-115946: https://github.com/godotengine/godot/pull/115946 +.. _GH-116394: https://github.com/godotengine/godot/pull/116394 +.. _GH-116839: https://github.com/godotengine/godot/pull/116839 +.. _GH-117149: https://github.com/godotengine/godot/pull/117149 +.. _GH-117399: https://github.com/godotengine/godot/pull/117399 +.. _GH-117800: https://github.com/godotengine/godot/pull/117800 +.. _GH-117968: https://github.com/godotengine/godot/pull/117968 +.. _GH-118128: https://github.com/godotengine/godot/pull/118128 +.. _GH-118582: https://github.com/godotengine/godot/pull/118582