Write a migration guide for Godot 4

[dploeger]

Issue description:

Because I remember the switch from Godot 2 to 3, I'm just putting this here to request a full migration guide for Godot 4.

I'd suggest that all developers, that make a breaking change on an object's properties or behavior or GDScript or C# language changes, comment a short info about that change and maybe some additional context to this issue and at the end I'll write a migration guide and add a PR for it.

[Calinou]

I have a preliminary 4.0 changelog here: https://gist.github.com/Calinou/49aefe52ce8f67ffa3f743932123d14f

Node renames are handled automatically by the editor, and it's planned to do the same for node properties as well. However, scripts will likely not be edited automatically.

See also https://github.com/godotengine/godot-proposals/issues/387.

[qarmin]

Most renames in GDScript files(like classes or function names) should be handled by https://github.com/godotengine/godot/pull/51950 (this isn't merged yet).

I think that with its help upgrading should be quite easy(not yet, since there is a lot of GDScript 2.0 bugs which prevents sometimes from using basic functionalities).

I'm still trying to get list of all C# classes and methods, but for now I'm unable to do this, so converting C# project probably will be more difficult due lack of support by this tool.

[and-rad]

~For now, animations that contain transform tracks have to be altered manually by replacing those with individual tracks for position_3d, rotation_3d, and scale_3d. See this issue for an example of the problem.~

EDIT: Nevermind, didn't look at the preliminary changelog first. It's already mentioned there.

[WolfgangSenff]

I've started the upgrade for Crystal Climber to 4.0 and have begun creating a gist with all the things I've had to do so far. There will be quite a bit more to it as I'm able to work on it, but see https://gist.github.com/WolfgangSenff/168cb0cbd486c8c9cd507f232165b976 for a good start on a GDScript 4.0 upgrade cheat sheet.

[Toasterson]

I started an upgrade experiment aswell for Fleets of Sol. But I hit a blockade. Node3D has no more get_world() function. Where has that landed? Does it still exist?

[qarmin]

get_world -> get_world_3d You can look at the code inside file editor/converter.cpp to see for function renames

[Cerno-b]

Just as a note: It is probably worthwhile to have a section in the manual for all the code changes in a systematic and complete table.

There are a lot of Godot 3 tutorials and Q&As out there that will cause some frustration if the answers don't work anymore in Godot 4 because OS.get_screen_size() is now DisplayServer.screen_get_size() etc. So having a handy table of all the functions that have been renamed or moved would be really neat.

[Riteo]

@Cerno-b perhaps https://github.com/godotengine/godot/pull/51950 might be used to build one?

[Cerno-b]

@Riteo Sounds like a good way to semi-automatically generate the list and make sure it is kept up to date in case the autoconverter gets extended later.

[Riteo]

@Cerno-b Thinking about it, I wonder if it'd be useful to have such a list if there's already a converter.

[dploeger]

@Riteo I guess it makes sense to see it documented how the converter works. Just as a reference or if something goes wrong.

[Cerno-b]

@Cerno-b Thinking about it, I wonder if it'd be useful to have such a list if there's already a converter.

The converter is for converting projects from Godot 3 to Godot 4. The change list is for "converting" developers from Godot 3 to Godot 4, in order to get them up to speed as conveniently as possible.

Maybe it's possible to generate this documentation from within the project converter as "docs as code". If I read this correctly, the code conversion will mainly consist of regexes, so I think it makes create a structure (list of pairs of string) in the place of where the regexes are applied so that the documentation and the conversion are in one place.

[Toasterson]

In my personal experience it's always good to have a list available (Even automatically generated from the converter). So that developers can update their workflows and if code changes fail in unexpected ways they can get an output of what they need to do manually.

[Zireael07]

Needs to happen sooner rather than later, people trying Godot 4 alphas are constantly running into renames... biggest offender so far is signals to callables, with shader changes not too far behind

[Calinou]

Needs to happen sooner rather than later, people trying Godot 4 alphas are constantly running into renames... biggest offender so far is signals to callables, with shader changes not too far behind

I think a migration guide will have to wait until 4.0 enters beta (maybe even RC), as the API is still subject to change right now. We can't spend too much time updating the page frequently, as other stabilization efforts are already taking a lot of time from contributors.

[dploeger]

Some things I came across while migrating EgoVenture (will update as I come along):

• Directory became DirAccess (as mentioned in the Beta 2 post)
• get_screen_size moved from OS to DisplayServer (no notes found about this)
• OS.center_window seems to be gone (investigating)

[Calinou]

OS.center_window seems to be gone (investigating)

There's a PR readding that functionality to DisplayServer: https://github.com/godotengine/godot/pull/65843

[dploeger]

Will subscribe to this and halt migration for the time being. Thanks.

[Calinou]

I started working on a upgrade guide: https://github.com/Calinou/godot-docs/tree/add-upgrade-to-godot-4