godot-brainstorming

Godot のブレインストーミング

Godot 4.3 以降の機能やシステムのための、構造化された設計プロセスです。実装コードを一行も書く前に、何もない状態から明確なシーンツリー、シグナルマップ、データフローを作成します。

関連スキル： まず未決定の設計事項を整理する godot-grill、シーンツリーの構成パターンを扱う scene-organization、コンポーネントベースのアーキテクチャを扱う component-system、シグナルベースの通信設計を扱う event-bus。

---

プロセス：ブレインストーミングの進め方

設計にいきなり取りかからないでください。次の手順に従ってください。

ステップ 1：決定事項を整理する

リクエストに未決定の設計事項（スコープ、次元、権限、データの保管先など）がある場合は、godot-prompter:godot-grill を呼び出し、最後まで実行します。プロジェクトの決定事項や ADR ディレクトリに、この機能について記録がすでにある場合、またはユーザーが決定事項を述べている場合は、この手順を省略してください。いずれの場合も、すでにあるもの（コード、シーン、アセット）を確認します。その記録をステップ 2 に引き継ぎ、各アプローチが確定済みの項目に従うようにします。

ステップ 2：2～3 個のアプローチを提案する

決定事項を整理したら、トレードオフを含めてアーキテクチャの選択肢を提案します。たとえば、次のような内容です。

• 「ステートマシンには Enum FSM と Node FSM のどちらが適しているか、それぞれに適した状況」
• 「システム間の通信に EventBus と直接シグナルのどちらを使うか、そのトレードオフ」 おすすめの案を先に示し、その理由を説明します。

ステップ 3：承認を得ながら設計する

設計をセクションごと（シーンツリー、シグナルマップ、データフロー）に提示します。次のセクションに進む前に、各セクションの後で「この内容でよさそうですか？」と尋ねます。

ステップ 4：実装の準備をする

設計の承認後：

1. エージェント向け指示セクションを追加するか確認する — このプロジェクトですでに使用しているエージェント向け指示ファイルに、GodotPrompter の統合セクションを追加するか尋ねます（下記の「エージェント向け指示の追加」を参照）。このセクションは、サブエージェントや今後のセッションに GodotPrompter のスキルを使うよう指示するものです。いずれかのファイルにすでに ## GodotPrompter セクションがある場合、またはユーザーが以前に断っている場合は、何も言わずに省略します。合意なしに追加してはいけません。

2. 実装計画を作成する — 計画作成スキル（例：superpowers:writing-plans）が利用可能な場合はそれを使用し、利用できない場合は設計を自分で順序付けされたタスクに分割します。いずれの場合も、計画の保存先は次の優先順位で決定します。ユーザーの指示またはプロジェクトのエージェント向け指示ファイル、次に計画作成スキルの規約、次に既存の計画ディレクトリです。どれにも該当しない場合はユーザーに尋ね、docs/plans/ を提案します。尋ねられない場合は docs/plans/ を使用します。

3. 各タスクにスキルを注記する — Godot のシステムに関わる計画内のすべてのタスクに、実装時に呼び出す godot-prompter:* スキルを記載する必要があります。例：

   • タスク 3：プレイヤーの移動 — 歩行、ダッシュ、ジャンプができる CharacterBody3D を作成します。 スキル：godot-prompter:player-controller、godot-prompter:input-handling

   これにより、別のプラグインが計画を実行する場合でも、実装エージェントが読み込むべき GodotPrompter のスキルを把握できます。

---

1. 使用する場面

次のような場合は、ここから始めてください。

• 新しい機能を追加する — 宝箱、会話システム、クラフトベンチ、スキルツリーなど
• 新しいシーンを作成する — どのノードを含めるか、それらがどのように通信するかを決める必要がある
• アプローチを選ぶ — 継承とコンポジション、Autoload と Resource、2D と 3D のどれにするか
• 構成に行き詰まっている — コードは動くものの、シーンツリーが適切でないと感じる
• 新しいメンバーを受け入れる — 既存システムの設計を説明する必要がある

必要なノードとその接続方法がすでに明確なら、このスキルは省略して実装してください。不確実さによって作業が滞っている場合に使用します。

---

2. シーンツリーの計画

Godot エディターを開く前に、紙の上（またはコメントブロック内）でシーンツリーを下書きします。各ノードについて、次の 3 つの質問に答えることが目的です。

1. このノードが所有するものは何か？（データ、子ノード、視覚的表現）
2. このノードが行うことは何か？（単一の責務）
3. 隣接するノードとどのように通信するか？（上方向へのシグナル、下方向へのメソッド呼び出し、横方向への EventBus）

計画の手順

1. ルートノードとその型を決めます。これにより、シーンが世界と交わす契約が定まります。
2. 直下の子ノードを、Godot のノード型ではなく役割ごとにグループ化して列挙します。
3. 各項目に Godot のノード型を割り当てます。
4. シーンが発信するシグナルと受信するシグナルをすべて特定します。
5. 別の .tscn ファイルにすべきノード（再利用候補）を明示します。

例：「Chest」インタラクティブオブジェクトの計画

ステップ 1 — 名前とルート型

Chest は、プレイヤーが近づいて開けるワールドオブジェクトです。物理ボディではなく、移動もしません。ルート：StaticBody2D または Node2D。

ステップ 2 — 役割ごとのグループ

• 視覚表現（スプライト、アニメーション）
• 衝突／インタラクションのトリガー（プレイヤーが近くにいることを検出）
• 戦利品データ（中に入っているアイテム）
• UI フィードバック（プロンプトラベル、開くアニメーションのトリガー）
• 状態（開いているか、閉じているか）

ステップ 3 — ノード型の割り当て

Chest (StaticBody2D)
├── Sprite2D                  # closed/open frame, or swap texture on open
├── AnimationPlayer           # open animation
├── CollisionShape2D          # physical body shape (blocks player)
├── InteractionArea (Area2D)  # detect when player is close enough
│   └── CollisionShape2D      # slightly larger than body shape
├── PromptLabel (Label3D or Label) # "Press F to open"
└── LootTable (Node)          # holds @export var items: Array[ItemData]

ステップ 4 — シグナルマップ

シグナル	発信元	接続先	用途
body_entered(body)	InteractionArea	Chest._on_area_body_entered	プレイヤーが範囲内に入ったときにプロンプトを表示します
body_exited(body)	InteractionArea	Chest._on_area_body_exited	プレイヤーが範囲外に出たときにプロンプトを非表示にします
opened(loot: Array[ItemData])	Chest	InventorySystem または EventBus	インベントリを所有する側に戦利品を渡します
animation_finished(name)	AnimationPlayer	Chest._on_animation_finished	開くアニメーションの完了後にチェストをロックします

ステップ 5 — 再利用候補

LootTable は樽、敵、ショップのクレートで再利用される可能性が高いため、独立した .tscn コンポーネントとして切り出します。

作成される GDScript と C# の Chest のスケッチ、およびこの設計の文書化に使う 4 部構成の設計項目（シーンツリー、ノードの責務、シグナルマップ、データフロー）については、references/example-chest.md を参照してください。

---

3. ノード型と次元の選択

ここでは 2 つの項目を調べますが、どちらも単純な知識の確認なので、答えがすでに明らかな場合は読み込む必要はありません。

• どの要件にどのノードを使うか？ CharacterBody、RigidBody、StaticBody、Area の使い分け、UI とワールド空間のラベル、パーティクル、カメラ、スポーンマーカー。
• 2D、3D、それとも 2.5D か？ それぞれの選択基準、ハイブリッド手法（ビルボード化したスプライト、正射投影 3D、SubViewport UI）、およびパフォーマンスへの影響。

Godot 4.3 以降で間違いやすい点が 2 つあるので、先に説明しておきます。タイルベースのレベルでは TileMapLayer を使います（ノードごとに 1 レイヤーです。TileMap は非推奨です）。また、ブレンドツリーを使った移動アニメーションには、AnimationPlayer 単体ではなく、AnimationPlayer と組み合わせた AnimationTree が必要です。

ニーズ別のノード一覧、2D／3D の選択基準、2.5D のハイブリッド手法の全容については、references/node-selection.md を参照してください。

---

4. 作成前に確認すること

最初のノードを作成する前に、このチェックリストを確認してください。

• このシステムに必要なデータは何ですか？ — 位置、体力、アイテム数、フラグなど、状態を表す要素をすべて列挙します
• 各データの所有者は誰ですか？ — 値ごとに権威のある所有者を 1 つ割り当て、状態の重複を避けます
• どのように通信しますか？ — ツリーを上るシグナル、下るメソッド呼び出し、システム間イベントには EventBus を使います
• 再利用できますか？ — できる場合は、明確な @export インターフェースを備えた独立した .tscn シーンにします
• 永続化が必要ですか？ — シーンの切り替えやゲームの再起動後もデータを保持する必要がある場合は、早い段階でセーブシステムを計画します
• シーンツリーはどうなりますか？ — エディターに触れる前に、少なくとも 2 階層分をスケッチします
• どのシグナルを発信しますか？ — すべてのシグナル名、引数、接続先を列挙します
• どのような障害が起こり得ますか？ — 必須ノードが見つからない場合や、シグナルが 2 回発火した場合に何が起きるか確認します
• 最小限の実用バージョンは何ですか？ — まずそれを作り、複雑さは必要になってから追加します

---

5. 一般的なアーキテクチャの判断

必要なもの	検討するもの	理由
どこからでもアクセスできるグローバル状態	Autoload（シングルトン）	プロジェクト設定に登録され、名前付きのグローバルとして利用できます
複数のシーン間で共有するデータ	Resource（.tres / .res）	アセットとして保存され、@export に対応し、シーンを再読み込みしても保持されます
エンティティの種類をまたいで再利用できる振る舞い	コンポーネントシーン	子としてインスタンス化でき、各エンティティはそのシーンを含めることで利用できます
多くの状態を持つ複雑なエンティティの振る舞い	ステートマシン	各状態の開始と終了が明示され、if 文の肥大化を防ぎます
親を共有しないシステム間のイベント	EventBus Autoload	送信側と受信側を疎結合にし、任意のノードが接続できます
セッションをまたいで保持する必要があるデータ	JSON またはバイナリを使ったセーブシステム	Resource または Dictionary をシリアライズし、_ready で読み込みます
設定可能なゲームデータ（ステータス、アイテム、レベル）	@export フィールドを持つ Resource	インスペクターで値を編集でき、コードを変更する必要がありません
実行時にシーンを生成すること	PackedScene + instantiate()	@export var scene: PackedScene を保存し、scene.instantiate() を呼び出します
遅延や一定間隔でコードを実行すること	Timer ノード	_process のフレームカウンターよりもすっきりしており、ワンショットとループに対応しています
段階的な遷移（フェード、lerp、トゥイーン）	Tween	create_tween() が組み込みで用意されており、Godot 4 では追加のノードは不要です

---

6. 設計の出力形式

設計はルートスクリプトの先頭にあるコメントブロック、またはシーンの隣にある DESIGN.md ファイルに記録します。完全な設計エントリーには、シーンツリーの ASCII 図、ノードの責務を示す表、シグナルマップ（シグナル → 送信元 → 受信側 → ペイロード）、そしてトリガーとなるイベントがツリーを通じてどのように伝播するかを示すデータフローの 4 つが含まれます。

Chest インタラクティブ要素を中心に作成した、4 つの要素がすべてそろった設計エントリーについては、references/example-chest.md を参照してください。

---

設計チェックリスト

• エディターを開く前に、少なくとも 2 階層のシーンツリーをスケッチする
• すべてのノードに、名前の付いた単一の責務を割り当てる
• すべてのシグナルについて、名前、送信元、受信側、ペイロード型を記載する
• データの所有者を割り当てる — 値を 2 か所に保存しない
• 再利用候補を個別の .tscn ファイルに切り出す
• 通信パターンを選択する：上方向はシグナル、下方向は呼び出し、横方向は EventBus
• データ構造を構築する前に、永続化要件を特定する
• グローバル状態、共有データ、イベントについて、アーキテクチャ判断の表を参照する

---

エージェントへの指示の追加

実装の準備（ステップ 4）を行う際、このプロジェクトでエージェントへの指示に使用しているファイルに、以下のセクションを追加してください。CLAUDE.md、CLAUDE.local.md、.claude/CLAUDE.md、AGENTS.md、GEMINI.md、.github/copilot-instructions.md、および .claude/rules/ と .cursor/rules/ ディレクトリのすべてを確認し、既存の ## GodotPrompter 見出しがどこかにあれば、追加をスキップしてください。

以前の拒否も回答として扱います。SessionStart フックは、拒否があった場合、このプロジェクトの ~/.godot-prompter/state/<hash>.json に "section_offer": "declined" と記録します（ファイルとハッシュの計算方法については godot-prompter:godot-mentor に記載されています）。このキーが設定されている場合は、再度尋ねないでください。ユーザーがここで拒否した場合は、既存のキーを維持したうえで、そのファイルに拒否を記録してください。

2 つ目のファイルではなく、プロジェクトがすでに管理しているファイルに記述してください。

• CLAUDE.md がある場合 → そこに追加してください。
• AGENTS.md または GEMINI.md のみがある場合 → リポジトリをエージェントに依存しない状態に保つため、そこに追加してください。Claude Code が読み込むのは CLAUDE.md のみです。ユーザーがそこにも読み込ませたい場合は、@AGENTS.md のみを記述した 1 行の CLAUDE.md を提案してください。勝手に作成しないでください。
• 何もない場合 → プロジェクト概要の見出しとこのセクションを含む CLAUDE.md を作成してください。

GodotPrompter

このプロジェクトは Godot プロジェクトで、GodotPrompter のスキルを利用できます。ゲームシステムを実装する前に、対応する godot-prompter:* スキルがないか必ず確認し、呼び出してください。これは、このリポジトリで作業するすべてのエージェント、サブエージェント、セッションに適用されます。

主なスキル：player-controller、state-machine、event-bus、scene-organization、component-system、resource-pattern、godot-ui、hud-system、ai-navigation、camera-system、audio-system、save-load、inventory-system、godot-testing。

すべてのスキルの一覧を確認するには、godot-prompter:using-godot-prompter を呼び出してください。