Back to Details

godot-4-migration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Godot 4 Migration Guide

Godot 4 迁移指南

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.
这是面向从Godot 3.x迁移到Godot 4的开发者的核心指南。本技能聚焦GDScript 2.0的主要语法变更、全新的
Tween
系统以及
export
注解的更新内容。

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.
  • 当你需要将Godot 3项目移植到Godot 4时使用
  • 当你升级后遇到语法错误时使用
  • 当你需要替换废弃节点（例如
    Tween
    节点替换为
    create_tween
    ）时使用
  • 当你需要将
    export
    变量更新为
    @export
    注解时使用

Key Changes

核心变更

1. Annotations (
@
)

1. 注解（
@
）

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)
Godot 4使用
@
标识用于修改行为的关键字。
  • export var x
    -> 
    @export var x
  • onready var y
    -> 
    @onready var y
  • tool
    -> 
    @tool
    （放置在文件顶部）

2. Setters and Getters

2. Setter与Getter

Properties now define setters/getters inline.
Godot 3:
gdscript
var health setget set_health, get_health

func set_health(value):
    health = value
Godot 4:
gdscript
var health: int:
    set(value):
        health = value
        emit_signal("health_changed", health)
    get:
        return health
属性现在支持内联定义setter/getter。
Godot 3:
gdscript
var health setget set_health, get_health

func set_health(value):
    health = value
Godot 4:
gdscript
var health: int:
    set(value):
        health = value
        emit_signal("health_changed", health)
    get:
        return health

3. Tween System

3. Tween系统

The 
Tween
node is deprecated. Use 
create_tween()
in code.
Godot 3:
gdscript
$Tween.interpolate_property(...)
$Tween.start()
Godot 4:
gdscript
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)
Tween
节点已被废弃，请在代码中使用
create_tween()
。
Godot 3:
gdscript
$Tween.interpolate_property(...)
$Tween.start()
Godot 4:
gdscript
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

4. 信号连接

String-based connections are discouraged. Use callables.
Godot 3:
gdscript
connect("pressed", self, "_on_pressed")
Godot 4:
gdscript
pressed.connect(_on_pressed)
不推荐使用基于字符串的连接方式，请使用可调用对象。
Godot 3:
gdscript
connect("pressed", self, "_on_pressed")
Godot 4:
gdscript
pressed.connect(_on_pressed)

Examples

示例

Example 1: Typed Arrays

示例1：类型数组

GDScript 2.0 supports typed arrays for better performance and type safety.
gdscript
undefined
GDScript 2.0支持类型数组，可提升性能与类型安全性。
gdscript
undefined

Godot 3

Godot 3

var enemies = []
var enemies = []

Godot 4

Godot 4

var enemies: Array[Node] = []
func _ready(): for child in get_children(): if child is Enemy: enemies.append(child)
undefined
var enemies: Array[Node] = []
func _ready(): for child in get_children(): if child is Enemy: enemies.append(child)
undefined

Example 2: Awaiting Signals (Coroutines)

示例2：等待信号（协程）

yield
is replaced by 
await
.
Godot 3:
gdscript
yield(get_tree().create_timer(1.0), "timeout")
Godot 4:
gdscript
await get_tree().create_timer(1.0).timeout
yield
已被
await
替代。
Godot 3:
gdscript
yield(get_tree().create_timer(1.0), "timeout")
Godot 4:
gdscript
await get_tree().create_timer(1.0).timeout

Best Practices

最佳实践

  • ✅ Do: Use 
    @export_range
    , 
    @export_file
    , etc., for better inspector UI.
  • ✅ Do: Type all variables (
    var x: int
    ) for performance gains in GDScript 2.0.
  • ✅ 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()
    ).
  • ✅ 推荐： 使用
    @export_range
    、
    @export_file
    等注解获得更友好的检查器UI。
  • ✅ 推荐： 为所有变量添加类型声明（
    var x: int
    ），以获得GDScript 2.0的性能提升。
  • ✅ 推荐： 使用
    super()
    调用父类方法，而非
    .function_name()
    的调用方式。
  • ❌ 不推荐： 若可以使用信号对象（
    name.emit()
    ）触发信号，就不要使用字符串名称的方式（
    emit_signal("name")
    ）。

Troubleshooting

故障排查

Problem: "Identifier 'Tween' is not a valid type." Solution: 
Tween
is now 
SceneTreeTween
or just an object returned by 
create_tween()
. You rarely type it explicitly, just use 
var tween = create_tween()
.
问题： "Identifier 'Tween' is not a valid type." 解决方案： 
Tween
现在已改为
SceneTreeTween
，或者就是
create_tween()
返回的对象。你几乎不需要显式声明它的类型，直接使用
var tween = create_tween()
即可。