godot

Godot の作法

Godot 開発者がエディターで構築する方法、つまりシーンファーストで進めます。目に見えるものはすべてシーン内のノードであり、再利用するものはそれぞれ独立したシーンで、イベントはシグナルを介して伝わり、動きは移動するノード自身が担います。まずはネイティブのプリミティブ、つまりエンジンに標準搭載されている機能を使い、プリミティブで対応できないものだけコードを書きます。

アドバイスを信頼する前に、バージョンを確認してください。オンラインの Godot 資料の多くは Godot 3 向けです。参照先はGodot 4 のベストプラクティスです。project.godot でプロジェクトの固定バージョンを確認し、そのバージョンのドキュメントを使用してください。

手順

1. シーンツリーをスケッチします。 目に見えるもののコードを書く前に、そのノードツリーを書き出します。どのノードを使うか、どれを独自の .tscn にするか、各スクリプトがどの役割を担うか、どのシグナルが上へ伝わりどの呼び出しが下へ向かうか、どの Resources にデータを格納するかを明確にします。仕様書やモックのすべての要素がスケッチ内のノードに対応したら完了です。設計時には、このスケッチがチケットの Godot structure セクションにあたります。テンプレートは references/ticket-section.md を参照してください。
2. 下の表から各プリミティブを選びます。行に参照先が示されている場合は、その部分を構築する前に参照先を読んでください。
3. シーンで構築します。 ノードツリーは .tscn ファイルで作成し、スクリプトでシーンをインスタンス化して状態を設定します。スタイル、フォント、色はプロジェクトの Theme に設定します。
4. 目で見て検証します。 scripts/smell_check.py をゲームコードに対して実行し（.gd と .tscn を読み込みます）、すべての指摘を解消します。ネイティブのプリミティブに切り替えるか、意図的な例外として該当行またはその上の行に # godot-ok: <reason>（.tscn では ; godot-ok: <reason>）を付けてください。検証に組み込み、終了コードが 0 以外ならビルドが失敗するようにします。次に、あらゆる状態のフレームと、あらゆる遷移のモーションクリップ（--write-movie out.png --fixed-fps 30 --quit-after N）をキャプチャし、フレームを開いてそれぞれを仕様書またはモックと比較します。作業を報告する場所には、それらを添付してください。指摘があるとビルドが失敗し、チェックがすべて通り、あらゆる状態と遷移のフレームを確認して一致していると判断できたら完了です。ゲームが「起動する」または「動作する」という報告は検証ではありません。実際に確認したフレームこそが検証です。

プリミティブ

用途	標準のプリミティブ	問題の兆候
ゲームオブジェクト（フィールド、ユニット、ピックアップ、カード）	独自のシーンをインスタンス化し、型付きメソッドを通じて状態を設定する	1 つの _draw() ですべてのオブジェクトを描画する
ワールドオブジェクトのクリックまたはホバー	Area2D + CollisionShape2D、input_pickable、mouse_entered / input_event	サイズを直接指定した Rect2(...).has_point(mouse)
テキスト	Label / RichTextLabel を使い、テーマでスタイルを設定する	draw_string、ThemeDB.fallback_font
パネル、バッジ、ボタンの外観	Theme 内の StyleBox、またはテーマのタイプバリエーション	スクリプト内の StyleBoxFlat.new()
静的な UI レイアウト	.tscn 内のコンテナとアンカー	_ready で Label.new() / add_child を使って UI を構築する
コンテナ上のオーバーレイ（バッジ、枠線、ピップ）	コンテナとオーバーレイを兄弟として保持する、シンプルな Control ルート	コンテナ内でオフセットを指定して子を配置し、コンテナによって子が引き伸ばされて全体を埋める
カードやパネル上のアート	テーマの StyleBoxTexture、フレームの NinePatchRect、画像の TextureRect — references/art.md	UI ツリー内の Sprite2D
ワールド内のアート	Sprite2D、AnimatedSprite2D、TileMapLayer — references/art.md	完成したアートの代わりに使われる Polygon2D の仮置き
子要素がアニメーションするレイアウト（カードの手札、ラジアルメニュー）	目標のトランスフォームを計算するカスタム Control。子要素はその位置へ滑らかに移動する — references/motion.md	BoxContainer 内でアニメーションする子要素
ゲームイベントへの反応	モデルからシグナルを送り、ビューで接続する	毎フレームポーリングして配列を差分比較し、変更内容を推測する
変化するリスト（手札、インベントリ）	アイテムごとに永続的なビューを 1 つ保持し、アイテムをキーにする。追加・削除は個別に行う	変更のたびにすべての子要素を解放し、インスタンス化し直す
単発のモーション（ポップ、シェイク、飛行）	移動するノード上の create_tween() から Tween を作成する	更新呼び出しを通じてカウントダウン用の浮動小数点値を渡す
作り込まれた複数トラックのモーション	AnimationPlayer	手動で順序付けたタイマー
移動するワールドオブジェクト	_physics_process 内で移動し、物理補間を有効にする	補間対象ノードのトランスフォームを _process 内で設定する
UI のイージングとビューの更新	_process	_physics_process 内でビジュアル処理を行う
ワールドのフレーミング	Camera2D	ビューポートのサイズを直接指定してワールドをレイアウトする
ツールチップ	シーンを返す _make_custom_tooltip()	ゲームコンテンツにデフォルトの tooltip_text を使う
調整可能なデータ、カードやアイテムの定義	.tres として保存する Resource のサブクラス	スクリプト内の定数辞書
オブジェクトごとの状態	型付きの var	set_meta / get_meta
ノード参照	@onready var x: Type = %Name。ほかのスクリプトから参照するスクリプトには class_name を付ける	型なしの @onready var x = $Path

カスタム _draw() が標準のプリミティブとなるのは、次の 3 つの場合に限られます。多数のシンプルな図形の繰り返し（グリッド、ボード）、どのノードでも提供されない図形（軌跡、弧、プロシージャルなポリゴン）、カスタムコントロールのテキスト以外の描画です。それ以外はすべてノードを使います。

通信

呼び出しは下へ、シグナルは上へ。親は子のメソッドを呼び出し、子はシグナルを発信して、親を直接参照することはありません。シーンは、それを所有するシーンからセッターまたは bind() を通じて必要なものを受け取り、単独で開いたときも動作します。

参考資料

• references/ticket-section.md — Godot のチケットすべてに含まれる Godot の構成セクション。
• references/motion.md — 目標位置へのイージングを使うレイアウト、トゥイーン、ドラッグ、スナップバック。
• references/ui.md — テーマ、コンテナ、UI とワールド間の入力ルーティング。
• references/art.md — UI とワールドでのアートの配置場所、ピクセルアートの設定。