はじめに

ChatGPT、Claude、Cursor などで GDScript を書かせると、構文的には正しい、コンパイルも通る、表面的には動く、というコードがほぼ確実に出力されます。しかし Godot 4 で実際にゲームを動かすと、エラーは出ないのに動作が間違っているという「サイレント失敗」が頻繁に発生します。

Sonarsource State of Code 2026 レポートによると、AI 生成コードの障害の60%はサイレント失敗です。Godot のような複雑なランタイムを持つエンジンでは、この比率はさらに高くなります。

私たちが Godot 専用の AI エージェントを開発する中で、ユーザーログから繰り返し見つかった5つの典型的な失敗パターンを共有します。

1. シグナル受信側が freed されているのに connect が残っている

# AI が書きがちなコード
func setup_enemy(enemy):
    enemy.died.connect(_on_enemy_died)

setup_enemy() を呼んだ親ノードが敵が死ぬ前に queue_free() されると、connect された receiver が dangling 状態になります。Godot はエラーを出しません。シグナルは emit されるが、コールバックは無音でスキップされます。

防御策は connect 時に is_instance_valid() ガードを入れること、または receiver の tree_exited シグナルで明示的に disconnect することです。

2. AnimationTree のパラメータパスが文字列ミス

# AI はパスを覚えで書く
anim_tree.set("parameters/playback/state", "run")

実際のパス名は parameters/playback だけで、状態は travel() メソッド経由で操作します。AI は他のプロジェクトで見たパスをそのままコピーすることがあり、文字列が間違っていてもエラーは出ず、無音で何も起こりません。

防御策は、起動時に anim_tree.get("parameters/playback") != null を assert することです。

3. autoload を参照する前にプロジェクト設定で登録忘れ

# AI コード
func _on_hit():
    AudioManager.play("hit")

AudioManager が project.godot に autoload として登録されていないと、これは NIL リファレンスエラーを起こします。ただし、_on_hit() が呼ばれる経路を実際にプレイテストしないと、エラーは表面化しません。30秒のテストプレイでは見つからない経路で起きやすいです。

4. シーンパスのハードコーディング

# AI の出力
var player_scene = load("res://scenes/Player.tscn")

プロジェクトのフォルダ構造が res://entities/ だった場合、load() は null を返しますが、エラーは出ません。player_scene.instantiate() で初めて Null reference エラーが出ます。

AI は最初に学習したプロジェクト構造を仮定するので、現在のプロジェクトと一致しない場合があります。@export var player_scene: PackedScene で明示的に注入するパターンが安全です。

5. tween チェーンが再エントリで壊れる

# AI コード
func attack():
    var tween = create_tween()
    tween.tween_property(self, "modulate", Color.RED, 0.1)
    tween.tween_property(self, "modulate", Color.WHITE, 0.1)

attack() が連続で呼ばれる (ボタン連打、AI からの指示など) と、複数の tween が同時に走り、互いを上書きします。アニメーションが「微妙にカクつく」程度の症状で、エラーは出ません。

防御策は tween.kill() を先頭に入れるか、tween_property の代わりに set を併用することです。

なぜ AI ツールはこれを直せないのか

これらのパターンに共通するのは、すべてランタイムでしか観察できないことです。ソースコードを読むだけでは検出不可能です。

1番のシグナル dangling は、receiver を free してから signal を emit して初めて見える
2番のパス間違いは、AnimationTree のインスペクタを見るか、実際に animation が走らないと判らない
3番の autoload 抜けは、プロジェクト設定を見ないと判らない
4番のパスハードコードは、load() が null を返すまで判らない
5番の tween 重複は、連打で初めて発生する

Stack Overflow 2025 開発者調査によると、AI 出力への信頼度は40%から29%に下落、66%の開発者が「ほぼ正しいが完全ではない AI コード」を最大の不満として挙げています。Godot 開発はこのカテゴリに完全に該当します。

対策

3つあります。

1つ目: AI が書いたコードは、必ず Godot を起動して F5 を押す。コミット前に。出力パネルがほとんどのサイレント失敗を数秒で表示します。

2つ目: is_connected() ガード、is_instance_valid() ガード、assert(get(path) != null) を AI 生成コードに自動的に追加する習慣をつける。これは最も安いディフェンシブパターンです。

3つ目: エンジン統合型の AI ツール (例: Godot 専用の Ziva) を試す。エージェント自体がシーンを実行してテストできるので、ソースコードを生成した瞬間にサイレント失敗を検出できます。

まとめ

AI が書いた GDScript が「動いてるように見える」のと「実際に動く」のは別物です。Godot のような scene tree と signal を持つエンジンでは、静的解析だけでは検出できないバグが多数発生します。

「コンパイルが通った」を「動く」と勘違いしないこと。これが Godot で AI コードを使うときの最も重要なルールです。