Claude CodeでGodotゲーム開発を始める手順

Godotの構成とGDScriptの位置づけ

Godotはオープンソースの2D/3Dゲームエンジンで、Claude Codeと組み合わせるとGDScriptのコード生成とシーン構成の反復作業を減らせます。Godotのシーンはノードを親子関係で並べた木構造です。保存したシーンはエディタ上で再利用可能な部品として扱えます。キャラクターならCharacterBody2D・Sprite2D・CollisionShape2Dのようなノードを組み合わせて1つのシーンにするのが基本形です。

公式ドキュメントは「ノードはゲームの基本的な構成要素」と説明しています。シーンは保存すると新しいノードの型のように扱え、いくつでもインスタンスを作れる再利用可能な部品になります。プレイヤー・敵・宝箱のような繰り返し登場するオブジェクトを個別のシーンとして分けておくと、Claude Codeに1つのシーンのスクリプトだけを渡して修正させる、という作業単位を切りやすくなります。

GDScriptはGodot専用のスクリプト言語です。extendsキーワードで継承元のノードクラスを指定し、_ready()や_process(delta)のような組み込み関数にゲームロジックを書きます。公式ドキュメントの例では、スプライトを毎フレーム回転させながら移動させるコードを次のように示しています。

extends Sprite2D
 
var speed = 400
var angular_speed = PI
 
func _process(delta):
    rotation += angular_speed * delta
    var velocity = Vector2.UP.rotated(rotation) * speed
    position += velocity * delta

_process()は定義すると毎フレーム呼ばれます。引数のdeltaには前フレームからの経過時間が渡ります。Claude Codeにこの関数を書かせるときは、移動量にdeltaを掛けているかどうかがフレームレート非依存の挙動になるかの分かれ目です。

Claude CodeにGodotプロジェクトを渡す準備

Claude CodeはCLAUDE.mdとauto memoryの2系統でプロジェクトの文脈を記憶します。Godotプロジェクトでは、ディレクトリ構成・命名規則・ヘッドレス実行コマンドをCLAUDE.mdに書いておくと、毎回の説明が要らなくなります。

# プロジェクト概要
Godot 4.7 で開発する2Dアクションゲーム。
 
## ディレクトリ構成
- scenes/ シーンファイル(.tscn)
- scripts/ GDScript(.gd)
 
## 実行・検証コマンド
- ヘッドレス実行: godot --headless --path .
- 特定シーンの起動: godot scenes/main.tscn
 
## コーディング規約
- 変数・関数はsnake_case
- シグナル名は状態変化を表す名詞(例: health_depleted)

CLAUDE.mdは強制設定ではなく文脈として読み込まれるだけです。具体的で簡潔な指示ほど従われやすくなります。書き込み禁止ディレクトリのように強制したい制約は、CLAUDE.mdでなくPreToolUse hookで縛るのが確実です。公式ドキュメントはCLAUDE.mdのサイズについて、1ファイルあたり200行程度を目安にするよう案内しています。Godotプロジェクトが大きくなるほどシーン一覧やコーディング規約を書き足したくなりますが、長くなりすぎたらscripts/配下だけに読み込ませるパス限定ルールへ分割するほうが読み込み効率を保てます。

もう1つ準備しておきたいのがpermissions設定です。GodotのCLIコマンドを都度確認なしで実行したい場合、.claude/settings.jsonにBashの許可ルールを追加します。

{
  "permissions": {
    "allow": [
      "Bash(godot --headless *)",
      "Bash(godot -s *)"
    ],
    "deny": [
      "Bash(godot --export-release *)"
    ]
  }
}

allowとdenyはどちらもツール名とパターンの組で書くルールです。エクスポート系のコマンドは成果物を書き出す操作なので、denyで確認を挟む側に倒すと事故を防げます。

シーンとノードをClaude Codeに実装させる

シーンの新規作成やノードの配置は、Godotエディタでの視覚的な操作が主体になる作業です。Claude Codeに向くのは、すでにあるシーン構成を前提にした.gdファイルの実装やリファクタリングのほうです。

シーンツリーの情報をClaude Codeに渡すときは注意が要ります。.tscnファイルの中身をそのまま読ませるより、ノード名と型の一覧をCLAUDE.mdや指示文に書き出すほうが誤解が少なくなります。.tscnはテキスト形式ですが、UIDでシーン間の参照を管理しています。テキストエディタとしての直接編集は、この参照が壊れる原因になりやすい部分です。

複数のシーン(プレイヤー・敵・HUD)を並行して実装させたい場合は、Taskツールでサブエージェントを並列化する方法がそのまま使えます。プレイヤーの移動ロジック・敵の生成ロジック・スコア表示のUIロジックは依存関係が薄く、並列実装との相性がいい分担です。

GDScriptの実装をClaude Codeに任せる

ノード間の通信にはシグナルを使います。シグナルはノードで何かが起きたときに発せられる合図で、connect()で別のノードの関数と紐づけます。

extends Node2D
 
signal health_depleted
 
func take_damage(amount):
    health -= amount
    if health <= 0:
        health_depleted.emit()

呼び出す側は_ready()の中で接続します。

func _ready():
    var timer = get_node("Timer")
    timer.timeout.connect(_on_timer_timeout)

Buttonのpressed、Timerのtimeout、Area2Dのbody_enteredのように、Godotの組み込みノードには最初からシグナルが用意されています。Claude Codeに実装を依頼するときは、どのノードのどのシグナルに接続するかを先に指定すると、存在しないシグナル名を書かれる事故を防げます。

入力処理も同様にInputシングルトンから読み取ります。Input.is_action_pressed()はフレームごとに指定したアクションが押されているかを返す関数です。ui_left・ui_right・ui_upのように、Godotプロジェクトには最初から定義済みのアクション名があります。

func _process(delta):
    var direction = 0
    if Input.is_action_pressed("ui_left"):
        direction = -1
    if Input.is_action_pressed("ui_right"):
        direction = 1
 
    rotation += angular_speed * direction * delta
 
    var velocity = Vector2.ZERO
    if Input.is_action_pressed("ui_up"):
        velocity = Vector2.UP.rotated(rotation) * speed
    position += velocity * delta

Claude Codeにこの種のコードを書かせるときは、参照しているアクション名がproject.godotの入力設定に実在するかを確認してから使わせます。存在しないアクション名を書かれると、実行時までエラーに気づけません。

「Your first 2D game」をClaude Codeとどう分担するか

公式チュートリアルの「Your first 2D game」は、前段の「Step by step」シリーズを終えた読者を対象にしています。Dodge the Creeps!という1本のゲームを、プロジェクト設定・プレイヤーシーンの作成・プレイヤーのコーディング・敵キャラクターの作成・メインシーンの統合・HUDの実装・最終調整という7段階で組み立てます。

視覚的な配置が中心の段階と、ロジック実装が中心の段階ははっきり分かれます。プレイヤーシーン・敵シーン・HUDの見た目そのものはエディタでの配置作業が主体です。一方、プレイヤーの移動ロジック・敵のランダムな生成タイミング・スコアカウントのようなロジック部分はGDScriptのコードとして完結するため、Claude Codeに実装を任せやすい範囲です。

メインシーンで各シーンを統合する段階は両方の要素を含みます。実行中に敵のシーンを生成してツリーに追加する処理自体はコードで書けますが、生成位置や出現タイミングの調整は実機プレイでの確認が欠かせません。段階ごとに「コードで閉じるか」「見た目の確認が要るか」を切り分けておくと、Claude Codeへの依頼範囲を決めやすくなります。

ヘッドレスモードでGodotプロジェクトを検証する

Godotはウィンドウを開かずにコマンドラインだけで実行できます。--headlessフラグはGPUアクセスがない環境で必須になるオプションで、CI環境やClaude Codeのサンドボックス内での動作確認に向きます。

godot --headless --path .

特定のGDScriptだけを実行したい場合は-s(--script)を使います。対象のスクリプトはSceneTreeかMainLoopを継承している必要があります。

godot -s scripts/test_runner.gd

ヘッドレスモードでは入力デバイスやウィンドウに依存する処理が動きません。テスト用のスクリプトは、ロジック部分をSceneTreeベースの関数に切り出してから検証する形にすると安全です。失敗するテストを先に書いてからClaude Codeに実装させる進め方は、Claude CodeでTDDを回す手順で扱っているStop hookでの締め方とそのまま組み合わせられます。GUIがないクラウド環境でこのループを回したいなら、Codespaces上でDevContainer開発を始める手順もヘッドレス実行と相性のいい構成です。

Claude Codeに任せる作業と任せない作業

作業の種類によって向き不向きがはっきり分かれます。

GodotとGDScript以外のエンジンでClaude Codeを使いたい場合、Unityには公式のMCPサーバーがあります。Unity公式MCPサーバーをClaude Codeで使う方法はエディタ操作をMCP経由で橋渡しする構成で、GDScriptのCLI中心のワークフローとは前提が異なります。

Godot開発でよくあるつまずき

• .tscnファイルをテキストとして直接編集させると、UID参照が壊れて別のシーンから読み込めなくなることがあります。シーン構成の変更はエディタ側の保存を挟むほうが安全です
• _process(delta)にdeltaを掛け忘れたコードは、フレームレートが変わると挙動も変わります。移動・回転系の実装では必ず確認します
• ヘッドレスモードは入力・描画に依存する処理を実行できません。テストスクリプトはロジック部分だけをSceneTreeベースに切り出しておきます
• Bash(godot *)のように広いパターンでallowを書くと、-sで任意のGDScriptを無確認で実行できてしまいます。実行対象を--headlessや-sの特定用途だけに絞るほうが安全です
• CLAUDE.mdにシーン構成やコーディング規約を詰め込みすぎると、200行の目安を超えて読み込み効率が落ちます。プロジェクトが育ったら内容を分割します

まとめ

Godot開発でClaude Codeが効くのは、シーン構成が固まった後のGDScript実装とヘッドレステストの領域です。CLAUDE.mdにディレクトリ構成と実行コマンドを書き、settings.jsonのallow/denyでGodot CLIの実行範囲を絞っておくと、シーン編集とスクリプト実装をはっきり分けて進められます。エディタでの視覚的な配置とコードでのロジック実装を混同せずに依頼範囲を決めることが、この組み合わせを無理なく続けるための分かれ目です。