From cb415a51d93736e39b54bfdf5ba59366ed89a023 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Sun, 6 Nov 2022 01:50:49 +0100 Subject: [PATCH 1/3] Add a Godot 3 to Godot 4 upgrade guide --- about/release_policy.rst | 6 +- tutorials/editor/index.rst | 9 + tutorials/editor/upgrading_to_godot_4.rst | 524 ++++++++++++++++++++++ 3 files changed, 538 insertions(+), 1 deletion(-) create mode 100644 tutorials/editor/upgrading_to_godot_4.rst diff --git a/about/release_policy.rst b/about/release_policy.rst index f6a790863c3..765a48a14b4 100644 --- a/about/release_policy.rst +++ b/about/release_policy.rst @@ -88,7 +88,7 @@ on GitHub. +-------------+----------------------+--------------------------------------------------------------------------+ | **Version** | **Release date** | **Support level** | +-------------+----------------------+--------------------------------------------------------------------------+ -| Godot 4.0 | Q4 2022 | |unstable| *Alpha.* Current focus of development (unstable). | +| Godot 4.0 | Q4 2022 | |unstable| *Beta.* Current focus of development (unstable). | +-------------+----------------------+--------------------------------------------------------------------------+ | Godot 3.6 | Q4 2022 | |supported| *Beta.* Receives new features as well as bug fixes while | | | | under development. | @@ -130,6 +130,10 @@ on GitHub. Pre-release Godot versions aren't intended to be used in production and are provided for testing purposes only. +.. seealso:: + + See :ref:`doc_upgrading_to_godot_4` for instructions on migrating a project. + .. _doc_release_policy_when_is_next_release_out: When is the next release out? diff --git a/tutorials/editor/index.rst b/tutorials/editor/index.rst index b0a0fcf5927..0a3cf2e3d9e 100644 --- a/tutorials/editor/index.rst +++ b/tutorials/editor/index.rst @@ -61,3 +61,12 @@ a project that's only 2D or only 3D and don't want to see what you don't need. :name: toc-editor-features managing_editor_features + +Upgrading to Godot 4 +-------------------- + +.. toctree:: + :maxdepth: 1 + :name: toc-editor-upgrading + + upgrading_to_godot_4 diff --git a/tutorials/editor/upgrading_to_godot_4.rst b/tutorials/editor/upgrading_to_godot_4.rst new file mode 100644 index 00000000000..ab30857c9a8 --- /dev/null +++ b/tutorials/editor/upgrading_to_godot_4.rst @@ -0,0 +1,524 @@ +.. _doc_upgrading_to_godot_4: + +Upgrading to Godot 4 +==================== + +TODO: https://github.com/godotengine/godot-proposals/issues/387#issuecomment-1251909261 + +Should I upgrade to Godot 4? +---------------------------- + +Before beginning the upgrade process, it's worth thinking about the advantages +and disadvantages that upgrading would bring to your project. + +Advantages of upgrading +^^^^^^^^^^^^^^^^^^^^^^^ + +Along with the new features present in 4.0, upgrading gives the following advantages: + +- Many bugs are fixed in 4.0, but cannot be resolved in 3.x for various reasons + (such as graphics API differences or backwards compatibility). +- 4.x will enjoy a longer :ref:`support period `. Godot 3.x + will continue to be supported for some time after 4.0 is released, but it will + eventually stop receiving support. + +Disadvantages of upgrading +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you don't *need* any features present in Godot 4.0, you may want to stay on +Godot 3.x for the following reasons: + +- Godot 4's baseline hardware requirements (such as memory usage) are slightly + higher, both for the editor and exported projects. This was required for the + implementation of some core optimizations. +- Godot 4 does not and will not have support for GLES2 rendering. + (There is still support for GLES3 rendering using the new OpenGL backend, + which means that devices without Vulkan support can still run Godot 4.) + + - If you are targeting **very** old hardware such as Intel Sandy Bridge (2nd + generation) integrated graphics, this will prevent the project from running + on such hardware after upgrading. + `Software OpenGL implementations `__ + can be used to bypass this limitation, but they're too slow for gaming. + +Running the project upgrade tool +-------------------------------- + +.. warning:: + + **Make a full backup of your project** before upgrading! The project upgrade + tool will *not* perform any backups of the project that is being upgraded. + + You can backup a project by using version control, or by copying the project + folder to another location. + +To use the project upgrade tool: + +1. Open the Godot 4 project manager. +2. Import the Godot 3.x project using the **Import** button, or use the **Scan** + button to find the project within a folder. +3. Double-click the imported project (or select the project then choose **Edit**). +4. You will see a dialog appearing with two options: **Convert project.godot + Only** and **Convert Full Project**. After ensuring your project is backed up + (see the above warning), choose **Convert Full Project**. **Convert + project.godot Only** is intended to be used for advanced use cases *only*, in + case the conversion tool fails. +5. Wait until the project conversion process finishes. This can take up to a few + minutes for large projects with lots of scenes. +6. When the project manager interface becomes available again, double-click the + project (or select the project then choose **Edit**) to open it in the + editor. + +.. note:: + + Only Godot 3.0 and later projects can be upgraded using the project + conversion tool found in the Godot 4 editor. + + Projects made using Godot versions older than 3.0 must follow a 2-step + process: + + 1. Upgrade the project to Godot 3 using the **Tools > Export to Godot 3.0** + option in the Godot 2.1.6 editor. Open the upgraded project in the Godot + 3.x editor, then manually fix the project to make sure it looks and + runs correctly. + 2. Only *after* performing step 1, you may upgrade the project to Godot 4. + +Fixing the project after running the project upgrade tool +--------------------------------------------------------- + +After upgrading the project, you may notice that certain things don't look as +they should. Scripts will likely contain various errors as well (possibly +hundreds in large projects). This is because the project upgrade tool cannot +cater to all situations. Therefore, a large part of the upgrade process remains +manual. + +Automatically renamed nodes and resources +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The list below refers to the nodes' new names in Godot 4.0. In the transition +between Godot 3.x and 4.0, dozens of nodes were renamed. 3D nodes had a ``3D`` +prefix added to them for consistency with their 2D counterparts. This conversion +is automatic. + +For ease of searching, this table lists all nodes and resources that were +renamed in a way that does not involve only adding a ``3D`` suffix to the old name: + ++-----------------------------------------+-------------------------------------------+ +| Old name (Godot 3.x) | New name (Godot 4) | ++=========================================+===========================================+ +| AnimatedSprite | AnimatedSprite2D | ++-----------------------------------------+-------------------------------------------+ +| ARVRCamera | XRCamera3D | ++-----------------------------------------+-------------------------------------------+ +| ARVRController | XRController3D | ++-----------------------------------------+-------------------------------------------+ +| ARVRAnchor | XRAnchor3D | ++-----------------------------------------+-------------------------------------------+ +| ARVRInterface | XRInterface | ++-----------------------------------------+-------------------------------------------+ +| ARVROrigin | XROrigin3D | ++-----------------------------------------+-------------------------------------------+ +| ARVRPositionalTracker | XRPositionalTracker | ++-----------------------------------------+-------------------------------------------+ +| ARVRServer | XRServer | ++-----------------------------------------+-------------------------------------------+ +| CubeMesh | BoxMesh | ++-----------------------------------------+-------------------------------------------+ +| EditorSpatialGizmo | EditorNode3DGizmo | ++-----------------------------------------+-------------------------------------------+ +| EditorSpatialGizmoPlugin | EditorNode3DGizmoPlugin | ++-----------------------------------------+-------------------------------------------+ +| GIProbe | VoxelGI | ++-----------------------------------------+-------------------------------------------+ +| GIProbeData | VoxelGIData | ++-----------------------------------------+-------------------------------------------+ +| GradientTexture | GradientTexture1D | ++-----------------------------------------+-------------------------------------------+ +| KinematicBody | CharacterBody3D | ++-----------------------------------------+-------------------------------------------+ +| KinematicBody2D | CharacterBody2D | ++-----------------------------------------+-------------------------------------------+ +| Light2D | PointLight2D | ++-----------------------------------------+-------------------------------------------+ +| LineShape2D | WorldBoundaryShape2D | ++-----------------------------------------+-------------------------------------------+ +| Listener | AudioListener3D | ++-----------------------------------------+-------------------------------------------+ +| NavigationMeshInstance | NavigationRegion3D | ++-----------------------------------------+-------------------------------------------+ +| NavigationPolygonInstance | NavigationRegion2D | ++-----------------------------------------+-------------------------------------------+ +| Navigation2DServer | NavigationServer2D | ++-----------------------------------------+-------------------------------------------+ +| PanoramaSky | Sky | ++-----------------------------------------+-------------------------------------------+ +| Particles | GPUParticles3D | ++-----------------------------------------+-------------------------------------------+ +| Particles2D | GPUParticles2D | ++-----------------------------------------+-------------------------------------------+ +| ParticlesMaterial | ParticleProcessMaterial | ++-----------------------------------------+-------------------------------------------+ +| Physics2DDirectBodyState | PhysicsDirectBodyState2D | ++-----------------------------------------+-------------------------------------------+ +| Physics2DDirectSpaceState | PhysicsDirectSpaceState2D | ++-----------------------------------------+-------------------------------------------+ +| Physics2DServer | PhysicsServer2D | ++-----------------------------------------+-------------------------------------------+ +| Physics2DShapeQueryParameters | PhysicsShapeQueryParameters2D | ++-----------------------------------------+-------------------------------------------+ +| Physics2DTestMotionResult | PhysicsTestMotionResult2D | ++-----------------------------------------+-------------------------------------------+ +| PhysicsDirectBodyState | PhysicsDirectBodyState3D | ++-----------------------------------------+-------------------------------------------+ +| PhysicsDirectSpaceState | PhysicsDirectSpaceState3D | ++-----------------------------------------+-------------------------------------------+ +| PlaneShape | WorldBoundaryShape3D | ++-----------------------------------------+-------------------------------------------+ +| Position2D | Marker2D | ++-----------------------------------------+-------------------------------------------+ +| Position3D | Marker3D | ++-----------------------------------------+-------------------------------------------+ +| ProceduralSky | Sky | ++-----------------------------------------+-------------------------------------------+ +| RayShape | SeparationRayShape3D | ++-----------------------------------------+-------------------------------------------+ +| RayShape2D | SeparationRayShape2D | ++-----------------------------------------+-------------------------------------------+ +| ShortCut | Shortcut | ++-----------------------------------------+-------------------------------------------+ +| Spatial | Node3D | ++-----------------------------------------+-------------------------------------------+ +| SpatialGizmo | Node3DGizmo | ++-----------------------------------------+-------------------------------------------+ +| SpatialMaterial | StandardMaterial3D | ++-----------------------------------------+-------------------------------------------+ +| Sprite | Sprite2D | ++-----------------------------------------+-------------------------------------------+ +| StreamTexture | CompressedTexture2D | ++-----------------------------------------+-------------------------------------------+ +| TextureProgress | TextureProgressBar | ++-----------------------------------------+-------------------------------------------+ +| VideoPlayer | VideoStreamPlayer | ++-----------------------------------------+-------------------------------------------+ +| ViewportContainer | SubViewportContainer | ++-----------------------------------------+-------------------------------------------+ +| Viewport | SubViewport | ++-----------------------------------------+-------------------------------------------+ +| VisibilityEnabler | VisibleOnScreenEnabler3D | ++-----------------------------------------+-------------------------------------------+ +| VisibilityNotifier | VisibleOnScreenNotifier3D | ++-----------------------------------------+-------------------------------------------+ +| VisibilityNotifier2D | VisibleOnScreenNotifier2D | ++-----------------------------------------+-------------------------------------------+ +| VisibilityNotifier3D | VisibleOnScreenNotifier3D | ++-----------------------------------------+-------------------------------------------+ +| VisualServer | RenderingServer | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeScalarConstant | VisualShaderNodeFloatConstant | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeScalarFunc | VisualShaderNodeFloatFunc | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeScalarOp | VisualShaderNodeFloatOp | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeScalarClamp | VisualShaderNodeClamp | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeVectorClamp | VisualShaderNodeClamp | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeScalarInterp | VisualShaderNodeMix | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeVectorInterp | VisualShaderNodeMix | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeVectorScalarMix | VisualShaderNodeMix | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeScalarSmoothStep | VisualShaderNodeSmoothStep | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeVectorSmoothStep | VisualShaderNodeSmoothStep | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeVectorScalarSmoothStep | VisualShaderNodeSmoothStep | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeVectorScalarStep | VisualShaderNodeStep | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeScalarSwitch | VisualShaderNodeSwitch | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeScalarTransformMult | VisualShaderNodeTransformOp | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeScalarDerivativeFunc | VisualShaderNodeDerivativeFunc | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeVectorDerivativeFunc | VisualShaderNodeDerivativeFunc | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeBooleanUniform | VisualShaderNodeBooleanParameter | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeColorUniform | VisualShaderNodeColorParameter | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeScalarUniform | VisualShaderNodeFloatParameter | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeCubeMapUniform | VisualShaderNodeCubeMapParameter | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeTextureUniform | VisualShaderNodeTexture2DParameter | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeTextureUniformTriplanar | VisualShaderNodeTextureParameterTriplanar | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeTransformUniform | VisualShaderNodeTransformParameter | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeVec3Uniform | VisualShaderNodeVec3Parameter | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeUniform | VisualShaderNodeParameter | ++-----------------------------------------+-------------------------------------------+ +| VisualShaderNodeUniformRef | VisualShaderNodeParameterRef | ++-----------------------------------------+-------------------------------------------+ + +If you cannot find a node or resource in the list below, refer to the above +table to find its new name. + +.. _doc_upgrading_to_godot_4_manual_rename: + +Manually renaming methods, properties, signals and constants +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Due to how the project upgrade tool works, not all +:abbr:`API (Application Programming Interface)` renames can be performed automatically. + + +.. tip:: + + You can use the **Replace in Files** dialog to speed up replacement by pressing + :kbd:`Ctrl + Shift + R` while the script editor is open. However, be careful + as the Replace in Files dialog doesn't offer any way to undo a replacement. + Use version control to commit your upgrade work regularly. + Command line tools such as `sd `__ can also be used + if you need something more flexible than the editor's Replace in Files dialog. + + If using C#, remember to search for outdated API usage with PascalCase + notation in the project (and perform the replacement with PascalCase + notation). + +**Methods** + +- File and Directory classes were replaced by :ref:`class_FileAccess` and + :ref:`class_DirAccess`, which have an entirely different API. Several methods + are now static, which means you can call them directly on FileAccess or + DirAccess without having to create an instance of that class. +- Screen and window-related methods from the :ref:`class_OS` singleton (such as + ``OS.get_screen_size()``) were moved to the :ref:`class_DisplayServer` singleton. + Method naming was also changed to use the + ``DisplayServer.__property()`` form instead. For example, + ``OS.get_screen_size()`` becomes ``DisplayServer.screen_get_size()``. +- Time and date methods from the :ref:`class_OS` singleton were moved to the + :ref:`class_Time` singleton. + (The Time singleton is also available in Godot 3.5 and later.) +- You may have to replace some ``instance()`` calls with ``instantiate()``. The + converter *should* handle this automatically, but this relies on custom code that + may not work in 100% of situations. +- AcceptDialog's ``set_autowrap()`` is now ``set_autowrap_mode()``. +- AnimationNode's ``process()`` is now ``_process()`` + (note the leading underscore, which denotes a virtual method). +- AStar2D and AStar3D's ``get_points()`` is now ``get_points_id()``. +- BaseButton's ``set_event()`` is now ``set_shortcut()``. +- Camera2D's ``get_v_offset()`` is now ``get_drag_vertical_offset()``. +- Camera2D's ``set_v_offset()`` is now ``set_drag_vertical_offset()``. +- Camera2D's ``make_current()`` is now ``set_current()``. +- Control's ``set_tooltip()`` is now ``set_tooltip_text()``. +- EditorNode3DGizmoPlugin's ``create_gizmo()`` is now ``_create_gizmo()`` + (note the leading underscore, which denotes a virtual method). +- ENetMultiplayerPeer's ``get_peer_port()`` is now ``get_peer()``. +- FileDialog's ``get_mode()`` is now ``get_file_mode()``. +- FileDialog's ``set_mode()`` is now ``set_file_mode()``. +- GraphNode's ``get_offset()`` is now ``get_position_offset()``. +- ItemList's ``get_v_scroll()`` is now ``get_v_scroll_bar()``. +- MultiPlayerAPI's ``get_network_connected_peers()`` is now ``get_peers()``. +- MultiPlayerAPI's ``get_network_peer()`` is now ``get_peer()``. +- MultiPlayerAPI's ``get_network_unique_id()`` is now ``get_unique_id()``. +- MultiPlayerAPI's ``has_network_peer()`` is now ``has_multiplayer_peer()``. +- PacketPeerUDP's ``is_listening()`` is now ``is_bound()``. +- PacketPeerUDP's ``listen()`` is now ``bound()``. +- ParticleProcessMaterial's ``set_flag()`` is now ``set_particle_flag()``. +- ResourceFormatLoader's ``get_dependencies()`` is now ``_get_dependencies()`` + (note the leading underscore, which denotes a virtual method). +- Shortcut's ``is_valid()`` is now ``has_valid_event()``. + +**Properties** + +.. note:: + + If a property is listed here, its associated getter and setter methods must + also be renamed manually if used in the project. For example, PathFollow2D + and PathFollow3D's ``set_offset()`` and ``get_offset()`` must be renamed to + ``set_progress()`` and ``get_progress()`` respectively. + +- Control's ``margin`` is now ``offset``. +- MultiPlayerAPI's ``refuse_new_network_connections`` is now ``refuse_new_connections``. +- PathFollow2D and PathFollow3D's ``offset`` is now ``progress``. +- The ``extents`` property on CSG nodes and VoxelGI will have to be replaced + with ``size``, with the set value halved (as they're no longer half-extents). + This also affects its setter/getter methods ``set_extents()`` and + ``get_extents()``. +- The ``Engine.editor_hint`` property was removed in favor of the + ``Engine.is_editor_hint()`` *method*. This is because it's read-only, and + properties in Godot are not used for read-only values. + +**Enums** + +- CPUParticles2D's ``FLAG_MAX`` is now ``PARTICLE_FLAG_MAX``. + +**Signals** + +- FileSystemDock's ``instantiate`` is now ``instance``. +- CanvasItem's ``hide`` is now ``hidden``. This rename does **not** apply to the + ``hide()`` method, only the signal. +- Tween's ``tween_all_completed`` is now ``loop_finished``. +- EditorSettings' ``changed`` is now ``settings_changed``. + +**Constants** + +- Color names are now uppercase and use underscores between words. + For example, ``Color.palegreen`` is now ``Color.PALE_GREEN``. +- MainLoop's ``NOTIFICATION_`` constants were moved to global scope, which means + you can remove the ``MainLoop.`` prefix when referencing them. +- MainLoop's ``NOTIFICATION_WM_QUIT_REQUEST`` is now ``NOTIFICATION_WM_CLOSE_REQUEST``. + +Checking project settings +^^^^^^^^^^^^^^^^^^^^^^^^^ + +Several project settings were renamed, and some of them had their enums changed +in incompatible ways (such as shadow filter quality). This means you may need to +set some project settings' values again. Make sure the **Advanced** toggle is +enabled in the project settings dialog so you can see all project settings. + +Checking Environment settings +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Graphics quality settings were moved from Environment properties to project +settings. This was done to make run-time quality adjustments easier, without +having to access the currently active Environment resource then modify its +properties. + +As a result, you will have to configure Environment quality settings in the +project settings as old Environment quality settings aren't converted +automatically to project settings. + +If you have a graphics settings menu that changed environment properties in +Godot 3.x, you will have to change its code to call :ref:`class_RenderingServer` +methods that affect environment effects' quality. Only the "base" toggle of each +environment effect and its visual knobs remain within the Environment resource. + +Updating scripts to take backwards-incompatible changes into account +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some changes performed between Godot 3.x and 4 are not renames, but they still +break backwards compatibility due to different default behavior. + +The most notable examples of this are: + +- Built-in scripts that are :ref:`tool scripts ` + do not get the the ``tool`` keyword converted to the ``@tool`` annotation. +- ``randomize()`` is now automatically called on project load, so deterministic + randomness with the global RandomNumberGenerate instance requires manually + setting a seed in a script's ``_ready()`` function. +- ``OS.get_system_time_secs()`` should be converted to ``Time.get_time_dict_from_system()["second"]``. +- A :ref:`class_StreamPeerTCP` must have ``poll()`` called on it to update its + state, instead of relying on ``get_status()`` automatically polling: + `GH-59582 `__ +- ``is_connected_to_host()`` was removed from StreamPeerTCP and PacketPeerUDP as + per `GH-59582 `__. + ``get_status()`` can be used in StreamPeerTCP instead. + ``is_socket_connected()`` can be used in PacketPeerUDP instead. + +**Removed or replaced nodes/resources** + +This lists all nodes that were replaced by another node requiring different +configuration. The setup must be done from scratch again, as the project +converter doesn't support updating existing setups: + ++---------------------+-----------------------+----------------------------------------------------------------------+ +| Removed node | Closest approximation | Comment | ++=====================+=======================+======================================================================+ +| AnimationTreePlayer | AnimationTree | AnimationTreePlayer was deprecated since Godot 3.1. | ++---------------------+-----------------------+----------------------------------------------------------------------+ +| BakedLightmap | LightmapGI | See :ref:`doc_baked_lightmaps`. | ++---------------------+-----------------------+ | +| BakedLightmapData | LightmapGIData | | ++---------------------+-----------------------+----------------------------------------------------------------------+ +| BitmapFont | FontFile | See :ref:`doc_gui_using_fonts`. | ++---------------------+-----------------------+ | +| DynamicFont | FontFile | | ++---------------------+-----------------------+ | +| DynamicFontData | FontFile | | ++---------------------+-----------------------+----------------------------------------------------------------------+ +| Navigation3D | Node3D | Replaced by other Navigation nodes. | ++---------------------+-----------------------+----------------------------------------------------------------------+ +| Navigation2D | Node2D | Replaced by other Navigation nodes. | ++---------------------+-----------------------+----------------------------------------------------------------------+ +| OpenSimplexNoise | FastNoiseLite | Has different parameters and more noise types such as cellular. No | +| | | support for 4D noise as it's absent from the FastNoiseLite library. | ++---------------------+-----------------------+----------------------------------------------------------------------+ +| ToolButton | Button | ToolButton was Button with the **Flat** property enabled by default. | ++---------------------+-----------------------+----------------------------------------------------------------------+ +| YSort | Node2D | Node2D has a new **Y Sort** property in 4.0. | ++---------------------+-----------------------+----------------------------------------------------------------------+ +| ProximityGroup | Node3D | :ref:`class_VisibleOnScreenNotifier3D` can act as a replacement. | ++---------------------+-----------------------+----------------------------------------------------------------------+ +| Portal | Node3D | Portal and room occlusion culling was replaced by raster | +| | | :ref:`occlusion culling ` | +| | | (OccluderInstance3D node), which requires a different setup process. | ++---------------------+-----------------------+ | +| Room | Node3D | | ++---------------------+-----------------------+ | +| RoomManager | Node3D | | ++---------------------+-----------------------+ | +| RoomGroup | Node3D | | ++---------------------+-----------------------+----------------------------------------------------------------------+ +| Occluder | Node3D | Geometry occlusion culling was replaced by raster | +| | | :ref:`occlusion culling ` | +| | | (OccluderInstance3D node), which requires a different setup process. | ++---------------------+-----------------------+ | +| OccluderShapeSphere | Resource | | ++---------------------+-----------------------+----------------------------------------------------------------------+ + +If loading an old project, the node will be replaced with its +*Closest approximation* automatically (even if not using the project upgrade tool). + +**Threading changes** + +:ref:`Threading ` APIs have changed in 4.0. For +example, the following code snippet in Godot 3.x must be modified to work in 4.0: + +:: + + # 3.x + var start_success = new_thread.start(self, "__threaded_background_loader", + [resource_path, thread_num] + ) + + # 4.0 + var start_success = new_thread.start(__threaded_background_loader.bind(resource_path, thread_num)) + +``Thread.is_active()`` is no longer used and should be converted to ``Thread.is_alive()``. + +.. seealso:: + + See the `changelog `__ + for a full list of changes between Godot 3.x and 4. + +List of automatically renamed methods, properties, signals and constants +------------------------------------------------------------------------ + +The `editor/project_converter_3_to_4.cpp `__ +source file lists all automatic renames performed by the project upgrade tool. +Lines that are commented out refer to API renames that :ref:`cannot be performed automatically `. + +Porting editor settings +----------------------- + +Godot 3.x and 4.0 use different editor settings files. This means their settings +can be changed independently from each other. + +If you wish to port over your Godot 3.x settings to Godot 4, open the +:ref:`editor settings folder ` and copy +``editor_settings-3.tres`` to ``editor_settings-4.tres`` while the Godot 4 +editor is closed. + +.. note:: + + Many settings' names and categories have changed since Godot 3.x. Editor settings + whose name or category has changed won't carry over to Godot 4.0; you will + have to set their values again. From 6a7e9184b2c69a87b5c18bb24edc922becd9ba62 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Sat, 19 Nov 2022 17:11:26 +0100 Subject: [PATCH 2/3] Add conversion suggestions from Mickeon --- tutorials/editor/upgrading_to_godot_4.rst | 118 ++++++++++++---------- 1 file changed, 67 insertions(+), 51 deletions(-) diff --git a/tutorials/editor/upgrading_to_godot_4.rst b/tutorials/editor/upgrading_to_godot_4.rst index ab30857c9a8..080230c5540 100644 --- a/tutorials/editor/upgrading_to_godot_4.rst +++ b/tutorials/editor/upgrading_to_godot_4.rst @@ -97,7 +97,7 @@ Automatically renamed nodes and resources The list below refers to the nodes' new names in Godot 4.0. In the transition between Godot 3.x and 4.0, dozens of nodes were renamed. 3D nodes had a ``3D`` -prefix added to them for consistency with their 2D counterparts. This conversion +suffix added to them for consistency with their 2D counterparts. This conversion is automatic. For ease of searching, this table lists all nodes and resources that were @@ -168,10 +168,6 @@ renamed in a way that does not involve only adding a ``3D`` suffix to the old na +-----------------------------------------+-------------------------------------------+ | Physics2DTestMotionResult | PhysicsTestMotionResult2D | +-----------------------------------------+-------------------------------------------+ -| PhysicsDirectBodyState | PhysicsDirectBodyState3D | -+-----------------------------------------+-------------------------------------------+ -| PhysicsDirectSpaceState | PhysicsDirectSpaceState3D | -+-----------------------------------------+-------------------------------------------+ | PlaneShape | WorldBoundaryShape3D | +-----------------------------------------+-------------------------------------------+ | Position2D | Marker2D | @@ -317,6 +313,7 @@ Due to how the project upgrade tool works, not all - Camera2D's ``get_v_offset()`` is now ``get_drag_vertical_offset()``. - Camera2D's ``set_v_offset()`` is now ``set_drag_vertical_offset()``. - Camera2D's ``make_current()`` is now ``set_current()``. +- CanvasItem's ``update()`` is now ``queue_redraw()``. - Control's ``set_tooltip()`` is now ``set_tooltip_text()``. - EditorNode3DGizmoPlugin's ``create_gizmo()`` is now ``_create_gizmo()`` (note the leading underscore, which denotes a virtual method). @@ -324,6 +321,9 @@ Due to how the project upgrade tool works, not all - FileDialog's ``get_mode()`` is now ``get_file_mode()``. - FileDialog's ``set_mode()`` is now ``set_file_mode()``. - GraphNode's ``get_offset()`` is now ``get_position_offset()``. +- GridMap's ``world_to_map()`` is now ``local_to_map()``. +- GridMap's ``map_to_world()`` is now ``map_to_local()``. +- Image's ``get_rect()`` is now ``get_region()``. - ItemList's ``get_v_scroll()`` is now ``get_v_scroll_bar()``. - MultiPlayerAPI's ``get_network_connected_peers()`` is now ``get_peers()``. - MultiPlayerAPI's ``get_network_peer()`` is now ``get_peer()``. @@ -335,6 +335,8 @@ Due to how the project upgrade tool works, not all - ResourceFormatLoader's ``get_dependencies()`` is now ``_get_dependencies()`` (note the leading underscore, which denotes a virtual method). - Shortcut's ``is_valid()`` is now ``has_valid_event()``. +- TileMap's ``world_to_map()`` is now ``local_to_map()``. +- TileMap's ``map_to_world()`` is now ``map_to_local()``. **Properties** @@ -346,8 +348,10 @@ Due to how the project upgrade tool works, not all ``set_progress()`` and ``get_progress()`` respectively. - Control's ``margin`` is now ``offset``. +- Label's ``percent_visible`` is now ``visible_ratio``. - MultiPlayerAPI's ``refuse_new_network_connections`` is now ``refuse_new_connections``. - PathFollow2D and PathFollow3D's ``offset`` is now ``progress``. +- TextureProgressBar's ``percent_visible`` is now ``show_percentage``. - The ``extents`` property on CSG nodes and VoxelGI will have to be replaced with ``size``, with the set value halved (as they're no longer half-extents). This also affects its setter/getter methods ``set_extents()`` and @@ -410,11 +414,23 @@ break backwards compatibility due to different default behavior. The most notable examples of this are: - Built-in scripts that are :ref:`tool scripts ` - do not get the the ``tool`` keyword converted to the ``@tool`` annotation. + do not get the ``tool`` keyword converted to the ``@tool`` annotation. - ``randomize()`` is now automatically called on project load, so deterministic randomness with the global RandomNumberGenerate instance requires manually setting a seed in a script's ``_ready()`` function. -- ``OS.get_system_time_secs()`` should be converted to ``Time.get_time_dict_from_system()["second"]``. +- AnimatedTexture's ``fps`` property was replaced by ``speed_scale``, which + works the same as AnimationPlayer's ``playback_speed`` property. +- AnimatedSprite2D and AnimatedSprite3D now allow negative ``speed_scale`` + values. This may break animations if you relied on ``speed_scale`` being + internally clamped to ``0.0``. +- BaseButton's signals are now ``button_up`` and ``button_down``. The + ``pressed`` property is now ``button_pressed``. +- Camera2D's ``rotating`` property was replaced by ``ignore_rotation``, which + has inverted behavior. +- Camera2D's ``zoom`` property was inverted: higher values are now more zoomed + in, instead of less. +- ``OS.get_system_time_secs()`` should be converted to + ``Time.get_time_dict_from_system()["second"]``. - A :ref:`class_StreamPeerTCP` must have ``poll()`` called on it to update its state, instead of relying on ``get_status()`` automatically polling: `GH-59582 `__ @@ -429,50 +445,50 @@ This lists all nodes that were replaced by another node requiring different configuration. The setup must be done from scratch again, as the project converter doesn't support updating existing setups: -+---------------------+-----------------------+----------------------------------------------------------------------+ -| Removed node | Closest approximation | Comment | -+=====================+=======================+======================================================================+ -| AnimationTreePlayer | AnimationTree | AnimationTreePlayer was deprecated since Godot 3.1. | -+---------------------+-----------------------+----------------------------------------------------------------------+ -| BakedLightmap | LightmapGI | See :ref:`doc_baked_lightmaps`. | -+---------------------+-----------------------+ | -| BakedLightmapData | LightmapGIData | | -+---------------------+-----------------------+----------------------------------------------------------------------+ -| BitmapFont | FontFile | See :ref:`doc_gui_using_fonts`. | -+---------------------+-----------------------+ | -| DynamicFont | FontFile | | -+---------------------+-----------------------+ | -| DynamicFontData | FontFile | | -+---------------------+-----------------------+----------------------------------------------------------------------+ -| Navigation3D | Node3D | Replaced by other Navigation nodes. | -+---------------------+-----------------------+----------------------------------------------------------------------+ -| Navigation2D | Node2D | Replaced by other Navigation nodes. | -+---------------------+-----------------------+----------------------------------------------------------------------+ -| OpenSimplexNoise | FastNoiseLite | Has different parameters and more noise types such as cellular. No | -| | | support for 4D noise as it's absent from the FastNoiseLite library. | -+---------------------+-----------------------+----------------------------------------------------------------------+ -| ToolButton | Button | ToolButton was Button with the **Flat** property enabled by default. | -+---------------------+-----------------------+----------------------------------------------------------------------+ -| YSort | Node2D | Node2D has a new **Y Sort** property in 4.0. | -+---------------------+-----------------------+----------------------------------------------------------------------+ -| ProximityGroup | Node3D | :ref:`class_VisibleOnScreenNotifier3D` can act as a replacement. | -+---------------------+-----------------------+----------------------------------------------------------------------+ -| Portal | Node3D | Portal and room occlusion culling was replaced by raster | -| | | :ref:`occlusion culling ` | -| | | (OccluderInstance3D node), which requires a different setup process. | -+---------------------+-----------------------+ | -| Room | Node3D | | -+---------------------+-----------------------+ | -| RoomManager | Node3D | | -+---------------------+-----------------------+ | -| RoomGroup | Node3D | | -+---------------------+-----------------------+----------------------------------------------------------------------+ -| Occluder | Node3D | Geometry occlusion culling was replaced by raster | -| | | :ref:`occlusion culling ` | -| | | (OccluderInstance3D node), which requires a different setup process. | -+---------------------+-----------------------+ | -| OccluderShapeSphere | Resource | | -+---------------------+-----------------------+----------------------------------------------------------------------+ ++---------------------+-----------------------+----------------------------------------------------------------------------+ +| Removed node | Closest approximation | Comment | ++=====================+=======================+============================================================================+ +| AnimationTreePlayer | AnimationTree | AnimationTreePlayer was deprecated since Godot 3.1. | ++---------------------+-----------------------+----------------------------------------------------------------------------+ +| BakedLightmap | LightmapGI | See :ref:`doc_baked_lightmaps`. | ++---------------------+-----------------------+ | +| BakedLightmapData | LightmapGIData | | ++---------------------+-----------------------+----------------------------------------------------------------------------+ +| BitmapFont | FontFile | See :ref:`doc_gui_using_fonts`. | ++---------------------+-----------------------+ | +| DynamicFont | FontFile | | ++---------------------+-----------------------+ | +| DynamicFontData | FontFile | | ++---------------------+-----------------------+----------------------------------------------------------------------------+ +| Navigation2D | Node2D | Replaced by :ref:`other 2D Navigation nodes `. | ++---------------------+-----------------------+----------------------------------------------------------------------------+ +| Navigation3D | Node3D | Replaced by :ref:`other 3D Navigation nodes `. | ++---------------------+-----------------------+----------------------------------------------------------------------------+ +| OpenSimplexNoise | FastNoiseLite | Has different parameters and more noise types such as cellular. No | +| | | support for 4D noise as it's absent from the FastNoiseLite library. | ++---------------------+-----------------------+----------------------------------------------------------------------------+ +| ToolButton | Button | ToolButton was Button with the **Flat** property enabled by default. | ++---------------------+-----------------------+----------------------------------------------------------------------------+ +| YSort | Node2D | Node2D has a new **Y Sort** property in 4.0. | ++---------------------+-----------------------+----------------------------------------------------------------------------+ +| ProximityGroup | Node3D | :ref:`class_VisibleOnScreenNotifier3D` can act as a replacement. | ++---------------------+-----------------------+----------------------------------------------------------------------------+ +| Portal | Node3D | Portal and room occlusion culling was replaced by raster | +| | | :ref:`occlusion culling ` | +| | | (OccluderInstance3D node), which requires a different setup process. | ++---------------------+-----------------------+ | +| Room | Node3D | | ++---------------------+-----------------------+ | +| RoomManager | Node3D | | ++---------------------+-----------------------+ | +| RoomGroup | Node3D | | ++---------------------+-----------------------+----------------------------------------------------------------------------+ +| Occluder | Node3D | Geometry occlusion culling was replaced by raster | +| | | :ref:`occlusion culling ` | +| | | (OccluderInstance3D node), which requires a different setup process. | ++---------------------+-----------------------+ | +| OccluderShapeSphere | Resource | | ++---------------------+-----------------------+----------------------------------------------------------------------------+ If loading an old project, the node will be replaced with its *Closest approximation* automatically (even if not using the project upgrade tool). From 0394b3f3a9832b166431e7adaa053e8139ad5f3d Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Mon, 21 Nov 2022 11:27:14 +0100 Subject: [PATCH 3/3] Update according to review comments --- tutorials/editor/upgrading_to_godot_4.rst | 73 ++++++++++++++--------- 1 file changed, 44 insertions(+), 29 deletions(-) diff --git a/tutorials/editor/upgrading_to_godot_4.rst b/tutorials/editor/upgrading_to_godot_4.rst index 080230c5540..493161b5404 100644 --- a/tutorials/editor/upgrading_to_godot_4.rst +++ b/tutorials/editor/upgrading_to_godot_4.rst @@ -3,8 +3,6 @@ Upgrading to Godot 4 ==================== -TODO: https://github.com/godotengine/godot-proposals/issues/387#issuecomment-1251909261 - Should I upgrade to Godot 4? ---------------------------- @@ -74,14 +72,8 @@ To use the project upgrade tool: Only Godot 3.0 and later projects can be upgraded using the project conversion tool found in the Godot 4 editor. - Projects made using Godot versions older than 3.0 must follow a 2-step - process: - - 1. Upgrade the project to Godot 3 using the **Tools > Export to Godot 3.0** - option in the Godot 2.1.6 editor. Open the upgraded project in the Godot - 3.x editor, then manually fix the project to make sure it looks and - runs correctly. - 2. Only *after* performing step 1, you may upgrade the project to Godot 4. + It's recommended to ensure that your project is up-to-date with the latest + 3.x stable release before running the project upgrade tool. Fixing the project after running the project upgrade tool --------------------------------------------------------- @@ -95,13 +87,16 @@ manual. Automatically renamed nodes and resources ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The list below refers to the nodes' new names in Godot 4.0. In the transition -between Godot 3.x and 4.0, dozens of nodes were renamed. 3D nodes had a ``3D`` -suffix added to them for consistency with their 2D counterparts. This conversion -is automatic. +The list below refers to nodes which were simply renamed for consistency or +clarity in Godot 4.0. The project upgrade tool renames them automatically in +your scripts. -For ease of searching, this table lists all nodes and resources that were -renamed in a way that does not involve only adding a ``3D`` suffix to the old name: +One noteworthy set of renames is 3D nodes, which all got a ``3D`` suffix added for +consistency with their 2D counterparts. For example, ``Area`` is now ``Area3D``. + +For ease of searching, this table lists all nodes and resources that were renamed +and are automatically converted, excluding the ones which only involved adding +a ``3D`` suffix to the old name: +-----------------------------------------+-------------------------------------------+ | Old name (Godot 3.x) | New name (Godot 4) | @@ -263,9 +258,6 @@ renamed in a way that does not involve only adding a ``3D`` suffix to the old na | VisualShaderNodeUniformRef | VisualShaderNodeParameterRef | +-----------------------------------------+-------------------------------------------+ -If you cannot find a node or resource in the list below, refer to the above -table to find its new name. - .. _doc_upgrading_to_godot_4_manual_rename: Manually renaming methods, properties, signals and constants @@ -273,7 +265,10 @@ Manually renaming methods, properties, signals and constants Due to how the project upgrade tool works, not all :abbr:`API (Application Programming Interface)` renames can be performed automatically. +The list below contains all renames that must be performed manually using the script editor. +If you cannot find a node or resource in the list below, refer to the above +table to find its new name. .. tip:: @@ -418,26 +413,46 @@ The most notable examples of this are: - ``randomize()`` is now automatically called on project load, so deterministic randomness with the global RandomNumberGenerate instance requires manually setting a seed in a script's ``_ready()`` function. -- AnimatedTexture's ``fps`` property was replaced by ``speed_scale``, which - works the same as AnimationPlayer's ``playback_speed`` property. -- AnimatedSprite2D and AnimatedSprite3D now allow negative ``speed_scale`` - values. This may break animations if you relied on ``speed_scale`` being - internally clamped to ``0.0``. -- BaseButton's signals are now ``button_up`` and ``button_down``. The - ``pressed`` property is now ``button_pressed``. -- Camera2D's ``rotating`` property was replaced by ``ignore_rotation``, which - has inverted behavior. +- ``call_group()``, ``set_group()`` and ``notify_group()`` are now immediate by + default. If calling an expensive function, this may result in stuttering when + used on a group containing a large number of nodes. To use deferred calls like + before, replace ``call_group(...)`` with + ``call_group_flags(SceneTree.GROUP_CALL_DEFERRED, ...)`` (and do the same with + ``set_group()`` and ``notify_group()`` respectively). +- :ref:`class_AABB`'s ``has_no_surface()`` was inverted and renamed to ``has_surface()``. +- :ref:`class_AABB` and :ref:`class_Rect2`'s ``has_no_area()`` was inverted and + renamed to ``has_area()``. +- :ref:`class_AnimatedTexture`'s ``fps`` property was replaced by ``speed_scale``, + which works the same as AnimationPlayer's ``playback_speed`` property. +- :ref:`class_AnimatedSprite2D` and :ref:`class_AnimatedSprite3D` now allow + negative ``speed_scale`` values. This may break animations if you relied on + ``speed_scale`` being internally clamped to ``0.0``. +- :ref:`class_BaseButton`'s signals are now ``button_up`` and ``button_down``. + The ``pressed`` property is now ``button_pressed``. +- :ref:`class_Camera2D`'s ``rotating`` property was replaced by + ``ignore_rotation``, which has inverted behavior. - Camera2D's ``zoom`` property was inverted: higher values are now more zoomed in, instead of less. +- :ref:`class_Node`'s ``remove_and_skip()`` method was removed. + If you need to reimplement it in a script, you can use the + `old C++ implementation `__ + as a reference. - ``OS.get_system_time_secs()`` should be converted to ``Time.get_time_dict_from_system()["second"]``. +- :ref:`class_ResourceSaver`'s ``save()`` method now has its arguments swapped around + (``resource: Resource, path: String``). This also applies to + :ref:`class_ResourceFormatSaver`'s ``_save()`` method. - A :ref:`class_StreamPeerTCP` must have ``poll()`` called on it to update its state, instead of relying on ``get_status()`` automatically polling: `GH-59582 `__ - ``is_connected_to_host()`` was removed from StreamPeerTCP and PacketPeerUDP as per `GH-59582 `__. ``get_status()`` can be used in StreamPeerTCP instead. - ``is_socket_connected()`` can be used in PacketPeerUDP instead. + ``is_socket_connected()`` can be used in :ref:`class_PacketPeerUDP` instead. +- In ``_get_property_list()``, the ``or_lesser`` property hint string is now ``or_less``. +- In ``_get_property_list()``, the ``noslider`` property hint string is now ``no_slider``. +- VisualShaderNodeVec4Parameter now takes a :ref:`class_Vector4` as parameter + instead of a :ref:`class_Quaternion`. **Removed or replaced nodes/resources**