diff --git a/tutorials/migrating/index.rst b/tutorials/migrating/index.rst index 8c250356025..aace1cd7402 100644 --- a/tutorials/migrating/index.rst +++ b/tutorials/migrating/index.rst @@ -19,3 +19,4 @@ path. upgrading_to_godot_4 upgrading_to_godot_4.1 + upgrading_to_godot_4.2 diff --git a/tutorials/migrating/upgrading_to_godot_4.2.rst b/tutorials/migrating/upgrading_to_godot_4.2.rst new file mode 100644 index 00000000000..158495db370 --- /dev/null +++ b/tutorials/migrating/upgrading_to_godot_4.2.rst @@ -0,0 +1,250 @@ +.. _doc_upgrading_to_godot_4.2: + +Upgrading from Godot 4.1 to Godot 4.2 +===================================== + +For most games and apps made with 4.1 it should be relatively safe to migrate to 4.2. +This page intends to cover everything you need to pay attention to when migrating +your project. + +Breaking changes +---------------- + +If you are migrating from 4.1 to 4.2, the breaking changes listed here might +affect you. Changes are grouped by areas/systems. + +.. warning:: + + The :ref:`class_Mesh` resource format has changed in 4.2 to allow for + `vertex and attribute compression `__. + This allows for improved rendering performance, especially on platforms + constrained by memory bandwidth such as mobile. + + It is still possible to load the Godot 4.0-4.1 Mesh formats, but it is + **not** possible to load the Godot 4.2 Mesh format in prior Godot versions. + When opening a Godot project made with a version prior to 4.2, you may + be presented with an upgrade dialog that offers two options: + + - **Restart & Upgrade:** Upgrades the mesh format for all meshes in the + project and saves the result to disk. Once chosen, this option prevents + downgrading the project to a Godot version prior to 4.2. Set up a + version control system and push your changes *before* choosing this option! + - **Upgrade Only:** Upgrades the mesh format in-memory without writing it + to disk. This allows downgrading the project to a Godot version older than 4.2 + if you need to do so in the future. The downside is that loading the project + will be slower every time as the mesh format needs to be upgraded every time + the project is loaded. These increased loading times will also affect the + exported project. The number and complexity of Mesh resources determines + how much loading times are affected. + + If this dialog doesn't appear, use **Project > Tools > Upgrade Mesh Surfaces…** + at the top of the editor. + +This article indicates whether each breaking change affects GDScript and whether +the C# breaking change is *binary compatible* or *source compatible*: + +- **Binary compatible** - Existing binaries will load and execute successfully without + recompilation, and the run-time behavior won't change. +- **Source compatible** - Source code will compile successfully without changes when + upgrading Godot. + +Core +^^^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**Node** +Constant ``NOTIFICATION_NODE_RECACHE_REQUESTED`` removed |❌| |✔️| |❌| `GH-84419`_ +======================================================================================================================== =================== ==================== ==================== =========== + +Animation +^^^^^^^^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**AnimationPlayer** +Method ``_post_process_key_value`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``add_animation_library`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``advance`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Signal ``animation_finished`` moved to base class ``AnimationMixer`` |✔️| |❌| |❌| `GH-80813`_ +Signal ``animation_started`` moved to base class ``AnimationMixer`` |✔️| |❌| |❌| `GH-80813`_ +Signal ``animation_libraries_updated`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Signal ``animation_list_changed`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Property ``audio_max_polyphony`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Signal ``caches_cleared`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``clear_caches`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``find_animation`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``find_animation_library`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``get_animation`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``get_animation_library`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``get_animation_library_list`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``get_animation_list`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``has_animation`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``has_animation_library`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Property ``method_call_mode`` renamed to ``callback_mode_method`` and moved to base class ``AnimationMixer`` |✔️| |✔️ with compat| |✔️ with compat| `GH-80813`_ +Property ``playback_active`` renamed to ``active`` and moved to base class ``AnimationMixer`` |✔️| |✔️ with compat| |✔️ with compat| `GH-80813`_ +Property ``playback_process_mode`` renamed to ``callback_mode_process`` and moved to base class ``AnimationMixer`` |✔️| |✔️ with compat| |✔️ with compat| `GH-80813`_ +Method ``remove_animation_library`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``rename_animation_library`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Property ``reset_on_save`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Property ``root_node`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``set_reset_on_save_enabled`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``seek`` adds a new ``update_only`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-80813`_ +**AnimationTree** +Method ``_post_process_key_value`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Property ``active`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``advance`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Signal ``animation_finished`` moved to base class ``AnimationMixer`` |✔️| |❌| |❌| `GH-80813`_ +Signal ``animation_started`` moved to base class ``AnimationMixer`` |✔️| |❌| |❌| `GH-80813`_ +Property ``audio_max_polyphony`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``get_root_motion_position`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``get_root_motion_position_accumulator`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``get_root_motion_rotation`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``get_root_motion_rotation_accumulator`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``get_root_motion_scale`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Method ``get_root_motion_scale_accumulator`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Property ``process_callback`` renamed to ``callback_mode_process`` and moved to base class ``AnimationMixer`` |✔️| |✔️ with compat| |✔️ with compat| `GH-80813`_ +Property ``root_motion_track`` moved to base class ``AnimationMixer`` |✔️| |✔️| |✔️| `GH-80813`_ +Property ``tree_root`` changes type from ``AnimationNode`` to ``AnimationRootNode`` |✔️| |❌| |❌| `GH-80813`_ +======================================================================================================================== =================== ==================== ==================== =========== + +GUI nodes +^^^^^^^^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**PopupMenu** +Method ``add_icon_shortcut`` adds a new ``allow_echo`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-36493`_ +Method ``add_shortcut`` adds a new ``allow_echo`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-36493`_ +Method ``clear`` adds a new ``free_submenus`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-79965`_ +**RichTextLabel** +Method ``add_image`` adds new ``key``, ``pad``, ``tooltip``, and ``size_in_percent`` optional parameters |✔️| |✔️ with compat| |✔️| `GH-80410`_ +======================================================================================================================== =================== ==================== ==================== =========== + +Rendering +^^^^^^^^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**ImporterMesh** +Method ``add_surface`` changes ``flags`` parameter type from ``uint32`` to ``uint64`` |✔️| |✔️ with compat| |✔️ with compat| `GH-81138`_ +Method ``get_surface_format`` changes return type from ``uint32`` to ``uint64`` |✔️| |❌| |❌| `GH-81138`_ +**MeshDataTool** +Method ``commit_to_surface`` adds a new ``compression_flags`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-81138`_ +Method ``get_format`` changes return type from ``uint32`` to ``uint64`` |✔️| |❌| |❌| `GH-81138`_ +**RenderingDevice** +Enum field ``BarrierMask.BARRIER_MASK_RASTER`` changes value from ``1`` to ``9`` |✔️| |✔️| |✔️| `GH-79911`_ +Enum field ``BarrierMask.BARRIER_MASK_ALL_BARRIERS`` changes value from ``7`` to ``32767`` |✔️| |✔️| |✔️| `GH-79911`_ +Enum field ``BarrierMask.BARRIER_MASK_NO_BARRIER`` changes value from ``8`` to ``32768`` |✔️| |✔️| |✔️| `GH-79911`_ +Method ``shader_create_from_bytecode`` adds a new ``placeholder_rid`` optional parameter |✔️| |✔️ with compat| |✔️| `GH-79606`_ +Method ``shader_get_vertex_input_attribute_ask`` changes return type from ``uint32`` to ``uint64`` |✔️| |❌| |❌| `GH-81138`_ +**SurfaceTool** +Method ``commit`` changes ``flags`` parameter type from ``uint32`` to ``uint64`` |✔️| |✔️ with compat| |✔️ with compat| `GH-81138`_ +======================================================================================================================== =================== ==================== ==================== =========== + +Text +^^^^ + +==================================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +==================================================================================================================================== =================== ==================== ==================== =========== +**Font** +Method ``set_fallbacks`` replaced with ``fallbacks`` property |✔️| |❌| |❌| `GH-78266`_ +Method ``get_fallbacks`` replaced with ``fallbacks`` property |✔️| |❌| |❌| `GH-78266`_ +Method ``find_variation`` adds new ``spacing_top``, ``spacing_bottom``, ``spacing_space``, and ``spacing_glyph`` optional parameters |✔️| |✔️ with compat| |✔️| `GH-80954`_ +==================================================================================================================================== =================== ==================== ==================== =========== + +GraphEdit +^^^^^^^^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**GraphEdit** +Property ``arrange_nodes_button_hidden`` renamed to ``show_arrange_button`` |❌| |✔️ with compat| |✔️ with compat| `GH-81582`_ +Method ``get_zoom_hbox`` renamed to ``get_menu_hbox`` |❌| |✔️ with compat| |✔️ with compat| `GH-79308`_ +Property ``snap_distance`` renamed to ``snapping_distance`` |❌| |✔️ with compat| |✔️ with compat| `GH-79308`_ +Property ``use_snap`` renamed to ``snapping_enabled`` |❌| |✔️ with compat| |✔️ with compat| `GH-79308`_ +**GraphNode** +Property ``comment`` removed |❌| |❌| |❌| `GH-79307`_ +Signal ``close_request`` renamed to ``delete_request`` and moved to base class ``GraphElement`` |❌| |✔️ with compat| |✔️ with compat| `GH-79311`_ +Property ``draggable`` moved to base class ``GraphElement`` |✔️| |✔️| |✔️| `GH-79311`_ +Property ``draggable`` moved to base class ``GraphElement`` |✔️| |✔️| |✔️| `GH-79311`_ +Signal ``dragged`` moved to base class ``GraphElement`` |✔️| |❌| |❌| `GH-79311`_ +Method ``get_connection_input_color`` removed |❌| |❌| |❌| `GH-79311`_ +Method ``get_connection_input_count`` removed |❌| |❌| |❌| `GH-79311`_ +Method ``get_connection_input_height`` removed |❌| |❌| |❌| `GH-79311`_ +Method ``get_connection_input_position`` removed |❌| |❌| |❌| `GH-79311`_ +Method ``get_connection_input_slot`` removed |❌| |❌| |❌| `GH-79311`_ +Method ``get_connection_input_type`` removed |❌| |❌| |❌| `GH-79311`_ +Method ``get_connection_output_color`` removed |❌| |❌| |❌| `GH-79311`_ +Method ``get_connection_output_count`` removed |❌| |❌| |❌| `GH-79311`_ +Method ``get_connection_output_height`` removed |❌| |❌| |❌| `GH-79311`_ +Method ``get_connection_output_position`` removed |❌| |❌| |❌| `GH-79311`_ +Method ``get_connection_output_slot`` removed |❌| |❌| |❌| `GH-79311`_ +Method ``get_connection_output_type`` removed |❌| |❌| |❌| `GH-79311`_ +Property ``language`` removed |❌| |❌| |❌| `GH-79311`_ +Signal ``node_deselected`` moved to base class ``GraphElement`` |✔️| |✔️| |✔️| `GH-79311`_ +Signal ``node_selected`` moved to base class ``GraphElement`` |✔️| |✔️| |✔️| `GH-79311`_ +Property ``overlay`` removed |❌| |❌| |❌| `GH-79311`_ +Property ``position_offset`` moved to base class ``GraphElement`` |✔️| |✔️| |✔️| `GH-79311`_ +Signal ``position_offset_changed`` moved to base class ``GraphElement`` |✔️| |✔️| |✔️| `GH-79311`_ +Signal ``raise_request`` moved to base class ``GraphElement`` |✔️| |✔️| |✔️| `GH-79311`_ +Property ``resizable`` moved to base class ``GraphElement`` |✔️| |✔️| |✔️| `GH-79311`_ +Signal ``resize_request`` moved to base class ``GraphElement`` |✔️| |❌| |❌| `GH-79311`_ +Property ``selectable`` moved to base class ``GraphElement`` |✔️| |✔️| |✔️| `GH-79311`_ +Property ``selected`` moved to base class ``GraphElement`` |✔️| |✔️| |✔️| `GH-79311`_ +Property ``show_close`` removed |❌| |❌| |❌| `GH-79311`_ +Property ``text_direction`` removed |❌| |❌| |❌| `GH-79311`_ +======================================================================================================================== =================== ==================== ==================== =========== + +TileMap +^^^^^^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**TileMap** +Property ``cell_quadrant_size`` renamed to ``rendering_quadrant_size`` |❌| |✔️ with compat| |✔️ with compat| `GH-81070`_ +======================================================================================================================== =================== ==================== ==================== =========== + +XR +^^ + +======================================================================================================================== =================== ==================== ==================== =========== +Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced +======================================================================================================================== =================== ==================== ==================== =========== +**XRInterface** +Property ``environment_blend_mode`` added |✔️| |❌| |❌| `GH-81561`_ +======================================================================================================================== =================== ==================== ==================== =========== + +.. note:: + + This change breaks compatibility in C# because the new property conflicts with the name of an existing enum + and the C# bindings generator gives priority to properties, so the enum type was renamed from + ``EnvironmentBlendMode`` to ``EnvironmentBlendModeEnum``. + +.. |❌| 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-36493: https://github.com/godotengine/godot/pull/36493 +.. _GH-78266: https://github.com/godotengine/godot/pull/78266 +.. _GH-79307: https://github.com/godotengine/godot/pull/79307 +.. _GH-79308: https://github.com/godotengine/godot/pull/79308 +.. _GH-79311: https://github.com/godotengine/godot/pull/79311 +.. _GH-79606: https://github.com/godotengine/godot/pull/79606 +.. _GH-79911: https://github.com/godotengine/godot/pull/79911 +.. _GH-79965: https://github.com/godotengine/godot/pull/79965 +.. _GH-80410: https://github.com/godotengine/godot/pull/80410 +.. _GH-80813: https://github.com/godotengine/godot/pull/80813 +.. _GH-80954: https://github.com/godotengine/godot/pull/80954 +.. _GH-81070: https://github.com/godotengine/godot/pull/81070 +.. _GH-81138: https://github.com/godotengine/godot/pull/81138 +.. _GH-81561: https://github.com/godotengine/godot/pull/81561 +.. _GH-81582: https://github.com/godotengine/godot/pull/81582 +.. _GH-84419: https://github.com/godotengine/godot/pull/84419