Skip to content

Commit fa694b5

Browse files
akien-mgaakien-mga
authored
Merge pull request #10546 from raulsntos/breaking_changes_4.4
Add "Upgrading from Godot 4.3 to Godot 4.4" page
2 parents 0c9c905 + aa17d7a commit fa694b5

File tree

2 files changed

+217
-0
lines changed

2 files changed

+217
-0
lines changed

‎tutorials/migrating/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,4 @@ path.
2323
upgrading_to_godot_4.1
2424
upgrading_to_godot_4.2
2525
upgrading_to_godot_4.3
26+
upgrading_to_godot_4.4

‎tutorials/migrating/upgrading_to_godot_4.4.rst

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
.. _doc_upgrading_to_godot_4.4:
2+
3+
Upgrading from Godot 4.3 to Godot 4.4
4+
=====================================
5+
6+
For most games and apps made with 4.3 it should be relatively safe to migrate to 4.4.
7+
This page intends to cover everything you need to pay attention to when migrating
8+
your project.
9+
10+
Breaking changes
11+
----------------
12+
13+
If you are migrating from 4.3 to 4.4, the breaking changes listed here might
14+
affect you. Changes are grouped by areas/systems.
15+
16+
This article indicates whether each breaking change affects GDScript and whether
17+
the C# breaking change is *binary compatible* or *source compatible*:
18+
19+
- **Binary compatible** - Existing binaries will load and execute successfully without
20+
recompilation, and the run-time behavior won't change.
21+
- **Source compatible** - Source code will compile successfully without changes when
22+
upgrading Godot.
23+
24+
Core
25+
~~~~
26+
27+
======================================================================================================================== =================== ==================== ==================== ============
28+
Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced
29+
======================================================================================================================== =================== ==================== ==================== ============
30+
**FileAccess**
31+
Method ``open_encrypted`` adds a new ``iv`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-98918`_
32+
Method ``store_8`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_
33+
Method ``store_16`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_
34+
Method ``store_32`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_
35+
Method ``store_64`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_
36+
Method ``store_buffer`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_
37+
Method ``store_csv_line`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_
38+
Method ``store_double`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_
39+
Method ``store_float`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_
40+
Method ``store_half`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_
41+
Method ``store_line`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_
42+
Method ``store_pascal_string`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_
43+
Method ``store_real`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_
44+
Method ``store_string`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_
45+
Method ``store_var`` changes return type from ``void`` to ``bool`` |✔️| |❌| |✔️| `GH-78289`_
46+
**OS**
47+
Method ``execute_with_pipe`` adds a new ``blocking`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-94434`_
48+
Method ``read_string_from_stdin`` adds a new ``buffer_size`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-91201`_
49+
**RegEx**
50+
Method ``compile`` adds a new ``show_error`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-95212`_
51+
Method ``create_from_string`` adds a new ``show_error`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-95212`_
52+
**Semaphore**
53+
Method ``post`` adds a new ``count`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-93605`_
54+
**TranslationServer**
55+
Method ``standardize_locale`` adds a new ``add_defaults`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-98972`_
56+
======================================================================================================================== =================== ==================== ==================== ============
57+
58+
GUI nodes
59+
~~~~~~~~~
60+
61+
======================================================================================================================== =================== ==================== ==================== ============
62+
Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced
63+
======================================================================================================================== =================== ==================== ==================== ============
64+
**RichTextLabel**
65+
Method ``push_meta`` adds a new ``tooltip`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-99481`_
66+
Method ``set_table_column_expand`` adds a new ``shrink`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-101482`_
67+
**GraphEdit**
68+
Method ``connect_node`` adds a new ``keep_alive`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-97449`_
69+
Signal ``frame_rect_changed`` changes ``new_rect`` parameter type from ``Vector2`` to ``Rect2`` |❌| |❌| |❌| `GH-102796`_
70+
======================================================================================================================== =================== ==================== ==================== ============
71+
72+
Physics
73+
~~~~~~~
74+
75+
======================================================================================================================== =================== ==================== ==================== ============
76+
Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced
77+
======================================================================================================================== =================== ==================== ==================== ============
78+
**SoftBody3D**
79+
Method ``set_point_pinned`` adds a new ``insert_at`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-94684`_
80+
======================================================================================================================== =================== ==================== ==================== ============
81+
82+
Rendering
83+
~~~~~~~~~
84+
85+
======================================================================================================================== =================== ==================== ==================== ============
86+
Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced
87+
======================================================================================================================== =================== ==================== ==================== ============
88+
**CPUParticles2D**
89+
Method ``restart`` adds a new ``keep_seed`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-92089`_
90+
**CPUParticles3D**
91+
Method ``restart`` adds a new ``keep_seed`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-92089`_
92+
**GPUParticles2D**
93+
Method ``restart`` adds a new ``keep_seed`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-92089`_
94+
**GPUParticles3D**
95+
Method ``restart`` adds a new ``keep_seed`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-92089`_
96+
**RenderingDevice**
97+
Method ``draw_list_begin`` adds a new ``breadcrumb`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-90993`_
98+
Method ``draw_list_begin`` removes many parameters |❌| |✔️ with compat| |✔️ with compat| `GH-98670`_
99+
Method ``index_buffer_create`` adds a new ``enable_device_address`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-100062`_
100+
Method ``uniform_buffer_create`` adds a new ``enable_device_address`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-100062`_
101+
Method ``vertex_buffer_create`` adds a new ``enable_device_address`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-100062`_
102+
**RenderingServer**
103+
Method ``multimesh_allocate_data`` adds a new ``use_indirect`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-99455`_
104+
**Shader**
105+
Method ``get_default_texture_parameter`` changes return type from ``Texture2D`` to ``Texture`` |✔️| |❌| |❌| `GH-95126`_
106+
Method ``set_default_texture_parameter`` changes ``texture`` parameter type from ``Texture2D`` to ``Texture`` |✔️| |❌| |✔️| `GH-95126`_
107+
**VisualShaderNodeCubemap**
108+
Property ``cube_map`` changes type from ``Cubemap`` to ``TextureLayered`` |✔️| |❌| |❌| `GH-95126`_
109+
**VisualShaderNodeTexture2DArray**
110+
Property ``texture_array`` changes type from ``Texture2DArray`` to ``TextureLayered`` |✔️| |❌| |❌| `GH-95126`_
111+
======================================================================================================================== =================== ==================== ==================== ============
112+
113+
.. note::
114+
115+
In C#, the enum ``RenderingDevice.StorageBufferUsage`` breaks compatibility because of the way the bindings generator
116+
detects the enum prefix. New members where added in `GH-100062`_ to the enum that caused the enum members to be renamed.
117+
118+
Navigation
119+
~~~~~~~~~~
120+
121+
======================================================================================================================== =================== ==================== ==================== ============
122+
Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced
123+
======================================================================================================================== =================== ==================== ==================== ============
124+
**NavigationServer2D**
125+
Method ``query_path`` adds a new ``callback`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-100129`_
126+
**NavigationServer3D**
127+
Method ``query_path`` adds a new ``callback`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-100129`_
128+
======================================================================================================================== =================== ==================== ==================== ============
129+
130+
Editor plugins
131+
~~~~~~~~~~~~~~
132+
133+
======================================================================================================================== =================== ==================== ==================== ============
134+
Change GDScript Compatible C# Binary Compatible C# Source Compatible Introduced
135+
======================================================================================================================== =================== ==================== ==================== ============
136+
**EditorInterface**
137+
Method ``open_scene_from_path`` adds a new ``set_inherited`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-90057`_
138+
Method ``popup_node_selector`` adds a new ``current_value`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-94323`_
139+
Method ``popup_property_selector`` adds a new ``current_value`` optional parameter |✔️| |✔️ with compat| |✔️ with compat| `GH-94323`_
140+
**EditorSceneFormatImporter**
141+
Method ``_get_import_flags`` removed |❌| |❌| |❌| `GH-101531`_
142+
**EditorTranslationParserPlugin**
143+
Method ``_parse_file`` changes return type to ``Array`` and removes ``msgids`` and ``msgids_context_plural`` parameters |❌| |❌| |❌| `GH-99297`_
144+
======================================================================================================================== =================== ==================== ==================== ============
145+
146+
.. note::
147+
148+
The method ``_get_import_flags`` was never used by the engine. It was removed despite the
149+
compatibility breakage as there's no way for users to rely on this affecting engine behavior.
150+
151+
Behavior changes
152+
----------------
153+
154+
Core
155+
~~~~
156+
157+
.. note::
158+
159+
The ``Curve`` resource now enforces its value range, so ``min_value`` and ``max_value`` need to be changed
160+
if any of the points fall outside of the default ``[0, 1]`` range.
161+
162+
Rendering
163+
~~~~~~~~~
164+
165+
.. note::
166+
167+
The ``VisualShaderNodeVec4Constant`` shader node had its input type changed to ``Vector4``. Users need to
168+
recreate the values in their constants.
169+
170+
CSG
171+
~~~
172+
173+
.. note::
174+
175+
The CSG implementation now uses Emmett Lalish's `Manifold <https://github.com/elalish/manifold>`_ library (`GH-94321`_).
176+
The new implementation is more consistent with manifold definitions and fixes a number of bugs and stability
177+
issues. As a result, non-manifold meshes are no longer supported. You can use ``MeshInstance3D`` for
178+
rendering non-manifold geometry, such as quads or planes.
179+
180+
Android
181+
~~~~~~~
182+
183+
.. note::
184+
185+
Android sensor events are no longer enabled by default (`GH-94799`_). Projects that use sensor events can
186+
enable them as needed in Project Settings under **Input Devices > Sensors**.
187+
188+
.. |❌| replace:: :abbr:`❌ (This API breaks compatibility.)`
189+
.. |✔️| replace:: :abbr:`✔️ (This API does not break compatibility.)`
190+
.. |✔️ with compat| replace:: :abbr:`✔️ (This API does not break compatibility. A compatibility method was added.)`
191+
192+
.. _GH-78289: https://github.com/godotengine/godot/pull/78289
193+
.. _GH-90057: https://github.com/godotengine/godot/pull/90057
194+
.. _GH-90993: https://github.com/godotengine/godot/pull/90993
195+
.. _GH-91201: https://github.com/godotengine/godot/pull/91201
196+
.. _GH-92089: https://github.com/godotengine/godot/pull/92089
197+
.. _GH-93605: https://github.com/godotengine/godot/pull/93605
198+
.. _GH-94321: https://github.com/godotengine/godot/pull/94321
199+
.. _GH-94323: https://github.com/godotengine/godot/pull/94323
200+
.. _GH-94434: https://github.com/godotengine/godot/pull/94434
201+
.. _GH-99455: https://github.com/godotengine/godot/pull/99455
202+
.. _GH-94684: https://github.com/godotengine/godot/pull/94684
203+
.. _GH-94799: https://github.com/godotengine/godot/pull/94799
204+
.. _GH-95212: https://github.com/godotengine/godot/pull/95212
205+
.. _GH-95126: https://github.com/godotengine/godot/pull/95126
206+
.. _GH-97449: https://github.com/godotengine/godot/pull/97449
207+
.. _GH-98670: https://github.com/godotengine/godot/pull/98670
208+
.. _GH-98918: https://github.com/godotengine/godot/pull/98918
209+
.. _GH-98972: https://github.com/godotengine/godot/pull/98972
210+
.. _GH-99297: https://github.com/godotengine/godot/pull/99297
211+
.. _GH-99481: https://github.com/godotengine/godot/pull/99481
212+
.. _GH-100062: https://github.com/godotengine/godot/pull/100062
213+
.. _GH-100129: https://github.com/godotengine/godot/pull/100129
214+
.. _GH-101482: https://github.com/godotengine/godot/pull/101482
215+
.. _GH-101531: https://github.com/godotengine/godot/pull/101531
216+
.. _GH-102796: https://github.com/godotengine/godot/pull/102796

0 commit comments

Comments
 (0)