Godot 3 to Godot 4: the converter, then the errors it leaves

Godot 4 renamed a large part of the API. KinematicBody2D became CharacterBody2D, Spatial became Node3D, translation became position, and the export, onready and tool keywords became the @export, @onready and @tool annotations. A Godot 3 script that uses any of them fails to parse in Godot 4, and a script that fails to parse runs nothing.

Godot's own converter knows those pairs. It ships in the editor: open a Godot 3 project in Godot 4's Project Manager and it offers to convert it, or run the editor with --convert-3to4. It rewrites scripts, scenes and project.godot from a renames table, converts the keywords to annotations, and rewrites signal connections to the Callable form.

Run it on a copy. The converter rewrites files in place, and a project that is half Godot 3 and half Godot 4 is harder to recover than either.

Some changes are not renames. move_and_slide() takes no arguments in Godot 4: the body moves by its velocity property, and the old arguments are properties too. yield became await, with a different shape. Tweens are created with create_tween() instead of being nodes. setget became properties with set and get blocks. A table of renames cannot rewrite any of those, so the converter leaves them, and the script fails to parse on the next import.

Rendering changed too. Godot 4 renders on Vulkan with Forward+ by default, or on the Compatibility renderer for older hardware, and lighting, environment and shaders look different from Godot 3's GLES3. Expect to retune light energy, glow and tonemapping by eye. TileMaps and TileSets were redesigned, and are the part of a 2D project that most often needs work after conversion.

C# is not rewritten. A Godot 3 Mono project's C# scripts need their API changes made by hand or by the AI, file by file.

These are the errors a converted Godot 3 project hits next, each with the error text, the fix, and the output of the fix run on Godot 4.7.2: KinematicBody2D is CharacterBody2D, Spatial is Node3D, export is @export, onready is @onready, tool is @tool, setget is set and get, yield is await, StreamTexture is CompressedTexture2D, AudioStreamSample is AudioStreamWAV, Physics2DServerSW is PhysicsServer2D, PhysicsTestMotionResult is PhysicsTestMotionResult3D, StreamCubemapArray is CompressedCubemapArray, VisualShaderNodeVectorScalarSmoothStep is SmoothStep.

Every one of those pages was checked by running the broken code and the fixed code headless on Godot 4.7.2, and shows what the engine printed. All the verified Godot 4 answers.

Flockbay runs Godot 4.7.2. Open a Godot 3 project from Home with Open an existing Godot project…, and it offers Convert a copy: it makes a copy next to the original, runs Godot's own converter on the copy, and imports the result once. The original is only read. A large project takes a few minutes.

A result card then lists what the converter left: the files it could not convert and the errors the engine reports when it imports the copy. It says when the project has C#, which the converter does not rewrite.

From there it is the normal loop. Ask Flockbay to fix the list. It reads each error, makes the change, checks every script parses, plays the game to see it run, and tells you what it changed. You play it and say what looks or feels different from the Godot 3 version, because a converted game that runs is not yet a converted game that feels the same.