Merge pull request #9250 from raulsntos/breaking_changes_4.3

Add "Upgrading from Godot 4.2 to Godot 4.3" page

tutorials/migrating/index.rst

@@ -22,3 +22,4 @@ path.
    upgrading_to_godot_4
    upgrading_to_godot_4.1
    upgrading_to_godot_4.2
+   upgrading_to_godot_4.3

tutorials/migrating/upgrading_to_godot_4.3.rst

@@ -0,0 +1,366 @@
+.. _doc_upgrading_to_godot_4.3:
+
+Upgrading from Godot 4.2 to Godot 4.3
+=====================================
+
+For most games and apps made with 4.2 it should be relatively safe to migrate to 4.3.
+This page intends to cover everything you need to pay attention to when migrating
+your project.
+
+Breaking changes
+----------------
+
+If you are migrating from 4.2 to 4.3, 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.
+
+GDExtension
+^^^^^^^^^^^
+
+========================================================================================================================  ===================  ====================  ====================  ===========
+Change                                                                                                                    GDScript Compatible  C# Binary Compatible  C# Source Compatible  Introduced
+========================================================================================================================  ===================  ====================  ====================  ===========
+**GDExtension**
+Method ``close_library`` removed                                                                                          |❌|                 |❌|                  |❌|                  `GH-88418`_
+Method ``initialize_library`` removed                                                                                     |❌|                 |❌|                  |❌|                  `GH-88418`_
+Method ``open_library`` removed                                                                                           |❌|                 |❌|                  |❌|                  `GH-88418`_
+========================================================================================================================  ===================  ====================  ====================  ===========
+
+Since it was basically impossible to use these methods in any useful way, these methods have been removed. Use ``GDExtensionManager::load_extension`` and ``GDExtensionManager::unload_extension`` instead to correctly load and unload a GDExtension.
+
+Animation
+^^^^^^^^^
+
+========================================================================================================================  ===================  ====================  ====================  ===========
+Change                                                                                                                    GDScript Compatible  C# Binary Compatible  C# Source Compatible  Introduced
+========================================================================================================================  ===================  ====================  ====================  ===========
+**Animation**
+Method ``position_track_interpolate`` adds a new ``backward`` optional parameter                                          |✔️|                 |✔️ with compat|      |✔️|                  `GH-86629`_
+Method ``rotation_track_interpolate`` adds a new ``backward`` optional parameter                                          |✔️|                 |✔️ with compat|      |✔️|                  `GH-86629`_
+Method ``scale_track_interpolate`` adds a new ``backward`` optional parameter                                             |✔️|                 |✔️ with compat|      |✔️|                  `GH-86629`_
+Method ``blend_shape_track_interpolate`` adds a new ``backward`` optional parameter                                       |✔️|                 |✔️ with compat|      |✔️|                  `GH-86629`_
+Method ``value_track_interpolate`` adds a new ``backward`` optional parameter                                             |✔️|                 |✔️ with compat|      |✔️|                  `GH-86629`_
+Method ``track_find_key`` adds a new ``limit`` optional parameter                                                         |✔️|                 |✔️ with compat|      |✔️|                  `GH-86661`_
+Method ``track_find_key`` adds a new ``backward`` optional parameter                                                      |✔️|                 |✔️ with compat|      |✔️|                  `GH-92861`_
+**AnimationMixer**
+Method ``_post_process_key_value`` changes ``object`` parameter type from ``Object`` to ``uint64``                        |✔️|                 |❌|                  |❌|                  `GH-86687`_
+**Skeleton3D**
+Method ``add_bone`` changes return type from ``void`` to ``int32``                                                        |✔️|                 |❌|                  |✔️|                  `GH-88791`_
+Signal ``bone_pose_changed`` replaced by ``skeleton_updated``                                                             |❌|                 |❌|                  |❌|                  `GH-90575`_
+**BoneAttachment3D**
+Method ``on_bone_pose_update`` replaced by ``on_skeleton_update``                                                         |✔️|                 |✔️ with compat|      |✔️ with compat|      `GH-90575`_
+========================================================================================================================  ===================  ====================  ====================  ===========
+
+GUI nodes
+^^^^^^^^^
+
+========================================================================================================================  ===================  ====================  ====================  ===========
+Change                                                                                                                    GDScript Compatible  C# Binary Compatible  C# Source Compatible  Introduced
+========================================================================================================================  ===================  ====================  ====================  ===========
+**AcceptDialog**
+Method ``register_text_enter`` changes parameter ``line_edit`` type from ``Control`` to ``LineEdit``                      |✔️|                 |✔️ with compat|      |✔️ with compat|      `GH-89419`_
+Method ``remove_button`` changes parameter ``button`` type from ``Control`` to ``Button``                                 |✔️|                 |✔️ with compat|      |✔️ with compat|      `GH-89419`_
+========================================================================================================================  ===================  ====================  ====================  ===========
+
+Physics
+^^^^^^^
+
+========================================================================================================================  ===================  ====================  ====================  ===========
+Change                                                                                                                    GDScript Compatible  C# Binary Compatible  C# Source Compatible  Introduced
+========================================================================================================================  ===================  ====================  ====================  ===========
+**PhysicsShapeQueryParameters3D**
+Property ``motion`` changes type from ``Vector2`` to ``Vector3``                                                          |❌|                 |❌|                  |❌|                  `GH-85393`_
+========================================================================================================================  ===================  ====================  ====================  ===========
+
+.. note::
+
+    In C#, the enum ``PhysicsServer3D.G6DofJointAxisFlag`` breaks compatibility because of the way the bindings generator
+    detects the enum prefix. New members were added in `GH-89851`_ to the enum that caused the enum members to be renamed.
+
+Rendering
+^^^^^^^^^
+
+========================================================================================================================  ===================  ====================  ====================  ===========
+Change                                                                                                                    GDScript Compatible  C# Binary Compatible  C# Source Compatible  Introduced
+========================================================================================================================  ===================  ====================  ====================  ===========
+**RenderingDevice**
+Enum field ``FinalAction.FINAL_ACTION_CONTINUE`` changes value from ``2`` to ``0``                                        |✔️|                 |❌|                  |❌|                  `GH-84976`_
+Enum field ``InitialAction.INITIAL_ACTION_CLEAR`` changes value from ``0`` to ``1``                                       |✔️|                 |❌|                  |❌|                  `GH-84976`_
+Enum field ``InitialAction.INITIAL_ACTION_CLEAR_REGION_CONTINUE`` changes value from ``2`` to ``1``                       |✔️|                 |❌|                  |❌|                  `GH-84976`_
+Enum field ``InitialAction.INITIAL_ACTION_CONTINUE`` changes value from ``5`` to ``0``                                    |✔️|                 |❌|                  |❌|                  `GH-84976`_
+Enum field ``InitialAction.INITIAL_ACTION_DROP`` changes value from ``4`` to ``2``                                        |✔️|                 |❌|                  |❌|                  `GH-84976`_
+Enum field ``InitialAction.INITIAL_ACTION_KEEP`` changes value from ``3`` to ``0``                                        |✔️|                 |❌|                  |❌|                  `GH-84976`_
+Method ``buffer_clear`` removes ``post_barrier`` parameter                                                                |✔️|                 |✔️ with compat|      |✔️ with compat|      `GH-84976`_
+Method ``buffer_update`` removes ``post_barrier`` parameter                                                               |✔️|                 |✔️ with compat|      |✔️ with compat|      `GH-84976`_
+Method ``compute_list_begin`` removes ``allow_draw_overlap`` parameter                                                    |✔️|                 |✔️ with compat|      |✔️ with compat|      `GH-84976`_
+Method ``compute_list_end`` removes ``post_barrier`` parameter                                                            |✔️|                 |✔️ with compat|      |✔️ with compat|      `GH-84976`_
+Method ``draw_list_begin`` removes ``storage_textures`` parameter                                                         |✔️|                 |✔️ with compat|      |✔️ with compat|      `GH-84976`_
+Method ``draw_list_end`` removes ``post_barrier`` parameter                                                               |✔️|                 |✔️ with compat|      |✔️ with compat|      `GH-84976`_
+Method ``texture_clear`` removes ``post_barrier`` parameter                                                               |✔️|                 |✔️ with compat|      |✔️ with compat|      `GH-84976`_
+Method ``texture_copy`` removes ``post_barrier`` parameter                                                                |✔️|                 |✔️ with compat|      |✔️ with compat|      `GH-84976`_
+Method ``texture_resolve_multisample`` removes ``post_barrier`` parameter                                                 |✔️|                 |✔️ with compat|      |✔️ with compat|      `GH-84976`_
+Method ``texture_update`` removes ``post_barrier`` parameter                                                              |✔️|                 |✔️ with compat|      |✔️ with compat|      `GH-84976`_
+**RenderingServer**
+Method ``environment_set_fog`` adds a new ``fog_mode`` optional parameter                                                 |✔️|                 |✔️ with compat|      |✔️|                  `GH-84792`_
+**RenderSceneBuffersRD**
+Method ``get_color_layer`` adds a new ``msaa`` optional parameter                                                         |✔️|                 |✔️ with compat|      |✔️|                  `GH-80214`_
+Method ``get_depth_layer`` adds a new ``msaa`` optional parameter                                                         |✔️|                 |✔️ with compat|      |✔️|                  `GH-80214`_
+Method ``get_velocity_layer`` adds a new ``msaa`` optional parameter                                                      |✔️|                 |✔️ with compat|      |✔️|                  `GH-80214`_
+Method ``get_color_texture`` adds a new ``msaa`` optional parameter                                                       |✔️|                 |✔️ with compat|      |✔️|                  `GH-80214`_
+Method ``get_depth_texture`` adds a new ``msaa`` optional parameter                                                       |✔️|                 |✔️ with compat|      |✔️|                  `GH-80214`_
+Method ``get_velocity_texture`` adds a new ``msaa`` optional parameter                                                    |✔️|                 |✔️ with compat|      |✔️|                  `GH-80214`_
+========================================================================================================================  ===================  ====================  ====================  ===========
+
+.. note::
+
+    While the values of the enum fields in ``RenderingDevice.InitialAction`` and ``RenderingDevice.FinalAction`` changed,
+    the only method that consumed them (``draw_list_begin``) added a compatibility method which supports the old values.
+    So in practice it doesn't break compatibility.
+
+.. note::
+
+    In C#, the enum ``RenderingDevice.DriverResource`` breaks compatibility because of the way the bindings generator
+    detects the enum prefix. New members were added in `GH-83452`_ to the enum that caused the enum members to be
+    renamed.
+
+Text
+^^^^
+
+========================================================================================================================  ===================  ====================  ====================  ===========
+Change                                                                                                                    GDScript Compatible  C# Binary Compatible  C# Source Compatible  Introduced
+========================================================================================================================  ===================  ====================  ====================  ===========
+**Font**
+Method ``find_variation`` adds a new ``baseline_offset`` optional parameter                                               |✔️|                 |✔️ with compat|      |✔️|                  `GH-87668`_
+**RichTextLabel**
+Method ``push_meta`` adds a new ``underline_mode`` optional parameter                                                     |✔️|                 |✔️ with compat|      |✔️|                  `GH-89024`_
+**TextServer**
+Method ``shaped_text_get_word_breaks`` adds a new optional ``skip_grapheme_flags`` parameter                              |✔️|                 |✔️ with compat|      |✔️|                  `GH-90732`_
+**TextServerExtension**
+Method ``_shaped_text_get_word_breaks`` adds a new ``skip_grapheme_flags`` parameter                                      |❌|                 |❌|                  |❌|                  `GH-90732`_
+========================================================================================================================  ===================  ====================  ====================  ===========
+
+Audio
+^^^^^
+
+========================================================================================================================  ===================  ====================  ====================  ===========
+Change                                                                                                                    GDScript Compatible  C# Binary Compatible  C# Source Compatible  Introduced
+========================================================================================================================  ===================  ====================  ====================  ===========
+**AudioStreamPlaybackPolyphonic**
+Method ``play_stream`` adds new ``playback_type``, and ``bus`` optional parameters                                        |✔️|                 |✔️ with compat|      |✔️|                  `GH-91382`_
+========================================================================================================================  ===================  ====================  ====================  ===========
+
+Navigation
+^^^^^^^^^^
+
+========================================================================================================================  ===================  ====================  ====================  ===========
+Change                                                                                                                    GDScript Compatible  C# Binary Compatible  C# Source Compatible  Introduced
+========================================================================================================================  ===================  ====================  ====================  ===========
+**AStar2D**
+Method ``get_id_path`` adds new ``allow_partial_path`` optional parameter                                                 |✔️|                 |✔️ with compat|      |✔️|                  `GH-88047`_
+Method ``get_point_path`` adds new ``allow_partial_path`` optional parameter                                              |✔️|                 |✔️ with compat|      |✔️|                  `GH-88047`_
+**AStar3D**
+Method ``get_id_path`` adds new ``allow_partial_path`` optional parameter                                                 |✔️|                 |✔️ with compat|      |✔️|                  `GH-88047`_
+Method ``get_point_path`` adds new ``allow_partial_path`` optional parameter                                              |✔️|                 |✔️ with compat|      |✔️|                  `GH-88047`_
+**AStarGrid2D**
+Method ``get_id_path`` adds new ``allow_partial_path`` optional parameter                                                 |✔️|                 |✔️ with compat|      |✔️|                  `GH-88047`_
+Method ``get_point_path`` adds new ``allow_partial_path`` optional parameter                                              |✔️|                 |✔️ with compat|      |✔️|                  `GH-88047`_
+**NavigationRegion2D**
+Property ``avoidance_layers`` removed                                                                                     |❌|                 |❌|                  |❌|                  `GH-90747`_
+Property ``constrain_avoidance`` removed                                                                                  |❌|                 |❌|                  |❌|                  `GH-90747`_
+Method ``get_avoidance_layer_value`` removed                                                                              |❌|                 |❌|                  |❌|                  `GH-90747`_
+Method ``set_avoidance_layer_value`` removed                                                                              |❌|                 |❌|                  |❌|                  `GH-90747`_
+========================================================================================================================  ===================  ====================  ====================  ===========
+
+.. note::
+
+    The constrain avoidance feature in ``NavigationRegion2D`` was experimental and has been discontinued with no
+    replacement.
+
+TileMap
+^^^^^^^
+
+========================================================================================================================  ===================  ====================  ====================  ===========
+Change                                                                                                                    GDScript Compatible  C# Binary Compatible  C# Source Compatible  Introduced
+========================================================================================================================  ===================  ====================  ====================  ===========
+**TileData**
+Method ``get_navigation_polygon`` adds new ``flip_h``, ``flip_v``, and ``transpose`` optional parameters                  |✔️|                 |✔️ with compat|      |✔️|                  `GH-84660`_
+Method ``get_occluder`` adds new ``flip_h``, ``flip_v``, and ``transpose`` optional parameters                            |✔️|                 |✔️ with compat|      |✔️|                  `GH-84660`_
+========================================================================================================================  ===================  ====================  ====================  ===========
+
+XR
+^^
+
+========================================================================================================================  ===================  ====================  ====================  ===========
+Change                                                                                                                    GDScript Compatible  C# Binary Compatible  C# Source Compatible  Introduced
+========================================================================================================================  ===================  ====================  ====================  ===========
+**WebXRInterface**
+Method ``get_input_source_tracker`` changes return type from ``XRPositionalTracker`` to ``XRControllerTracker``           |✔️|                 |❌|                  |✔️|                  `GH-90645`_
+**XRServer**
+Method ``get_tracker`` changes return type from ``XRPositionalTracker`` to ``XRTracker``                                  |✔️|                 |❌|                  |❌|                  `GH-90645`_
+========================================================================================================================  ===================  ====================  ====================  ===========
+
+Editor plugins
+^^^^^^^^^^^^^^
+
+========================================================================================================================  ===================  ====================  ====================  ===========
+Change                                                                                                                    GDScript Compatible  C# Binary Compatible  C# Source Compatible  Introduced
+========================================================================================================================  ===================  ====================  ====================  ===========
+**EditorInspectorPlugin**
+Method ``add_property_editor`` adds a new ``label`` optional parameter                                                    |✔️|                 |✔️ with compat|      |✔️|                  `GH-92322`_
+**EditorPlugin**
+Method ``add_control_to_bottom_panel`` adds a new ``shortcut`` optional parameter                                         |✔️|                 |✔️ with compat|      |✔️|                  `GH-88081`_
+Method ``add_control_to_dock`` adds a new ``shortcut`` optional parameter                                                 |✔️|                 |✔️ with compat|      |✔️|                  `GH-88081`_
+**EditorSceneFormatImporterFBX**
+Type renamed to ``EditorSceneFormatImporterFBX2GLTF``                                                                     |❌|                 |❌|                  |❌|                  `GH-81746`_
+========================================================================================================================  ===================  ====================  ====================  ===========
+
+Behavior changes
+----------------
+
+In 4.3 some behavior changes have been introduced, which might require you to adjust your project.
+
+Core
+^^^^
+
+.. note::
+
+    Binary serialization was modified to fix some issues with the serialization of scripted Objects and typed Arrays (`GH-78219`_).
+    This breaks compat with script encoding/decoding.
+
+.. note::
+
+    ``PackedByteArray`` is now able to use a more compact base64 encoding for storage. But the trade-off is that it breaks
+    compatibility, meaning that older versions of Godot may not be able to open resources saved by 4.3. (`GH-89186`_).
+
+    To maximize compatibility, this new storage format will only be enabled for resources and scenes that contain large
+    PackedByteArrays for now. Support for this new format will also be added in patch updates for older versions of Godot.
+    Once all supported Godot versions are able to read the new format, we will gradually retire the compatibility measures
+    and have all resources and scenes use the new storage format.
+
+.. note::
+
+    In C#, the ``Transform3D.InterpolateWith`` implementation was fixed to use the right order of operations, applying the rotation before the scale (`GH-89843`_).
+
+.. note::
+
+    In C#, the ``Aabb.GetSupport`` implementation was fixed to properly return the support vector (`GH-88919`_).
+
+.. note::
+
+    In C#, the Variant types' ``ToString`` implementation now defaults to using the ``InvariantCulture`` (`GH-89547`_)
+    which means ``Vector2(1.2, 3.4)`` is formatted using ``.`` as the decimal separator independently of the language
+    of the operating system that the program is running on.
+
+Animation
+^^^^^^^^^
+
+.. note::
+
+    ``AnimationMixer`` replaced its Capture mode with a new Capture feature that works much better than the old one,
+    this replaces the existing cache (`GH-86715`_).
+
+.. note::
+
+    ``AnimationNode`` has a reworked process for retrieving the semantic time info. This ensures that time-related
+    behavior works as expected, but changes the blending behavior. Implementors of the ``_process`` virtual method
+    should also note that this method is now deprecated and will be replaced by a new one in the future (`GH-87171`_).
+
+More information about the changes to Animation can be found in the
+`Migrating Animations from Godot 4.0 to 4.3 <https://godotengine.org/article/migrating-animations-from-godot-4-0-to-4-3>`__
+article.
+
+GUI nodes
+^^^^^^^^^
+
+.. note::
+
+    The default font outline color was changed from white to black. (`GH-54641`_).
+
+.. note::
+
+    The ``auto_translate`` property is deprecated in favor of the ``auto_translate_mode`` property which is now in ``Node`` (`GH-87530`_).
+    The default value for ``auto_translate_mode`` is ``AUTO_TRANSLATE_INHERIT``, which means nodes inherit the ``auto_translate_mode`` value
+    from their parent. This means, existing nodes with the ``auto_translate`` property set to ``true`` may no longer be translated if they
+    are children of a node with the ``auto_translate`` property set to ``false``.
+
+Rendering
+^^^^^^^^^
+
+.. note::
+
+    Decals now convert the modulate color from an sRGB color to a linear color, like all other inputs, to ensure proper
+    blending (`GH-89849`_). Existing projects that were using the decal's modulate property will notice a change in
+    their visuals.
+
+.. note::
+
+    The reverse Z depth buffer technique is now implemented. This may break compatibility for some shaders.
+    Read the `Introducing Reverse Z (AKA I'm sorry for breaking your shader) <https://godotengine.org/article/introducing-reverse-z/>`__
+    article for more information and guidance on how to fix common scenarios.
+
+TileMap
+^^^^^^^
+
+.. note::
+
+    ``TileMap`` layers were moved to individual nodes (`GH-87379`_ and `GH-89179`_).
+
+Android
+^^^^^^^
+
+.. note::
+
+    Android permissions are no longer requested automatically because it goes against the recommended best practices (`GH-87080`_).
+    Use the ``request_permission`` method in ``OS`` and the ``on_request_permissions_result`` signal on ``MainLoop`` to request
+    permissions and wait for the user response.
+
+.. |❌| 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-54641: https://github.com/godotengine/godot/pull/54641
+.. _GH-78219: https://github.com/godotengine/godot/pull/78219
+.. _GH-80214: https://github.com/godotengine/godot/pull/80214
+.. _GH-81746: https://github.com/godotengine/godot/pull/81746
+.. _GH-83452: https://github.com/godotengine/godot/pull/83452
+.. _GH-84660: https://github.com/godotengine/godot/pull/84660
+.. _GH-84792: https://github.com/godotengine/godot/pull/84792
+.. _GH-84976: https://github.com/godotengine/godot/pull/84976
+.. _GH-85393: https://github.com/godotengine/godot/pull/85393
+.. _GH-86629: https://github.com/godotengine/godot/pull/86629
+.. _GH-86661: https://github.com/godotengine/godot/pull/86661
+.. _GH-86687: https://github.com/godotengine/godot/pull/86687
+.. _GH-86715: https://github.com/godotengine/godot/pull/86715
+.. _GH-87080: https://github.com/godotengine/godot/pull/87080
+.. _GH-87171: https://github.com/godotengine/godot/pull/87171
+.. _GH-87379: https://github.com/godotengine/godot/pull/87379
+.. _GH-87530: https://github.com/godotengine/godot/pull/87530
+.. _GH-87668: https://github.com/godotengine/godot/pull/87668
+.. _GH-87888: https://github.com/godotengine/godot/pull/87888
+.. _GH-88047: https://github.com/godotengine/godot/pull/88047
+.. _GH-88081: https://github.com/godotengine/godot/pull/88081
+.. _GH-88418: https://github.com/godotengine/godot/pull/88418
+.. _GH-88791: https://github.com/godotengine/godot/pull/88791
+.. _GH-88919: https://github.com/godotengine/godot/pull/88919
+.. _GH-89024: https://github.com/godotengine/godot/pull/89024
+.. _GH-89179: https://github.com/godotengine/godot/pull/89179
+.. _GH-89186: https://github.com/godotengine/godot/pull/89186
+.. _GH-89419: https://github.com/godotengine/godot/pull/89419
+.. _GH-89547: https://github.com/godotengine/godot/pull/89547
+.. _GH-89843: https://github.com/godotengine/godot/pull/89843
+.. _GH-89849: https://github.com/godotengine/godot/pull/89849
+.. _GH-89851: https://github.com/godotengine/godot/pull/89851
+.. _GH-90575: https://github.com/godotengine/godot/pull/90575
+.. _GH-90645: https://github.com/godotengine/godot/pull/90645
+.. _GH-90732: https://github.com/godotengine/godot/pull/90732
+.. _GH-90747: https://github.com/godotengine/godot/pull/90747
+.. _GH-91382: https://github.com/godotengine/godot/pull/91382
+.. _GH-92322: https://github.com/godotengine/godot/pull/92322
+.. _GH-92861: https://github.com/godotengine/godot/pull/92861