mcpField
G
godot

godot

github.com/bfollington開発51118 回インストール2 週間前に更新
リポジトリ

godot について

godotは、Godot Engineでゲームやアプリを開発するLLMコーディングアシスタント向けのスキルです。シーンやリソースのファイル形式、検証、設計パターン、テンプレート、テスト手順を扱います。

主な機能

  1. 01.gd、.tscn、.tresのファイルガイド
  2. 02シーンとリソースの検証スクリプト
  3. 03コンポーネントとシグナル駆動の設計
  4. 04再利用可能なコードとリソースのテンプレート
  5. 05GUTによるユニットテストのガイド

活用シーン

  1. 01Godotのシーンやリソースの作成・編集
  2. 02リソース読み込みや構文エラーの調査
  3. 03コンポーネント型ゲームシステムの構築
  4. 04GUTを使ったゲームロジックのテスト

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/bfollington/terma --skill godot

インストール後、Claude Code で/godotを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

assets/templates/
attribute_template.gd
component_template.gd
interaction_template.gd
item_resource.tres
spell_resource.tres
references/
architecture-patterns.md
common-pitfalls.md
file-formats.md
godot4-physics-api.md
scripts/
validate_tres.py
validate_tscn.py

詳細

Godot Engine 開発スキル

Godot Engine でゲームやアプリケーションを開発するための専門的なガイダンスです。LLM コーディングアシスタントと Godot 独自のファイル構造との効果的な連携に重点を置いています。

概要

Godot プロジェクトでは、GDScript コードファイル(.gd)とテキストベースのリソースファイル(シーン用の .tscn、リソース用の .tres)を組み合わせて使用します。GDScript はわかりやすい一方で、リソースファイルには GDScript の構文とは大きく異なる厳密な書式要件があります。このスキルでは、Godot プロジェクトを効果的に開発するためのファイル形式に関する専門知識、実績のあるアーキテクチャパターン、検証ツール、コードテンプレート、デバッグのワークフローを提供します。

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

次の場合にこのスキルを呼び出してください。

  • Godot Engine プロジェクトで作業するとき
  • .tscn(シーン)ファイルまたは .tres(リソース)ファイルを作成・変更するとき
  • ゲームシステム(インタラクション、属性、呪文、インベントリなど)を実装するとき
  • 「ファイルの読み込みに失敗しました」などのリソースエラーをデバッグするとき
  • コンポーネントベースのアーキテクチャを設定するとき
  • シグナル駆動型システムを作成するとき
  • リソースベースのデータ(アイテム、呪文、アビリティ)を実装するとき

重要な原則

1. ファイル形式の違いを理解する

GDScript(.gd)- 完全なプログラミング言語:

extends Node
class_name MyClass

var speed: float = 5.0
const MAX_HEALTH = 100

func _ready():
    print("Ready")

シーンファイル(.tscn)- 厳密なシリアライズ形式:

[ext_resource type="Script" path="res://script.gd" id="1"]

[node name="Player" type="CharacterBody3D"]
script = ExtResource("1")  # NOT preload()!

リソースファイル(.tres)- GDScript の構文は使用不可:

[ext_resource type="Script" path="res://item.gd" id="1"]

[resource]
script = ExtResource("1")  # NOT preload()!
item_name = "Sword"        # NOT var item_name = "Sword"!
2. .tres および .tscn ファイルに関する重要なルール

.tres/.tscn ファイルでは絶対に使用しないでください:

  • preload() - 代わりに ExtResource("id") を使用します
  • var、const、func - これらは GDScript のキーワードです
  • 型指定のない配列 - Array[Type]([...]) 構文を使用します

.tres/.tscn ファイルでは必ず使用してください:

  • 外部リソースには ExtResource("id")
  • インラインリソースには SubResource("id")
  • 型指定配列:Array[Resource]([...])
  • 使用前に適切な ExtResource 宣言を記述します
3. 関心事の分離

ロジックは .gd ファイルに、データは .tres ファイルに記述します:

src/
  spells/
    spell_resource.gd      # Class definition + logic
    spell_effect.gd        # Effect logic
resources/
  spells/
    fireball.tres          # Data only, references scripts
    ice_spike.tres         # Data only

これにより、LLM による編集がはるかに安全で明確になります。

4. コンポーネントベースのアーキテクチャ

機能を小さく、目的を絞ったコンポーネントに分割します:

Player (CharacterBody3D)
├─ HealthAttribute (Node)     # Component
├─ ManaAttribute (Node)        # Component
├─ Inventory (Node)            # Component
└─ StateMachine (Node)         # Component
    ├─ IdleState (Node)
    ├─ MoveState (Node)
    └─ AttackState (Node)

利点:

  • 各コンポーネントが小さく、目的の明確なファイルになります
  • 理解や変更が容易です
  • 責務が明確です
  • さまざまなエンティティで再利用できます
5. シグナル駆動型の通信

疎結合を実現するためにシグナルを使用します:

# Component emits signals
signal health_changed(current, max)
signal death()

# Parent connects to signals
func _ready():
    $HealthAttribute.health_changed.connect(_on_health_changed)
    $HealthAttribute.death.connect(_on_death)

利点:

  • システム間の密結合がありません
  • 新しいリスナーを簡単に追加できます
  • 自己文書化されます(シグナルから利用可能なイベントがわかります)
  • ゲームロジックを変更せずに UI を接続できます

同梱リソースの使用

検証スクリプト

Godot でテストする前に .tres ファイルと .tscn ファイルを検証し、構文エラーを早期に検出します。

.tres ファイルを検証:

python3 scripts/validate_tres.py resources/spells/fireball.tres

.tscn ファイルを検証:

python3 scripts/validate_tscn.py scenes/player/player.tscn

次の場合にこれらのスクリプトを使用します。

  • .tres/.tscn ファイルをプログラムで作成または編集した後
  • 「読み込みに失敗しました」エラーをデバッグするとき
  • シーンやリソースの変更をコミットする前
  • ユーザーからカスタムリソースに関する問題が報告されたとき
参考ドキュメント

詳細な情報が必要な場合は、参考ファイルを読み込みます。

references/file-formats.md - .gd、.tscn、.tres の構文に関する詳しい説明:

  • 各ファイル形式の完全な構文規則
  • よくある間違いとその例
  • 安全な編集パターンとリスクの高い編集パターン
  • ExtResource と SubResource の使用方法

references/architecture-patterns.md - 実績のあるアーキテクチャパターン:

  • コンポーネントベースのインタラクションシステム
  • 属性システム(体力、マナなど)
  • リソースベースの効果システム(呪文、アイテム)
  • インベントリシステム
  • ステートマシンパターン
  • パターンを組み合わせた例

次の場合にこれらの参考資料を読みます。

  • 新しいゲームシステムを実装するとき
  • .tres/.tscn の構文がわからないとき
  • ファイル形式のエラーをデバッグするとき
  • 新機能のアーキテクチャを計画するとき
コードテンプレート

一般的なパターンの出発点としてテンプレートを使用します。テンプレートは assets/templates/ にあります。

component_template.gd - シグナル、エクスポート、アクティベーションを備えた基本コンポーネント:

# Copy and customize for new components
cp assets/templates/component_template.gd src/components/my_component.gd

attribute_template.gd - 数値属性(体力、マナ、スタミナ):

# Use for any numeric attribute with min/max
cp assets/templates/attribute_template.gd src/attributes/stamina_attribute.gd

interaction_template.gd - インタラクションコンポーネントの基本クラス:

# Extend for custom interactions (pickup, door, switch, etc.)
cp assets/templates/interaction_template.gd src/interactions/lever_interaction.gd

spell_resource.tres - 効果を備えた呪文の例:

# Use as reference for creating new spell data
cat assets/templates/spell_resource.tres

item_resource.tres - アイテムリソースの例:

# Use as reference for creating new item data
cat assets/templates/item_resource.tres

ワークフロー

ワークフロー 1:新しいコンポーネントシステムの作成

例:敵に体力システムを追加します。

手順:

  1. アーキテクチャパターンのリファレンスを読む:

    # Check for similar patterns
    Read references/architecture-patterns.md
    # Look for "Attribute System" section
    
  2. テンプレートを使って基本クラスを作成する:

    cp assets/templates/attribute_template.gd src/attributes/attribute.gd
    # Customize the base class
    
  3. 専用のサブクラスを作成する:

    # Create health_attribute.gd extending attribute.gd
    # Add health-specific signals (damage_taken, death)
    
  4. .tscn の編集でシーンに追加する:

    [ext_resource type="Script" path="res://src/attributes/health_attribute.gd" id="4_health"]
    
    [node name="HealthAttribute" type="Node" parent="Enemy"]
    script = ExtResource("4_health")
    value_max = 50.0
    value_start = 50.0
    
  5. Godot エディターですぐにテストする

  6. 問題がある場合は、シーンファイルを検証する:

    python3 scripts/validate_tscn.py scenes/enemies/base_enemy.tscn
    
ワークフロー 2:リソースデータファイル(.tres)の作成

例:新しい呪文を作成します。

手順:

  1. テンプレートを参照する:

    cat assets/templates/spell_resource.tres
    
  2. 適切な構造で新しい .tres ファイルを作成する:

    [gd_resource type="Resource" script_class="SpellResource" load_steps=3 format=3]
    
    [ext_resource type="Script" path="res://src/spells/spell_resource.gd" id="1"]
    [ext_resource type="Script" path="res://src/spells/spell_effect.gd" id="2"]
    
    [sub_resource type="Resource" id="Effect_1"]
    script = ExtResource("2")
    effect_type = 0
    magnitude_min = 15.0
    magnitude_max = 25.0
    
    [resource]
    script = ExtResource("1")
    spell_name = "Fireball"
    spell_id = "fireball"
    mana_cost = 25.0
    effects = Array[ExtResource("2")]([SubResource("Effect_1")])
    
  3. テスト前に検証する:

    python3 scripts/validate_tres.py resources/spells/fireball.tres
    
  4. バリデーターで報告されたエラーを修正する

  5. Godot エディターでテストする

ワークフロー 3:リソース読み込み問題のデバッグ

ユーザーから「リソースの読み込みに失敗しました」などのエラーが報告された場合に使用します。

手順:

  1. エラーで報告されたファイルを読む:

    # Check file syntax
    Read resources/spells/problem_spell.tres
    
  2. 検証スクリプトを実行する:

    python3 scripts/validate_tres.py resources/spells/problem_spell.tres
    
  3. よくある間違いを確認する:

    • ExtResource() の代わりに preload() を使用している
    • var、const、func キーワードを使用している
    • ExtResource 宣言が不足している
    • 配列構文が正しくない(型指定されていない)
  4. 必要に応じてファイル形式のリファレンスを読む:

    Read references/file-formats.md
    # Focus on "Resource Files (.tres)" section
    # Check "Common Mistakes Reference"
    
  5. エラーを修正して再検証する

ワークフロー 4:アーキテクチャパターンに基づく実装

既知のパターン(インタラクションシステム、ステートマシンなど)を実装する場合に使用します。

手順:

  1. 該当するパターンを読む:

    Read references/architecture-patterns.md
    # Find the specific pattern (e.g., "Component-Based Interaction System")
    
  2. 該当するテンプレートをコピーする:

    cp assets/templates/interaction_template.gd src/interactions/door_interaction.gd
    
  3. テンプレートをカスタマイズする:

    • _perform_interaction() をオーバーライドする
    • 設定用のカスタムエクスポートを追加する
    • 必要に応じてカスタムシグナルを追加する
  4. パターンに沿ってシーン構造を作成する:

    [node name="Door" type="StaticBody3D"]
    script = ExtResource("base_interactable.gd")
    
    [node name="DoorInteraction" type="Node" parent="."]
    script = ExtResource("door_interaction.gd")
    interaction_text = "Open Door"
    
  5. 段階的にテストする

GUT によるユニットテスト

純粋なロジックのテストには GUT(Godot Unit Testing)を使用します。シーンツリーに依存しない RefCounted または Resource クラスは、いずれもテストに適しています。カードシステム、スコアリング、ステートマシン、マップジェネレーター、チャレンジロジックなどが対象です。

インストール
  1. GitHub のリリースからダウンロードする(v9.5.0 は Godot 4.5 で動作します。v9.6.0 以降には、より新しい Godot が必要です)
  2. addons/gut/ をプロジェクトに配置する
  3. プロジェクト設定 → プラグインでプラグインを有効にする
  4. プロジェクトのルートに .gutconfig.json を作成する:
{
  "dirs": ["res://test/unit"],
  "prefix": "test_",
  "suffix": ".gd",
  "log_level": 1
}
テストの作成

テストは test/unit/ に配置し、ファイル名の先頭に test_ を付け、GutTest を継承します。

extends GutTest

func test_score_calculation() -> void:
    var scoring := Scoring.new()
    assert_eq(scoring.calculate(3, 0), 100, "Base score for 3 moves")
    assert_gt(scoring.calculate(2, 0), scoring.calculate(3, 0), "Fewer moves = higher score")

func test_deck_shuffle() -> void:
    var rng := RandomNumberGenerator.new()
    rng.seed = 42
    var deck := CardSystem.create_shuffled_deck(rng)
    assert_eq(deck.size(), 52, "Full deck")

主な規則:

  • テストメソッド名は test_ で始める必要があります
  • ヘルパーメソッドには _ 接頭辞を付けます(テストとして検出されません)
  • セットアップ/ティアダウンには before_each() / after_each() を使用します
  • 主なアサーション:assert_eq、assert_ne、assert_true、assert_false、assert_gt、assert_lt、assert_null、assert_not_null
テストの実行
# Run all tests (returns exit code 0 on pass, 1 on fail)
godot -d -s --path "$PWD" addons/gut/gut_cmdln.gd -gexit

# Run a specific test file
godot -d -s --path "$PWD" addons/gut/gut_cmdln.gd -gtest=res://test/unit/test_scoring.gd -gexit

# Run tests matching a pattern
godot -d -s --path "$PWD" addons/gut/gut_cmdln.gd -gdir=res://test/unit -gselect=weekly -gexit
テスト対象

RefCounted または Resource を継承する、純粋なロジッククラスのテストを優先します。

  • ゲームルールとスコアリング
  • カード/デッキ/手札の管理
  • マップ生成(正確な出力ではなく、特性を検証します)
  • 状態のスナップショット/復元
  • アップグレード/進行度の計算

シーンツリーに依存するコード(レンダリング、UI、入力処理)は、ユニットテストでのテストを避けてください。

よくある落とし穴と解決策

落とし穴 1:.tres ファイルで GDScript の構文を使用する

問題:

# ❌ WRONG
script = preload("res://script.gd")
var items = [1, 2, 3]

解決策:

# ✅ CORRECT
[ext_resource type="Script" path="res://script.gd" id="1"]
script = ExtResource("1")
items = Array[int]([1, 2, 3])

予防策: テスト前に検証スクリプトを実行します。

落とし穴 2:ExtResource 宣言が不足している

問題:

[resource]
script = ExtResource("1_script")  # Not declared!

解決策:

[ext_resource type="Script" path="res://script.gd" id="1_script"]

[resource]
script = ExtResource("1_script")

検出方法: 検証スクリプトで検出できます。

落とし穴 3:複雑な .tscn の階層構造の編集

問題: インスタンス化されたシーンの子ノードを変更すると、エディターで再保存した際に問題が発生することがあります。

解決策:

  • .tscn ファイルでは、シンプルなプロパティの編集だけを行います
  • 複雑な変更には、Godot エディターを使用します
  • テキスト編集後はすぐにテストします
  • git で変更を追跡し、必要に応じて元に戻します
落とし穴 4:.tres ファイル内の型指定されていない配列

問題:

effects = [SubResource("Effect_1")]  # Missing type

解決策:

effects = Array[Resource]([SubResource("Effect_1")])

予防策: 検証スクリプトで警告が表示されます。

落とし穴 5:インスタンスのプロパティオーバーライドを忘れる

問題: シーンをインスタンス化する際に、子ノードのプロパティをオーバーライドし忘れることがあります。インスタンスではデフォルト値(多くの場合 null)が使用されるため、気づきにくいバグの原因になります。

# level.tscn
[node name="KeyPickup" parent="." instance=ExtResource("6_pickup")]
# Oops! PickupInteraction.item_resource is null - pickup won't work!

解決策: index 構文を使って、インスタンス化したシーンのプロパティを必ず設定します。

[node name="KeyPickup" parent="." instance=ExtResource("6_pickup")]

[node name="PickupInteraction" parent="KeyPickup" index="0"]
item_resource = ExtResource("7_key")

検出方法:

  • インスタンスをゲーム内ですぐにテストします
  • 詳細については、references/file-formats.md の「Instance Property Overrides」セクションを読みます
  • シーンインスタンスを作成する際に、「このシーンには、プロパティの設定が必要な構成可能なコンポーネントがあるか」と確認します

予防策: 構成可能な子ノード(PickupInteraction、DoorInteraction など)を持つシーンをインスタンス化した後は、重要なプロパティが必ずオーバーライドされていることを確認します。

落とし穴 6:CPUParticles3D の color_ramp に色が表示されない

問題: CPUParticles3D に color_ramp を設定しても、パーティクルが白く見えたり、グラデーションの色が表示されなかったりします。

[node name="CPUParticles3D" type="CPUParticles3D" parent="."]
mesh = SubResource("SphereMesh_1")
color_ramp = SubResource("Gradient_1")  # Gradient is set but doesn't work!

根本原因: パーティクルの色をメッシュの表面に適用するには、メッシュに vertex_color_use_as_albedo = true を設定したマテリアルが必要です。

解決策: 頂点カラーを有効にした StandardMaterial3D をメッシュに追加します。

[sub_resource type="StandardMaterial3D" id="StandardMaterial3D_1"]
vertex_color_use_as_albedo = true

[sub_resource type="SphereMesh" id="SphereMesh_1"]
material = SubResource("StandardMaterial3D_1")
radius = 0.12
height = 0.24

[node name="CPUParticles3D" type="CPUParticles3D" parent="."]
mesh = SubResource("SphereMesh_1")
color_ramp = SubResource("Gradient_1")  # Now works!

予防策: color または color_ramp を使って CPUParticles3D を作成する場合は、必ず vertex_color_use_as_albedo = true を設定したマテリアルをメッシュに追加します。

ベストプラクティス

1. よくある問題についてリファレンスを参照する

問題が発生した場合は、リファレンスドキュメントを参照します。

references/common-pitfalls.md - Godot でよくある落とし穴と解決策:

  • 初期化と @onready のタイミングに関する問題
  • ノード参照と get_node() に関する問題
  • シグナル接続に関する問題
  • リソースの読み込みと変更
  • CharacterBody3D の移動
  • Transform と basis の混同
  • 入力処理
  • 型安全性に関する問題
  • シーンのインスタンス化に関する落とし穴
  • Tween に関する問題

references/godot4-physics-api.md - Physics API のクイックリファレンス:

  • 正しいレイキャスト API(PhysicsRayQueryParameters3D)
  • シェイプクエリと衝突検出
  • 衝突レイヤーとマスク
  • Area3D と RigidBody3D、CharacterBody3D の使い分け
  • よく使われる Physics のパターン
  • パフォーマンスのヒント

以下の場合に読み込みます:

  • null 参照エラーが発生した場合
  • Physics/衝突システムを実装する場合
  • @onready のタイミングに関する問題をデバッグする場合
  • CharacterBody3D の移動を扱う場合
  • レイキャストまたはシェイプクエリを設定する場合
2. .tres/.tscn の編集後は必ず検証する
python3 scripts/validate_tres.py path/to/file.tres
python3 scripts/validate_tscn.py path/to/file.tscn
2. テンプレートを出発点として使う

コンポーネントをゼロから書かず、テンプレートを応用します。

cp assets/templates/component_template.gd src/my_component.gd
3. 詳細な構文はリファレンスを読む

構文がわからない場合は、リファレンスを読み込みます。

Read references/file-formats.md
4. 関心の分離に従う
  • ロジック → .gd ファイル
  • データ → .tres ファイル
  • シーン構造 → .tscn ファイル(複雑な変更にはエディターを優先)
5. 通信にはシグナルを使う

メソッドの直接呼び出しより、シグナルを優先します。

# ✅ Good - Loose coupling
signal item_picked_up(item)
item_picked_up.emit(item)

# ❌ Avoid - Tight coupling
get_parent().get_parent().add_to_inventory(item)
6. 段階的にテストする

変更のたびに:

  1. スクリプトで検証します
  2. Godot エディターでテストします
  3. 機能を確認します
  4. git にコミットします
7. エクスポート変数を積極的に使う

設定を見えるようにし、編集可能にします。

@export_group("Movement")
@export var speed: float = 5.0
@export var jump_force: float = 10.0

@export_group("Combat")
@export var damage: int = 10

Godot CLI の使用

godot コマンドラインツールを使うと、エディターを開かずにゲームを実行したり、さまざまな操作を行ったりできます。

ゲームの実行

現在のプロジェクトを実行する:

godot --path . --headless

特定のシーンを実行する:

godot --path . --scene scenes/main_menu.tscn

デバッグフラグを指定して実行する:

# Show collision shapes
godot --path . --debug-collisions

# Show navigation debug visuals
godot --path . --debug-navigation

# Show path lines
godot --path . --debug-paths
コードの確認/検証

実行せずに GDScript の構文を確認する:

godot --path . --check-only --script path/to/script.gd

ヘッドレステストを実行する(自動テスト用):

godot --path . --headless --quit --script path/to/test_script.gd
本物のバグに見える、ヘッドレス実行時の落とし穴が2つあります

新しく作成した class_name は、プロジェクトを再インポートするまで --check-only で失敗します。 ヘッドレスチェックでは、プロジェクトのキャッシュ済みクラスリストからグローバルクラスを解決します。このリストには、作成したばかりのスクリプトがまだ含まれていません。症状として、もっともらしい誤った解析エラーが表示されます。

Parse Error: Identifier "MyNewClass" not declared in the current scope

一度修正してから、もう一度チェックしてください。

godot --path . --import --headless --quit

static func を使ったユーティリティクラスが多数あるコードベースでは、特にこの問題が発生しやすくなります。新しい型が複数のファイルから同時に参照されるため、エラーが本当の依存関係不足のように見えてしまいます。

サンドボックス化されたエージェントのシェル内で、ヘッドレス Godot がクラッシュまたはハングします。 プロセスが user://logs/... に書き込めない場合、handle_crash: Program crashed with signal 11 で終了するか、XPC の Connection Invalid でハングします。タイムアウトを設定したテストランナーでは、どちらも出力が空のままゼロ以外の終了コードになります。どちらもテスト対象コードの本物の不具合のように見えるため、そのようにデバッグされますが、原因はファイルシステムへの書き込み拒否だけです。紛らわしいバックトレースが表示されてからではなく、最初の起動からサンドボックスを無効にして Godot を実行し、サブエージェントにも最初に同じことを伝えてください。サブエージェントも個別にこの問題に遭遇し、それぞれ同じ30分を無駄にします。

CLI からのエディター操作

エディターを開かずにリソースをインポートする:

godot --path . --import --headless --quit

プロジェクトをエクスポートする:

# Export release build
godot --path . --export-release "Preset Name" builds/game.exe

# Export debug build
godot --path . --export-debug "Preset Name" builds/game_debug.exe
よくある CLI ワークフロー

ワークフロー:クイックテスト実行

# Run the project and quit after testing
godot --path . --quit-after 300  # Runs for 300 frames then quits

ワークフロー:リソースの自動インポート

# Import all resources and exit (useful in CI/CD)
godot --path . --import --headless --quit

ワークフロー:スクリプトの検証

# Validate a GDScript file before committing
godot --path . --check-only --script src/player/player.gd

ワークフロー:ヘッドレスサーバー

# Run as dedicated server (no rendering)
godot --path . --headless --scene scenes/multiplayer_server.tscn
CLI の使用上のヒント
  1. プロジェクトディレクトリから実行するときは、Godot が project.godot を見つけられるように、必ず --path . を指定してください
  2. CI/CD と自動テストでは、ウィンドウもレンダリングも使わない --headless を使用してください
  3. タスク完了後に自動終了するには、--quit または --quit-after N を使用してください
  4. GDScript の構文をすばやく検証するには、--check-only と --script を組み合わせてください
  5. 開発中にシステムを視覚化するには、デバッグフラグ(--debug-collisions、--debug-navigation)を使用してください
  6. 終了コードを確認してください。ゼロ以外はエラーを示します(CI/CD スクリプトで役立ちます)
例:GDScript を検証する pre-commit フック
#!/bin/bash
# Validate all changed .gd files before committing

for file in $(git diff --cached --name-only --diff-filter=ACM | grep '\.gd$'); do
    if ! godot --path . --check-only --script "$file" --headless --quit; then
        echo "GDScript validation failed for $file"
        exit 1
    fi
done

クイックリファレンス

ファイル形式の選択フローチャート

ゲームロジックを書く場合は? → .gd ファイルを使用します

データ(アイテムのステータス、スペルの設定など)を保存する場合は? → .tres ファイルを使用します

シーン構造を作成する場合は? → .tscn ファイルを使用します(複雑な構造には Godot エディターの使用をおすすめします)

構文のクイックチェック

.gd ファイルの場合: 完全な GDScript を使用します。var、func、preload() など ✅

.tres/.tscn ファイルの場合:

  • preload() ❌ → ExtResource("id") を使用 ✅
  • var、const、func ❌ → プロパティ値のみ ✅
  • [1, 2, 3] ❌ → Array[int]([1, 2, 3]) ✅
各検証スクリプトを使用する場面

validate_tres.py - リソースファイル用:

  • アイテム、スペル、アビリティ
  • カスタムリソースデータ
  • .tres ファイルを作成した後

validate_tscn.py - シーンファイル用:

  • プレイヤー、敵、レベル
  • UI シーン
  • .tscn ファイルを編集した後
各リファレンスを読む場面

file-formats.md - 次の場合:

  • .tres/.tscn ファイルを作成または編集するとき
  • 「failed to load」エラーが発生したとき
  • 構文ルールがわからないとき

architecture-patterns.md - 次の場合:

  • 新しいゲームシステムを実装するとき
  • コンポーネント構造を計画するとき
  • 実績のあるパターンを探すとき

まとめ

次の方法で、Godot プロジェクトを効果的に扱えます。

  1. ファイル形式を理解する - .gd はコード、.tres/.tscn は厳密な構文を持つデータです
  2. 検証ツールを使う - テスト前にエラーを見つけます
  3. パターンに従う - リファレンスにある実績のあるアーキテクチャを使います
  4. テンプレートから始める - ゼロから作るのではなく、既存のものを応用します
  5. 段階的にテストする - 頻繁に検証、テスト、コミットします

重要なポイントは、GDScript とリソースシリアライズ形式の構文の違いを守れば、Godot のテキストベースのファイルは LLM と相性がよいということです。

コメント