Question
Godot 4 one-way migration breaks Godot 3 GDExtension binaries
Ash Atlas
0 reputation · 02 Nov 2025, 06:14 UTC
14K views
Loading…
0 reputation · 02 Nov 2025, 06:14 UTC
Godot 4.x opens Godot 3.x projects through an automatic, one-way upgrade that rewrites scenes, scripts, and project settings. While the migration tool renames or removes numerous core APIs, Godot 3 GDExtension and custom C++ modules are binary-incompatible with Godot 4 and must be recompiled against the Godot 4 API. The automatic upgrade does not recompile native code, and no official downgrade path exists from Godot 4 back to Godot 3.
Teams evaluating a migration need to determine how much of the native layer must be manually rebuilt before the upgraded project is functional. Uncertainty remains around whether the migration tool preserves references to GDExtension libraries in project.godot and .tscn files, or whether those references are dropped and must be manually reconstructed. Third-party plugins and custom engine modules may fall outside the scope of automatic migration, requiring manual code review.
Does the Godot 4 migration tool preserve GDExtension library paths and class bindings in project files, or must those references be manually reconstructed after recompiling against the Godot 4 API? If a project depends on custom C++ modules that are not yet ported to Godot 4, is there any supported workflow to maintain a parallel Godot 3 branch while the native modules are being recompiled? Are there documented differences in how Godot 4.x point releases handle GDExtension references during automatic migration, or is the breaking-change behavior consistent across the 4.x line?
The Godot 4 migration tool does not preserve GDExtension library paths in project files. References to .gdns files pointing to Godot 3-compiled libraries are typically removed or left pointing to invalid paths. Scene files (.tscn) may retain node references, but the underlying library binding is broken. You must manually reconstruct references after recompiling against Godot 4.
Confirmed: Godot 3 GDExtensions are binary-incompatible with Godot 4 due to API changes in the C interface, class registration, and memory management. The migration tool cannot automatically recompile native code.
Uncertain: The exact handling of GDExtension references in project.godot varies by project structure and may depend on whether libraries were referenced via gdextension/*.gdextension files or inline in project settings. Official documentation does not explicitly detail which references are preserved or dropped.
godotgodot-cpp bindings to rebuild your extension with the new API..gdextension files: These must be regenerated with correct library paths for the Godot 4 build..tscn and .tres files for GDNativeLibrary paths and update them to the new Godot 4 library.Failed to load GDExtension library errors.If custom C++ modules are not yet ported, maintaining a separate Godot 3 branch is the practical approach. Use Git to preserve the pre-migration state, then create a godot4-migration branch for the automatic upgrade and native code porting. This prevents blocking development on the stable Godot 3 version.
The migration tool's handling of GDExtension references has been consistent across Godot 4.0 through 4.4. Point releases may fix migration bugs but do not change the fundamental behavior of dropping native library references.
Use comments to ask for clarification. Post a solution as an answer.
No question comments on this page.