From 305eca6f513363642a2c1371f84d8cf108e2a547 Mon Sep 17 00:00:00 2001 From: Raul Santos Date: Fri, 19 Apr 2024 02:55:37 +0200 Subject: [PATCH] Add "Upgrading from Godot 4.2 to Godot 4.3" page --- tutorials/migrating/index.rst | 1 + .../migrating/upgrading_to_godot_4.3.rst | 366 ++++++++++++++++++ 2 files changed, 367 insertions(+) create mode 100644 tutorials/migrating/upgrading_to_godot_4.3.rst diff --git a/tutorials/migrating/index.rst b/tutorials/migrating/index.rst index 01653803f0f..90291dc2136 100644 --- a/tutorials/migrating/index.rst +++ b/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 diff --git a/tutorials/migrating/upgrading_to_godot_4.3.rst b/tutorials/migrating/upgrading_to_godot_4.3.rst new file mode 100644 index 00000000000..1c68731c639 --- /dev/null +++ b/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 `__ +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) `__ + 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