Up to date

This page is up to date for Godot 4.1. If you still find outdated information, please open an issue.

Upgrading from Godot 3 to Godot 4

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

See Documentation changelog for a list of pages documenting new features in Godot 4.0.

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 3.x is tried and true, while Godot 4 remains in its early stages.

    • Godot 4.0 is expected to contain workflow and performance issues that Godot 3.x doesn't have. These issues will be ironed out over time in future Godot 4.x releases.

  • Godot 4 has fewer third-party tutorials available compared to Godot 3.x. If you're new to game engines, you may have a better experience using Godot 3.x as a result.

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

  • Since Godot 4 includes more features than Godot 3, Godot 4's binary size for exported projects is larger. While this can be mitigated by optimizing a build for size, a 4.0 build with a given set of enabled modules will remain larger compared to a 3.x build with the same modules. This can be an issue for exporting to the Web, as binary size directly influences how fast the engine can initialize (regardless of download speed).

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

Caveats of upgrading

Since Godot 4 is a complete rewrite in many aspects, some features have unfortunately been lost in the process. Some of these features may be restored in future Godot releases:

  • Bullet physics was removed in favor of GodotPhysics. This only affects 3D projects that used the default physics engine (which was Bullet) and didn't manually change it to GodotPhysics. There are no plans to re-add Bullet physics in core, but a third-party add-on could be created for it thanks to GDExtension.

  • Rendering in 2D is no longer performed in HDR, which means "overbright" modulate values have no visible effect. This is planned to be restored at some point in the future.

  • While rendering still happens in HDR in 3D when using the Forward Plus or Forward Mobile backends, Viewports cannot return HDR data anymore. This is planned to be restored at some point in the future.

  • Mono was replaced by .NET 6. This means exporting C# projects to Android, iOS and HTML5 is no longer supported for now. Exporting C# projects to desktop platforms is still supported. Support for exporting C# projects to more platforms will be restored in future 4.x releases as upstream support improves.

You can find a more complete list of functional regressions by searching for issues labeled "regression" but not "bug" on GitHub.

Preparing before the upgrade (optional)

If you want to be ready to upgrade to Godot 4 in the future, consider using Tweener and the Time singleton in your project. These classes are both available in Godot 3.5 and later.

This way, you won't be relying on the deprecated Tween node and OS time functions, both of which are removed in Godot 4.0.

It's also a good idea to rename external shaders so that their extension is .gdshader instead of .shader. Godot 3.x supports both extensions, but only .gdshader is supported in Godot 4.0.

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.

Using the Project Manager

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.

If you hit conversion issues due to some project files being too large or long, you can use the command line to upgrade the project (see below). This will allow you to override the converter's size limits.

Using the command line

To use the project upgrade tool from the command line, it's recommended to validate the project conversion by running the Godot editor binary with the following arguments:

# [<max_file_kb>] [<max_line_size>] are optional arguments.
# Remove them if you aren't changing their values.
path/to/godot.binary --path /path/to/project/folder --validate-conversion-3to4 [<max_file_kb>] [<max_line_size>]

If the list of planned upgrades looks good to you, run the following command on the Godot editor binary to upgrade project files:

# [<max_file_kb>] [<max_line_size>] are optional arguments.
# Remove them if you aren't changing their values.
path/to/godot.binary --path