How Godot Handles Project Conversion and Backward Compatibility: A Technical Deep Dive

The Godot 4 editor automatically detects Godot 3 projects and runs a non-destructive, three-phase conversion pipeline that validates, scans, and renames code elements using regular expression mappings while ensuring idempotence through SHA-256 hashing.

When migrating legacy game projects to modern engine versions, understanding project conversion and backward compatibility mechanisms becomes critical for preserving work. The godotengine/godot repository implements a sophisticated upgrade system that bridges Godot 3 and Godot 4 without destroying original source files. This article examines the automatic detection logic, the data-driven conversion pipeline, and the safety mechanisms that prevent data corruption during migration.

Automatic Detection and the Project Upgrade Tool

The conversion process begins when the editor detects an unconverted Godot 3 project during startup. In editor/editor_node.cpp, the initialization sequence checks for two specific indicators: a special comment marker inside project.godot and the editor setting "Run Project Upgrade Tool on restart".

The marker comment ; Project was converted by built‑in tool to Godot 4 serves as a permanent flag indicating successful conversion. If this string is absent, the editor instantiates ProjectUpgradeTool (defined in editor/project_upgrade/project_upgrade_tool.h), which presents a modal dialog with a progress bar and launches the conversion pipeline.

The Three-Phase Conversion Pipeline

The core conversion logic resides in ProjectConverter3To4 (declared in editor/project_upgrade/project_converter_3_to_4.h and implemented in editor/project_upgrade/project_converter_3_to_4.cpp). This class executes a rigorous three-phase process to ensure accuracy and safety.

Phase 1: Project Validation with validate_conversion()

Before modifying any files, ProjectConverter3To4::validate_conversion() performs a complete dry-run analysis. This method scans every potential target file (.gd, .tscn, .shader, .cs, and others) and applies regular expression patterns from RenamesMap3To4 to detect required changes without writing data.

The validation phase identifies syntax incompatibilities, counts necessary renames, and reports files that exceed configurable size or line-length limits. This prevents the conversion from starting if critical errors would occur, giving developers a chance to fix issues before committing changes.

Phase 2: File Discovery via check_for_files()

Once validation passes, ProjectConverter3To4::check_for_files() recursively traverses the res:// directory tree. This method specifically excludes hidden folders like .git and .godot while collecting paths for files matching supported extensions.

The discovery phase builds an internal vector of file paths that will undergo conversion, ensuring that only relevant source assets are processed while ignoring binary artifacts, version control metadata, and engine-generated cache files.

Phase 3: In-Place Conversion with convert()

The final phase, ProjectConverter3To4::convert(), executes the actual transformation. For each discovered file, the converter:

1. Reads the file into a vector of SourceLine objects
2. Sequentially applies rename helpers including rename_classes(), rename_gdscript_functions(), rename_csharp_functions(), rename_colors(), and others
3. Calculates the SHA-256 hash of the transformed content
4. Rewrites the file only if the hash differs from the original, preventing unnecessary disk writes

After processing all files, the converter prepends the conversion marker comment to project.godot, ensuring idempotence—subsequent editor launches will recognize the project as already converted and skip the upgrade tool entirely.

Data-Driven Renames and Non-Destructive Safeguards

The conversion system emphasizes safety and maintainability through data-driven architecture and multiple protective mechanisms.

RenamesMap3To4 and Regular Expression Patterns

Rather than hardcoding string replacements, ProjectConverter3To4 relies on RenamesMap3To4 (defined in editor/project_upgrade/renames_map_3_to_4.h). This header contains comprehensive mapping tables for:

• Class renames (class_renames)

• GDScript function renames (gdscript_function_renames)

• C# function renames (csharp_function_renames)

• Property, signal, and enum renames

• Shader built-in renames

• Input map action renames

The converter compiles these mappings into optimized regular expressions during initialization, allowing the community to extend compatibility support by updating the data tables without modifying the conversion algorithm itself.

Safety Mechanisms: SHA-256 Validation and Size Limits

To prevent data corruption, the implementation includes several non-destructive safeguards:

• Hash-based change detection: Files are rewritten only when SHA-256 hashes indicate actual content changes, preserving timestamps and avoiding unnecessary modifications
• Configurable size limits: Files exceeding the configured maximum size (default typically 1 MiB) are skipped and reported to the user
• Line length protection: Lines longer than the configured maximum are ignored during conversion but logged for manual review
• Dry-run validation: The validate_conversion() phase ensures all renames can be applied successfully before any disk writes occur

These mechanisms ensure that even if the conversion process is interrupted or encounters unexpected file formats, the original project remains recoverable.

Key Source Files and Architecture

The project conversion system spans several specialized files within the Godot editor codebase:

• editor/project_upgrade/project_converter_3_to_4.h and .cpp – Core conversion logic, file scanning, and rename pipelines
• editor/project_upgrade/renames_map_3_to_4.h – Data tables mapping Godot 3 names to Godot 4 equivalents
• editor/project_upgrade/project_upgrade_tool.h and .cpp – UI dialog wrapper and progress reporting
• editor/editor_node.cpp – Entry point for automatic detection and tool invocation during editor startup

This architecture separates concerns between data definitions, conversion algorithms, user interface, and editor integration, making the system maintainable and extensible for future version migrations.

Summary

• Godot 4 automatically detects unconverted Godot 3 projects by checking for a specific comment marker in project.godot and the "Run Project Upgrade Tool on restart" editor setting.
• The conversion process uses ProjectConverter3To4 to execute a three-phase pipeline: validation via validate_conversion(), file discovery through check_for_files(), and in-place transformation using convert().
• All renames are data-driven through RenamesMap3To4 tables, supporting class, function, property, signal, enum, shader, and input map migrations without algorithmic code changes.
• Non-destructive safeguards include SHA-256 hash verification to prevent unnecessary writes, configurable file size and line length limits, and dry-run validation before any disk modifications.
• The system ensures idempotence by writing a conversion marker to project.godot, preventing re-conversion in subsequent editor sessions.

Frequently Asked Questions

How do I manually trigger the Godot project conversion tool?

You can initiate the conversion through the editor interface by selecting Project → Upgrade Project Files… from the menu bar. Alternatively, you can trigger the conversion programmatically using the ProjectConverter3To4 class in C++ or GDScript, specifying maximum file size and line length parameters to control the conversion scope.

What file types does the Godot 3 to 4 converter support?

The converter processes multiple source asset formats including .gd (GDScript), .tscn (scene files), .shader (shader code), .cs (C# scripts), and other project configuration files. The check_for_files() method specifically targets these extensions while excluding hidden directories like .git and .godot to avoid processing version control or cache data.

Is the Godot project conversion process reversible?

The conversion is designed to be non-destructive but not automatically reversible. While the validate_conversion() method performs a dry-run to ensure safety, and SHA-256 hashing prevents unnecessary file modifications, the actual renaming operations permanently change source code references from Godot 3 to Godot 4 naming conventions. Developers should commit their projects to version control before running the upgrade tool to enable manual rollback if needed.

How does the converter prevent projects from being converted multiple times?

The system implements idempotence through a conversion marker comment that the convert() method prepends to project.godot upon successful completion: ; Project was converted by built‑in tool to Godot 4. When the editor restarts, editor_node.cpp checks for this marker and the "Run Project Upgrade Tool on restart" setting; if the marker exists, the upgrade tool is not spawned, ensuring each project undergoes conversion exactly once.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}