.. _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 runtime 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``. Multiplayer ~~~~~~~~~~~ .. note:: The ``SceneMultiplayer`` caching protocol was changed to send the received ID instead of the Node path when sending a node removal confirmation packet (`GH-90027`_). This is a breaking change for the high-level multiplayer protocol making it incompatible with previous Godot versions. Upgrade both your server and client versions to Godot 4.3 to handle this change gracefully. Note that high-level multiplayer facilities are only ever meant to be compatible with server and client using the same Godot version. It is recommended to implement some kind of version checking. 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-90027: https://github.com/godotengine/godot/pull/90027 .. _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