mcpField
G
godot-4-migration

godot-4-migration

github.com/sickn33开发48.7k70 次安装今天更新
代码仓库

关于 godot-4-migration

面向将项目从 Godot 3.x 迁移到 Godot 4 的开发者，说明 GDScript 语法及 API 变化，并强调验证转换结果后再替换现有构建。

主要功能

  1. 01GDScript 2.0 语法变化
  2. 02Tween 迁移至 create_tween()
  3. 03更新 export 注解
  4. 04信号与协程迁移
  5. 05转换验证建议

适用场景

  1. 01迁移 Godot 3 项目
  2. 02排查升级后的错误
  3. 03替换已弃用的 Tween 节点
  4. 04更新导出变量

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/sickn33/agentic-awesome-skills --skill godot-4-migration

安装后在 Claude Code 中输入/godot-4-migration确认已加载。

详细介绍

Godot 4 迁移指南

概述

这是一份面向从 Godot 3.x 迁移到 Godot 4 的开发者的重要指南。本指南重点介绍 GDScript 2.0 中的主要语法变更、新的 Tween 系统以及 export 注解的更新。

何时使用此技能

  • 将 Godot 3 项目移植到 Godot 4 时使用。
  • 升级后遇到语法错误时使用。
  • 替换已弃用的节点时使用（例如，用 create_tween 替代 Tween 节点）。
  • 将 export 变量更新为 @export 注解时使用。

迁移流程

在已备份的分支或副本中进行操作。选择确切的 Godot 4 版本，在修改文件前验证转换结果，并检查转换器的不足、重命名的节点、着色器、物理、插件和导出目标。替换正在使用的 Godot 3 构建版本前，先测试场景和存档。以下示例是适用于 Node 脚本的代码片段；Enemy 必须是已声明的项目类型。

官方指南：升级到 Godot 4。

主要变更

1. 注解（@）

Godot 4 使用 @ 表示会修改行为的关键字。

  • export var x -> @export var x
  • onready var y -> @onready var y
  • tool -> @tool（位于文件顶部）
2. Setter 和 Getter

现在可以在属性中内联定义 setter/getter。

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 系统

Godot 3 的 Tween 节点已在 Godot 4 中移除。请在代码中使用 create_tween()。

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. 信号连接

不建议使用基于字符串的连接方式。请使用可调用对象。

Godot 3：

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

Godot 4：

pressed.connect(_on_pressed)

示例

示例 1：类型化数组

GDScript 2.0 支持类型化数组，用于类型检查；应实际测量性能，而不要假定它能提升速度。

# Godot 3
var enemies = []

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

func _ready():
    for child in get_children():
        if child is Enemy:
            enemies.append(child)
示例 2：等待信号（协程）

yield 已被 await 取代。

Godot 3：

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

Godot 4：

await get_tree().create_timer(1.0).timeout

最佳实践

  • ✅ 建议： 使用 @export_range、@export_file 等注解，以改善检查器 UI。
  • ✅ 建议： 使用静态类型（var x: int），让约定和类型检查更清晰；并在目标引擎和工作负载下测量性能。
  • ✅ 建议： 使用 super() 调用父类方法，而不是 .function_name()。
  • ❌ 避免： 如果可以使用信号对象（name.emit()），就不要使用信号名称字符串（emit_signal("name")）。

故障排除

问题： “Identifier 'Tween' is not a valid type.” 解决方案： Godot 4 使用由 create_tween() 返回的 Tween 对象，而不是场景节点或 SceneTreeTween 类型。在 Node 上下文中使用 var tween: Tween = create_tween()。

限制

  • 仅当任务明确符合上述范围时，才使用此技能。
  • 不要将输出视为针对特定环境进行验证、测试或专家评审的替代品。
  • 如果缺少必要的输入、权限、安全边界或成功标准，请暂停并请求澄清。

评论

支持 Markdown