Add a Godot 3 to Godot 4 upgrade guide

[Calinou]

I've likely missed some things, so please review 🙂

See #5121. This closes #4960.

[Mickeon]

A lot of properties, methods, signals etc. etc. are missing and I'm not sure it's because they are handled by the converter already or is an intentional omission to keep it brief.

[Calinou]

A lot of properties, methods, signals etc. etc. are missing and I'm not sure it's because they are handled by the converter already or is an intentional omission to keep it brief.

In the interest of brevity, I've only listed properties/methods that are not automatically converted. I've left a link to the converter source code, which lists all properties/methods that were renamed. The converter source code also includes commented out code for properties/methods that are not automatically renamed, with a comment explaining why.

[Mickeon]

I was considering reordering that whole list 'cause it very much is... such a mess to read, but in the meantime, let's see...

[Mickeon]

• Camera2D's rotating has been inverted the other way around Reverse Camera2D.rotating to ignore_rotation godot#64359;
• Camera2D's zoom was inverted Invert Camera2D zoom to make it intuitive godot#57392.
• Button's signals are now button_up and button_down and the property is button_pressed (wait what, why is it not just pressed anymore after the whole ordeal?)
• Rename Image's get_rect to get_region godot#66017
• Rework AnimatedTexture's fps into speed_scale godot#65188 (I recall Reduz wanted to nuke this class, but well, it is still here, so it may be worth mentioning)
• Rename ProgressBar.percent_visible to show_percentage godot#65038 and Rename Label & RichTextLabel.percent_visible to visible_ratio godot#64665 are two entirely different properties with the same name, and for that reason could not be included in the project converter.
• Rename TileMap/GridMap.world_to_map and opposite to local_to_map godot#64661 (This is worth mentioning because the converter cannot infer if it refers to TileMap or GridMap)
• Rename CanvasItem.update() to queue_redraw() godot#64377 (update is too generic for a term and could not be included in the project converter)
• Allow negative speed_scale in AnimatedSprite2D & 3D godot#65148 may be worth mentioning? The original PR's behavior was modified so it isn't nearly as compatibility breaking as thought, unless someone was actually relying on the value being clamped to 0.

[Calinou]

@Mickeon Thanks! I've pushed a separate commit mentioning your changes so it can be reviewed separately.

[skyace65]

I accidentally hit submit review with the first thing I was looking at, sorry. Just a few minor things that should be changed but overall the page the page looks good. As someone not familiar with a lot of the changes made this was easy to understand.

[Mickeon]

Some miscellaneous compatibility-breaking PRs that I could actually understand the meaning of, that I found while browsing.

• Delete set_all, set_axis, and get_axis methods from Vector2/3/3i/4/4i godot#66133
• Improve naming of theme properties throughout GUI code godot#65437
• Rename uniform to parameter across the engine godot#64952 (This may be noteworthy on its own?)
• Remove Node.remove_and_skip method godot#64412 (?)
• Replace AABB/Rect2/Rect2i has_no_* methods with has_* methods godot#64417
• Swap arguments of ResourceSaver.save() godot#61647
• Remove Signal connect binds godot#63595 (Very very important)
• Rename or_lesser range property hint to or_less godot#59589 (There's also noslider to no_slider but I can't find it)
• Make {call,set,notify}_group() immediate by default godot#51591

[mhilbrunner]

Looks good to me, I'll let it stay open another day in case someone notices something else and will merge tomorrow. Thanks! ❤️

[akien-mga]

Didn't review everything, but here's some early comments.

[akien-mga]

Suggested change

	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.
	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:
	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.
	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:

[akien-mga]

I tried to make the language clearer that this is not all renamed nodes. IMO it's still a bit confusing though to have an "exhaustive" list that actually is only a subset.

There would need to be an intro paragraph to explain how the document is structured further (trivial renames handled by the converter, API changes which require manual handling, etc.).

But maybe there should be a table which actually lists everything, and has a third column that clarifies where the rename is handled by the conversion tool or not (and if not, why - different API, risk of false positives, etc.).
So users could always find an old or new name with Ctrl+F.

[Calinou]

The table would be very long and could get outdated quickly – I guess we could find a way to generate it automatically and put it on a separate page.

[Mickeon]

But maybe there should be a table which actually lists everything, and has a third column that clarifies where the rename is handled by the conversion tool or not (and if not, why - different API, risk of false positives, etc.).
So users could always find an old or new name with Ctrl+F.

Absolutely. 100%. It's part of the reason as to why I expressed this:

I was considering reordering that whole list 'cause it very much is... such a mess to read,

[Calinou]

Some miscellaneous compatibility-breaking PRs that I could actually understand the meaning of, that I found while browsing.

I updated the list to take the PRs you listed into account (also pushed as a separate commit for easier reviewing).

[akien-mga]

Looks great as a start 👍

[akien-mga]

Thanks!

[TokisanGames]

Good start. A comprehensive list of renames is great, but that's appendix information. The value of a guide like this is to discuss fundamentals, API design shifts, philosophical adjustments, gotchas, and intentional breaks where there is no supported replacement or where reimplementation is required (eg tweens, dropping rotation_degrees, signals, setters/getters), such as:

• Shaders are not converted at all with the auto tool (last I checked) and there are many breaking changes. Transmission is gone, and backlight works differently. Filenames are different. Hints are renamed. Projection Matrices are renamed. #63673
• ArrayMesh is an unsupported format, no matter if it is saved to disk as a resource file or embedded in a scene file. It is not forwards compatible and not upgradeable. The conversion tool won't do anything to the meshes. The only supported, and safe way to maintain working meshes is to keep fbx/glb files linked to tscns. Cleared inheritance is not supported at all and will cause broken meshes. GD3->4 #63550 GD4a1-14->a15+ #64854 There has been talk of supporting ArrayMesh by Juan, Remi & Clay in 64854, but until it is reality, the above should be documented.
• Setters and getters are verrrrry different #61660 https://docs.godotengine.org/en/latest/tutorials/scripting/gdscript/gdscript_basics.html#properties
• Signal connections are very different https://docs.godotengine.org/en/latest/tutorials/scripting/gdscript/gdscript_basics.html#signals
• Advantages of upgrading:
  • Vulkan support
  • Greatly improved visual fidelity with improved direct lighting & shadows, bounce lighting systems (VoxelGI/SDGFI), fixed roughness, improved SSS, physical lights and camera, volumetric fog, particle collision, vfx/screen space/camera effects, AA methods Ground truth #63374
  • Faster real world gdscript and rendering performance, even pre-optimizations (though not in all test circumstances #68959)
  • Compute shaders and a much more open shader pipeline (How open is it? Can we do anything like tessellation or geometry shaders?), shader includes, uniform arrays, structs
  • Automatic, toggleable LOD generation and handling for meshes
  • Animation Library, allowing seamless retargeting of animations on identical rigs
  • Cyclic References of class names are now supported (as of pending beta7) #67714
  • Double precision floating point support (upon recompiling) #892
  • Move maker mode for offline, performance-independent rendering #62122
• DIsadvantages of upgrading:
  • Bullet physics has been removed. Only godot physics exists (for better or worse). (Gamedevs should not have to discover this half-way through a port.)
  • Any ArrayMeshes (cleared inheritance from glb/fbxes) will need to be manually reimported from assets again.
  • Rotation_degrees is gone affecting both code and AnimationPlayer tracks #63390
  • You now have to care about StringNames #64171 Pending removal #68747
  • No 16/32-bit/HDR viewports (yet) #2935
  • Tween Node is gone and tweens need to be reimplemented, which can be done while still on GD3 #41794

[Calinou]

Shaders are not converted at all with the auto tool (last I checked) and there are many breaking changes. Transmission is gone, and backlight works differently. Filenames are different. Hints are renamed. Projection Matrices are renamed. godotengine/godot#63673

Shaders are supposed to be converted, but it might only work with external .gdshader files, not built-in shaders in a scene file:
Edit: It's the other way around: godotengine/godot#69597

https://github.com/godotengine/godot/blob/1e3919c409fa1f24db8ecde58f723fd59adfeccb/editor/project_converter_3_to_4.cpp#L1374-L1390