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

> Discover how the Godot 4 editor converts Godot 3 projects with its automatic, non-destructive three-phase pipeline. Learn about validation, scanning, renaming, and idempotence for seamless backward compatibility.

- Repository: [Godot Engine/godot](https://github.com/godotengine/godot)
- Tags: deep-dive
- Published: 2026-02-26

---

**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`](https://github.com/godotengine/godot/blob/main/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`](https://github.com/godotengine/godot/blob/main/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`](https://github.com/godotengine/godot/blob/main/editor/project_upgrade/project_converter_3_to_4.h) and implemented in [`editor/project_upgrade/project_converter_3_to_4.cpp`](https://github.com/godotengine/godot/blob/main/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`](https://github.com/godotengine/godot/blob/main/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`](https://github.com/godotengine/godot/blob/main/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`](https://github.com/godotengine/godot/blob/main/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`](https://github.com/godotengine/godot/blob/main/editor/project_upgrade/project_upgrade_tool.h) and `.cpp` – UI dialog wrapper and progress reporting
- [`editor/editor_node.cpp`](https://github.com/godotengine/godot/blob/main/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`](https://github.com/godotengine/godot/blob/main/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.