godot-gdscript-mastery

GDScript を使いこなす

パフォーマンスと保守性に優れた GDScript を書くための専門的なガイダンスです。スタイルガイドの焼き直しではなく、Godot 固有の落とし穴に対応する判断ツリーを紹介します。

読み込まないでください

• 一般的な文章のスタイルや Godot エンジンのバージョンアップ（3→4 / 4.x への移行）には、このスキルを読み込まないでください。これらについては godot-version-migration（および同ハブから参照できる公式アップグレードガイド）で扱っています。
• 以下のスクリプトをすべて事前に読み込まないでください。実装するコアディレクティブに対応する必須の参照先だけを開いてください。
• EditorScript ユーティリティ（type_checker、performance_analyzer、signal_architecture_validator）を、実行時のゲームプレイコードとして扱わないでください。

GDScript で絶対にしないこと

• 同じ変数に @onready と @export を絶対に併用しないでください — 初期化順序によって、@onready がインスペクターの値を上書きします。
• 反復処理中に Dictionary のサイズを絶対に変更しないでください — 要素を安全に削除するには、dict.keys().duplicate() を使うか、複製したものを反復処理してください。
• 文字列ベースの connect("signal", ...) を絶対に使わないでください — コンパイル時の安全性を確保するため、必ず Signal オブジェクト構文（button.pressed.connect(...)）を使ってください。
• 非仮想のネイティブエンジンメソッドを絶対にオーバーライドしないでください — queue_free() や get_class() のオーバーライドはサポートされておらず、エンジンのコールバックによって無視されます。
• _process() 内で動的な get_node() や $ を絶対に使わないでください — 毎フレームパスを取得すると CPU が停滞します。キャッシュして @onready を使ってください。
• Parent.method() の呼び出しを絶対に使わないでください — 「上にはシグナルで通知し、下には呼び出す」という原則に反します。親との通信にはシグナルを使ってください。
• is の後にハードキャストを絶対に使わないでください — 型チェックに通った後でオブジェクトが変わると、クラッシュします。as を使い、null かどうかを確認してください。
• 本番環境のデバッグに print() を絶対に使わないでください — push_error()、push_warning()、またはブレークポイントを使ってください。
• _ready() 内で巨大なリソースを絶対に事前読み込みしないでください — 非同期読み込みには ResourceLoader.load_threaded_request() を使ってください。
• static var で十分な場合に、Autoload のグローバル変数を絶対に使わないでください — 静的変数を使うと、カプセル化が向上します。

---

コアディレクティブ（判断ツリー＋必須スクリプト）

1. 強い型付けとパフォーマンス

落とし穴	判断
ホットパスにまだ Variant が残っていますか？	変数と戻り値に型注釈を付け、型付きコレクションを優先してください
_process 内で汎用的な数学関数を使っていますか？	型付きヘルパー（absf、ceili、clampf）を使ってください
グリーンの安全行が不足していますか？	:= または明示的な型指定で型推論を修正してください

必須: typed_collections_mastery.gd、array_preallocation_perf.gd、type_checker.gd（EditorScript による監査）。

2. シグナルアーキテクチャ

落とし穴	判断
子ノードが親の反応を必要としていますか？	シグナルを上に送出し、親のメソッドは絶対に呼び出さないでください
スクリプト間のペイロードが安全ではありませんか？	型付きの signal name(arg: Type) を使ってください
接続箇所が見えていますか？	エディターのみで設定する見えない接続より、_ready() での接続を優先してください

必須: typed_signal_definitions.gd、signal_architecture_validator.gd。

3. ノードアクセスとライフサイクルの安全性

落とし穴	判断
子ノードが必要ですか？	@onready / %UniqueName を使ってください — _init() 内では絶対に使わないでください
シーンにインスタンス化されたノードにコンストラクター引数が必要ですか？	@export による注入を使ってください — _init(args) は PackedScene.instantiate() を壊します
毎フレームパスを検索していますか？	一度だけキャッシュしてください。_process 内では $ / get_node を絶対に使わないでください

必須: safe_type_casting.gd。

4. Callable とシグナル (ファーストクラス)

地雷	判断
コールバックに追加のコンテキストを渡すには？	Callable.bind(...)
未使用のシグナル引数を破棄するには？	Callable.unbind(n)
一度きりのタイムアウト処理は？	インラインラムダで OK。create_callback 形式の寿命が重要なら参照を保持する

必須: callable_binding_context.gd、unbind_signal_args.gd、advanced_lambdas.gd、functional_lambda_logic.gd。

5. 非同期、静的、安全なコレクション

地雷	判断
スレッドなしでタイマーを順序付けするには？	await チェーン — await マネージャーを参照
Autoload を肥大化させずにグローバル状態を扱うには？	static var (使い終わったら大きな静的変数は null 化する)
Dictionary の反復中に削除するには？	先にキーをクローンする

必須: await_sequence_manager.gd、static_var_singleton_alt.gd、dictionary_safe_iteration.gd、performance_analyzer.gd (EditorScript)。

スクリプトカタログ (全ファイル)

スクリプト	開くタイミング
typed_collections_mastery.gd	型付き Array/Dictionary のオペコード
functional_lambda_logic.gd	reduce / all / any
advanced_lambdas.gd	高階 Callable
safe_type_casting.gd	as + null チェック
typed_signal_definitions.gd	型付きシグナルの境界
callable_binding_context.gd	bind() によるコンテキスト注入
unbind_signal_args.gd	unbind() による引数数の調整
await_sequence_manager.gd	ノンブロッキングな await フロー
array_preallocation_perf.gd	resize() による事前確保
static_var_singleton_alt.gd	軽量なグローバル状態
dictionary_safe_iteration.gd	安全な反復中削除
type_checker.gd	EditorScript による型チェック監査
performance_analyzer.gd	EditorScript によるホットパススキャン
signal_architecture_validator.gd	EditorScript によるシグナル接続チェック

クイック地雷

• 存在が不確かな場合は dict["key"] よりも dict.get("key", default) を優先してください。
• 重要な UI/ノードでは Access as Scene Unique Name を有効にし、%Name で読み取ってください。
• スクリプトのレイアウト順: extends → class_name → signals/enums/consts → exports/onready → lifecycle → public → _private。

エキスパート知識 (オンデマンド)

LLM 不知ルール: 一般的なエージェントが読む前に知らないであろう情報は、リファレンスをロードしてください — エキスパートの差分を決して削除しないでください。

• gdscript-core-directives.md — 復元されたベースラインの教育内容 (アーキテクチャ、WHY、実装の深さ)

リファレンス

段階的開示: 特定の API を調査するときだけ Official Documentation のリンクを開いてください。ピア領域へルーティングするときは Related Skills をロードしてください — ラティス全体を事前読み込みしないでください。

公式ドキュメント

• GDScript の基本 — 型付き変数や関数、signal 宣言、await、ファーストクラスの Callable など、このスキルで標準化する言語の中核について説明します。
• GDScript スタイルガイド — レビューやリファクタリングで使用する、標準的なスクリプトの記述順序（extends → class_name → signals → exports → lifecycle → methods）を説明します。
• GDScript の静的型付け — 型付きの Array／Dictionary と戻り値の型によって、最適化されたオペコードやエディターのセーフラインを利用できる理由を説明します。
• GDScript：動的言語の入門 — filter／map／reduce ヘルパーの背景にあるラムダ、高階 Callable、応用パターンについて説明します。
• GDScript の警告システム — 安全でないキャスト、未使用のシグナル、型指定のないホットパスを、CI で確認できる警告にします。
• ロジックに関する推奨事項 — スクリプトの疎結合を保つために、宣言的なシグナルと命令的な呼び出しのどちらを優先するかについて説明します。
• シーンの構成 — このスキルで徹底する、公式の「シグナルは上へ、呼び出しは下へ」という所有権ルールについて説明します。
• シグナルの使用 — 接続／発行のモデルと、名前による文字列ベースの接続を避ける理由について説明します。
• Callable — ラッパーノードを使わずにコールバック引数を注入または破棄するための bind()／unbind() API について説明します。
• Array — スクリプトで使用する型付き配列、resize()、関数型メソッド（filter／map／reduce／all／any）について説明します。
• Dictionary — .get() の安全な既定値と、キーの反復中にサイズを変更してはいけない理由について説明します。
• CPU の最適化 — _process ループ内で get_node／$ を使う代わりに、@onready／%UniqueName をキャッシュします。

関連スキル

前提条件

• godot-project-foundations — 型付き GDScript スクリプトが組み込まれる、プロジェクトの構成、Autoload の登録、シーンの所有権に関する規約について説明します。
• godot-composition — スタイルを適用する前に、どのスクリプトがシグナルを所有し、どれが下方向への呼び出し API を所有するかを明確にするコンポーネントの境界について説明します。

補完

• godot-version-migration — エンジンのバージョンアップグレード（3→4 の言語破壊的変更、4.x の移行）；このスキルは現在の GDScript 2.0 のイディオムにとどまります。
• godot-signal-architecture — このスキルの型付きシグナル／Callable の基本を踏まえ、connect フラグ、バス、シーケンサーを深掘りします。
• godot-autoload-architecture — 重量級の Autoload と、ここで示す static var シングルトンの代替案を対比します。
• godot-resource-data-patterns — 共有設定には Resource を優先し、GDScript モジュールは Resource ペイロードを中心に薄く型付きに保ちます。
• godot-scene-management — @onready、ユニーク名、await シーケンスは、シーンの差し替えやローダーをまたいでも有効であり続ける必要があります。
• godot-testing-patterns — 型付きシグナルと Callable により、単体テストで watch_signals／スパイが信頼できるものになります。
• godot-debugging-profiling — ホットパスが依然として遅い場合は、このスキルのスタイル／パフォーマンスの臭いをプロファイラーやカスタムモニターと組み合わせます。
• godot-state-machine-advanced — FSM の enter／exit ハンドラーは、同じ型付きシグナルと await シーケンスの規約に従うべきです。

下流／利用側

• godot-performance-optimization — 型付き GDScript だけでは不十分な場合にエスカレーションします。サーバー、プーリング、より広範な CPU／GPU 戦術はそちらにあります。
• godot-auditor — プロジェクト全体の監査は、このスキルで成文化された型付け、シグナルの流れ、ホットパスのルールを利用します。
• godot-ability-system — アビリティには、これらの言語パターンに基づく型付きシグナルペイロードと await セーフなクールダウンが必要です。
• godot-combat-system — ダメージ／死亡のファンアウトは、ここで教える型付き emit と安全なキャストに依存します。

マスター

• godot-master — ライブラリのルーターおよびミラーリングされたモジュールのエントリー。横断的なスクリプティング上の関心事をどのドメインスキルが担うかを探すときに開きます。