godot-4-migration

Godot 4 Migration Guide

Overview

A critical guide for developers transitioning from Godot 3.x to Godot 4. This skill focuses on the major syntax changes in GDScript 2.0, the new Tween system, and export annotation updates.

When to Use This Skill

• Use when porting a Godot 3 project to Godot 4.
• Use when encountering syntax errors after upgrading.
• Use when replacing deprecated nodes (like Tween node vs create_tween).
• Use when updating export variables to @export annotations.

Migration procedure

Work in a backed-up branch or copy. Choose an exact Godot 4 version, validate conversion before changing files, and inspect converter gaps, renamed nodes, shaders, physics, plugins and export targets. Test scenes and saved games before replacing the working Godot 3 build. Examples below are fragments in an appropriate Node script; Enemy must be a declared project type.

Official guide: Upgrading to Godot 4.

Key Changes

1. Annotations (@)

Godot 4 uses @ for keywords that modify behavior.

• export var x -> @export var x
• onready var y -> @onready var y
• tool -> @tool (at top of file)

2. Setters and Getters

Properties now define setters/getters inline.

Godot 3:

var health setget set_health, get_health

func set_health(value):
    health = value

Godot 4:

signal health_changed(health: int)

var health: int = 100:
    set(value):
        health = value
        emit_signal("health_changed", health)
    get:
        return health

3. Tween System

The Godot 3 Tween node was removed in Godot 4. Use create_tween() in code.

Godot 3:

$Tween.interpolate_property(...)
$Tween.start()

Godot 4:

var tween = create_tween()
tween.tween_property($Sprite, "position", Vector2(100, 100), 1.0)
tween.parallel().tween_property($Sprite, "modulate:a", 0.0, 1.0)

4. Signal Connections

String-based connections are discouraged. Use callables.

Godot 3:

connect("pressed", self, "_on_pressed")

Godot 4:

pressed.connect(_on_pressed)

Examples

Example 1: Typed Arrays

GDScript 2.0 supports typed arrays for type checking; measure performance rather than assuming a speedup.

# Godot 3
var enemies = []

# Godot 4
var enemies: Array[Node] = []

func _ready():
    for child in get_children():
        if child is Enemy:
            enemies.append(child)

Example 2: Awaiting Signals (Coroutines)

yield is replaced by await.

Godot 3:

yield(get_tree().create_timer(1.0), "timeout")

Godot 4:

await get_tree().create_timer(1.0).timeout

Best Practices

• ✅ Do: Use @export_range, @export_file, etc., for better inspector UI.
• ✅ Do: Use static types (var x: int) for clearer contracts and type checking; measure performance in the target engine and workload.
• ✅ Do: Use super() to call parent methods instead of .function_name().
• ❌ Don't: Use string names for signals (emit_signal("name")) if you can use the signal object (name.emit()).

Troubleshooting

Problem: "Identifier 'Tween' is not a valid type." Solution: Godot 4 uses a Tween object returned by create_tween(), not a scene node or a SceneTreeTween type. Use var tween: Tween = create_tween() in a Node context.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.