Upgrading from Godot 3 to Godot 4 (2024)

Advantages of upgrading¶

Along with thenew 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.xwill continue to be supported for some time after 4.0 is released, but it willeventually 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 onGodot 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 Godot3.x doesn't have. These issues will be ironed out over time in futureGodot 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.xas a result.

• Godot 4's baseline hardware requirements (such as memory usage) are slightlyhigher, both for the editor and exported projects. This was required for theimplementation of some core optimizations.

• Since Godot 4 includes more features than Godot 3, Godot 4's binary size forexported projects is larger. While this can be mitigated byoptimizing a build for size, a 4.0 build witha given set of enabled modules will remain larger compared to a 3.x build withthe same modules. This can be an issue forexporting to the Web, as binary size directlyinfluences 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 (2ndgeneration) integrated graphics, this will prevent the project from runningon such hardware after upgrading.Software OpenGL implementationscan 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 haveunfortunately been lost in the process. Some of these features may be restoredin future Godot releases:

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

• 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 somepoint in the future.

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

• Mono was replaced by .NET 6. This means exporting C# projects to Android, iOSand HTML5 is no longer supported for now. Exporting C# projects to desktopplatforms is still supported, and as of 4.2 there's experimental support forexporting to mobile platforms. Support for exporting C# projects to moreplatforms will be restored in future 4.x releases as upstream supportimproves.

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

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 Scanbutton 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.godotOnly and Convert Full Project. After ensuring your project is backed up(see the above warning), choose Convert Full Project. Convertproject.godot Only is intended to be used for advanced use cases only, incase the conversion tool fails.

5. Wait until the project conversion process finishes. This can take up to a fewminutes for large projects with lots of scenes.

6. When the Project Manager interface becomes available again, double-click theproject (or select the project then choose Edit) to open it in theeditor.

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 allowyou 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 onthe 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 /path/to/project/folder --convert-3to4 [<max_file_kb>] [<max_line_size>]

[<max_file_kb>] and [<max_line_size>] are optional arguments to specifythe maximum size of files to be converted (in kilobytes and lines). The defaultlimits are 4 MB and 100,000 lines respectively. If a file hits either of thoselimits, it will not be upgraded by the project converter. This is useful toprevent large resources from slowing down the upgrade to a crawl.

If you still want large files to be converted by the project upgrade tool,increase the size limits when running the project upgrade tool. For example,running the Godot editor binary with those arguments increases both limits by a10× factor:

path/to/godot.binary --path /path/to/project/folder --convert-3to4 40000 1000000

Automatically renamed nodes and resources¶

The list below refers to nodes which were simply renamed for consistency orclarity in Godot 4.0. The project upgrade tool renames them automatically inyour scripts.

One noteworthy set of renames is 3D nodes, which all got a 3D suffix added forconsistency with their 2D counterparts. For example, Area is now Area3D.

For ease of searching, this table lists all nodes and resources that were renamedand are automatically converted, excluding the ones which only involved addinga 3D suffix to the old name:

Manually renaming methods, properties, signals and constants¶

Due to how the project upgrade tool works, not allAPI 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 abovetable to find its new name.

Methods

• File and Directory classes were replaced by FileAccess andDirAccess, which have an entirely different API. Several methodsare now static, which means you can call them directly on FileAccess orDirAccess without having to create an instance of that class.

• Screen and window-related methods from the OS singleton (such asOS.get_screen_size()) were moved to the DisplayServer singleton.Method naming was also changed to use theDisplayServer.<object>_<get/set>_property() form instead. For example,OS.get_screen_size() becomes DisplayServer.screen_get_size().

• Time and date methods from the OS singleton were moved to theTime singleton.(The Time singleton is also available in Godot 3.5 and later.)

• You may have to replace some instance() calls with instantiate(). Theconverter should handle this automatically, but this relies on custom code thatmay 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().

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

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

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

• 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 bind().

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

• SceneTree's change_scene() is now change_scene_to_file().

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

• Transform2D's xform() is mat * vec and xform_inv() is vec * mat.

Properties

• 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 replacedwith size, with the set value halved (as they're no longer half-extents).This also affects its setter/getter methods set_extents() andget_extents().

• The Engine.editor_hint property was removed in favor of theEngine.is_editor_hint() method. This is because it's read-only, andproperties 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 thehide() 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 duplicated to Node which meansyou 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 changedin incompatible ways (such as shadow filter quality). This means you may need toset some project settings' values again. Make sure the Advanced toggle isenabled in the project settings dialog so you can see all project settings.

Checking Environment settings¶

Graphics quality settings were moved from Environment properties to projectsettings. This was done to make run-time quality adjustments easier, withouthaving to access the currently active Environment resource then modify itsproperties.

As a result, you will have to configure Environment quality settings in theproject settings as old Environment quality settings aren't convertedautomatically to project settings.

If you have a graphics settings menu that changed environment properties inGodot 3.x, you will have to change its code to call RenderingServermethods that affect environment effects' quality. Only the "base" toggle of eachenvironment effect and its visual knobs remain within the Environment resource.

Updating shaders¶

There have been some changes to shaders that aren't covered by the upgrade tool.

The .shader file extension is no longer supported, which means you mustrename .shader files to .gdshader and update references accordingly inscene/resource files using an external text editor.

Some notable renames you will need to perform in shaders are:

• Texture filter and repeat modes are now set on individual uniforms, ratherthan the texture files themselves.

• hint_albedo is now source_color.

• hint_color is now source_color.

• Built in matrix variables were renamed.

• Particles shaders no longer use the vertex() processor function. Insteadthey use start() and process().

See Shading language for more information.

Updating scripts to take backwards-incompatible changes into account¶

Some changes performed between Godot 3.x and 4 are not renames, but they stillbreak backwards compatibility due to different default behavior.

The most notable examples of this are:

• Lifecycle functions such as _ready() and _process() no longerimplicitly call parent classes' functions that have the same name. Instead,you must use super() at the top of a lifecycle function in the child classso that the parent class function is called first.

• Both String and StringName are now exposed toGDScript. This allows for greater optimization, as StringName is specificallydesigned to be used for "constant" strings that are created once and reusedmany times. These types are not strictly equivalent to each other, which meansis_same("example", &"example") returns false. Although in most casesthey are interchangeable ("example" == &"example" returns true),sometimes you may have to replace "example" with &"example".

• GDScript setter and getter syntaxwas changed, but it's only partially converted by the conversion tool. In mostcases, manual changes are required to make setters and getters working again.

• GDScript signal connection syntax was changed.The conversion tool will use the string-based syntax which is still present inGodot 4, but it's recommended to switch to the Signal-based syntaxdescribed on the linked page. This way, strings are no longer involved,which avoids issues with signal name errors that can only be discovered at run-time.

• Built-in scripts that are tool scriptsdo not get the tool keyword converted to the @tool annotation.

• The Tween node was removed in favor of Tweeners, which are also available inGodot 3.5 and later. See theoriginal pull requestfor details.

• randomize() is now automatically called on project load, so deterministicrandomness with the global RandomNumberGenerate instance requires manuallysetting a seed in a script's _ready() function.

• call_group(), set_group() and notify_group() are now immediate bydefault. If calling an expensive function, this may result in stuttering whenused on a group containing a large number of nodes. To use deferred calls likebefore, replace call_group(...) withcall_group_flags(SceneTree.GROUP_CALL_DEFERRED, ...) (and do the same withset_group() and notify_group() respectively).

• Instead of rotation_degrees, the rotation property is exposed to theeditor, which is automatically displayed as degrees in the Inspectordock. This may break animations, as the conversion is not handled automatically by theconversion tool.

• AABB's has_no_surface() was inverted and renamed to has_surface().

• AABB and Rect2's has_no_area() was inverted andrenamed to has_area().

• AnimatedTexture's fps property was replaced by speed_scale,which works the same as AnimationPlayer's playback_speed property.

• AnimatedSprite2D and AnimatedSprite3D now allownegative speed_scale values. This may break animations if you relied onspeed_scale being internally clamped to 0.0.

• AnimatedSprite2D and AnimatedSprite3D's playingproperty was removed. Use play()/stop() method instead OR configureautoplay animation via the SpriteFrames bottom panel (but not both at once).

• Array's slice() second parameter (end) is now exclusive,instead of being inclusive. For example, this means that[1, 2, 3].slice(0, 1) now returns [1] instead of [1, 2].

• BaseButton's signals are now button_up and button_down.The pressed property is now button_pressed.

• Camera2D's rotating property was replaced byignore_rotation, which has inverted behavior.

• Camera2D's zoom property was inverted: higher values are now more zoomedin, instead of less.

• Node's remove_and_skip() method was removed.If you need to reimplement it in a script, you can use theold C++ implementationas a reference.

• OS.get_system_time_secs() should be converted toTime.get_time_dict_from_system()["second"].

• ResourceSaver's save() method now has its arguments swapped around(resource: Resource, path: String). This also applies toResourceFormatSaver's _save() method.

• A StreamPeerTCP must have poll() called on it to update itsstate, instead of relying on get_status() automatically polling:GH-59582

• String's right() method has changed behavior:it now returns a number of characters from the right of the string, rather thanthe right side of the string from a given position. If you need the old behavior,you can use substr() instead.

• is_connected_to_host() was removed from StreamPeerTCP and PacketPeerUDP asper GH-59582.get_status() can be used in StreamPeerTCP instead.is_socket_connected() can be used in 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 Vector4 as parameterinstead of a Quaternion.

Removed or replaced nodes/resources

This lists all nodes that were replaced by another node requiring differentconfiguration. The setup must be done from scratch again, as the projectconverter doesn't support updating existing setups:

If loading an old project, the node will be replaced with itsClosest approximation automatically (even if not using the project upgrade tool).

Threading changes

Threading APIs have changed in 4.0. Forexample, the following code snippet in Godot 3.x must be modified to work in 4.0:

# 3.xvar start_success = new_thread.start(self, "__threaded_background_loader", [resource_path, thread_num])# 4.0var 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().

ArrayMesh resource compatibility breakage¶

If you've saved an ArrayMesh resource to a .res or .tres file, theformat used in 4.0 is not compatible with the one used in 3.x. You will need togo through the process of importing the source mesh file and saving it as anArrayMesh resource again.