godot-4-migration

Godot 4 移行ガイド

概要

Godot 3.x から Godot 4 へ移行する開発者向けの重要なガイドです。このスキルでは、GDScript 2.0 の主な構文変更、新しい Tween システム、export アノテーションの更新に焦点を当てます。

このスキルを使用する場面

• Godot 3 のプロジェクトを Godot 4 に移植するときに使用します。
• アップグレード後に構文エラーが発生したときに使用します。
• 非推奨のノード（Tween ノードと create_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. セッターとゲッター

プロパティでは、セッター／ゲッターをインラインで定義するようになりました。

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. シグナル接続

文字列ベースの接続は推奨されていません。Callable を使用してください。

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）を使用し、対象のエンジンとワークロードでパフォーマンスを測定します。
• ✅ 推奨: 親メソッドを呼び出すには .function_name() ではなく super() を使用します。
• ❌ 非推奨: シグナルオブジェクト（name.emit()）を使用できる場合は、シグナルに文字列名（emit_signal("name")）を使用しないでください。

トラブルシューティング

問題: 「Identifier 'Tween' is not a valid type.」 解決策: Godot 4 では、Tween は create_tween() が返すオブジェクトであり、シーンノードでも SceneTreeTween 型でもありません。Node のコンテキストでは var tween: Tween = create_tween() を使用してください。

制限事項

• このスキルは、タスクが上記の説明範囲に明確に該当する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。