godot-gdscript

Godot GDScript（4.x）

正しく、静的型付けされた GDScript を記述し、エンジンが意図する方法でノードのライフサイクルとシグナルシステムを使用します。対象は Godot 4.7（GDScript 2.0）です。

使用する場面

• .gd ファイルの記述や修正に使用します。変数や関数の宣言、クラスの作成、@export／@onready の使用、シグナルの接続、コルーチンやシグナルの待機などが該当します。
• Godot 3.x のスクリプトを 4.x に移植し、スクリプトを解析できなくなった場合に使用します。

使用しない場面： シーン／ノードの構造やインスタンス化に関する質問 → godot-nodes-scenes；シグナルの設計／疎結合のパターン → godot-signals-groups；GDScript の代わりに C# を使用する場合 → godot-csharp。

基本的なワークフロー

1. 可能な限りすべてに型を指定します。 GDScript 2.0 は静的型付けに対応しています （var hp: int = 10、func add(a: int, b: int) -> int:）。型を指定すると解析時にエラーを検出でき、VM の処理も高速になります。型を推論する場合は := を使用します。
2. ライフサイクルコールバックは、それぞれの用途に合わせて使用します。 ノードとその子ノードがツリーに入ったときに一度だけ呼ばれる _ready()、描画フレームごとに呼ばれる _process(delta)、固定の物理ティックごとに呼ばれる _physics_process(delta) があります（移動や物理処理にはこれを使用します）。
3. ノード参照は @onready で取得します。 _init() では取得しないでください。子ノードはノードがツリーに入るまで存在しません。
4. @export で調整可能な値を公開します。 デザイナーがインスペクターで編集できるようになります。
5. イベントへの反応には、読みやすい場合はポーリングではなくシグナルと await を使用します。
6. 実行してエラーを確認します。 デバッガーパネルには行番号付きで型エラーが表示されます。まず最初のエラーを修正してください（後続のエラーは連鎖していることがよくあります）。

パターン

1. ライフサイクル、@export、@onready を使った型付きスクリプト

extends Node2D
class_name Spinner            # registers a global type usable in other scripts

@export var speed: float = 90.0          # editable in the Inspector (degrees/sec)
@export_range(0, 10, 0.5) var wobble := 2.0
@onready var sprite: Sprite2D = $Sprite2D # resolved when the node enters the tree

func _ready() -> void:
    # Runs once, after children are ready. Safe to touch $Sprite2D here.
    sprite.modulate = Color.AQUA

func _process(delta: float) -> void:
    # delta is seconds since last frame; multiply rates by it for FPS independence.
    rotation_degrees += speed * delta

2. シグナル：宣言、発行、接続（4.x の Callable 構文）

extends Node

signal health_changed(current: int, maximum: int)   # typed signal params

var health := 100

func take_damage(amount: int) -> void:
    health = max(health - amount, 0)
    health_changed.emit(health, 100)     # 4.x: emit as a method on the signal

func _ready() -> void:
    # 4.x: connect with a Callable, not a string method name.
    health_changed.connect(_on_health_changed)

func _on_health_changed(current: int, maximum: int) -> void:
    print("HP: %d/%d" % [current, maximum])

3. await — タイマーまたはシグナルが発火するまで一時停止（3.x の yield を置き換えます）

func flash_then_continue() -> void:
    modulate = Color.RED
    await get_tree().create_timer(0.2).timeout   # resume after 0.2s
    modulate = Color.WHITE
    # await any signal: var result = await some_node.some_signal

4. ラムダ、型付き配列、安全なアクセス

var enemies: Array[Node] = []                    # typed array

func cull_dead() -> void:
    enemies = enemies.filter(func(e): return e.is_inside_tree())

func get_first_name(d: Dictionary) -> String:
    return d.get("name", "unknown")              # default avoids missing-key errors

注意点

• 3.x から 4.x への移行でシグナル API が変更されました。 emit_signal("x") は引き続き動作しますが、x.emit(...) を推奨します。connect("x", self, "_on_x") は廃止されました。Callable を使用して x.connect(_on_x) とします。yield(obj, "sig") は await obj.sig になりました。
• export var は @export var（アノテーション）になりました。同様に、onready は @onready、tool は @tool、RPC キーワードの remote／master は @rpc(...) アノテーションになりました。
• _init() で @onready や $NodePath を使うと失敗します。 ノードはまだツリーに入っていません。ノード参照は _ready() または @onready で初期化してください。
• 整数の除算では小数部分が切り捨てられます。 5 / 2 == 2 です。5.0 / 2 を使うか、float にキャストしてください。
• _process と _physics_process の使い分けに注意してください。 move_and_slide() と物理処理は _physics_process(delta) に記述します。_process を使うと、動きがフレームレートに依存します。
• class_name はプロジェクト全体で一意である必要があります。 また、他のスクリプトで型名を使用する場合や、インスペクターで型として使用する場合に必要です。

参考資料

• アノテーションの全一覧、高度な型付け、スタイル規約については、 references/annotations-and-typing.md を参照してください。

関連スキル

• godot-nodes-scenes — シーンツリー、インスタンス化、オートロード。
• godot-signals-groups — シグナルとグループを使ったイベント駆動型アーキテクチャ。
• godot-resources — カスタム Resource 型を使ったデータ駆動型設計。
• godot-csharp — C#/.NET を使用した同じエンジン概念。