godot-fundamentals

Godot の基本

スタータープロジェクトのレイアウトを押し付けず、プロジェクトで既に使われている Godot の規約に従って実装します。

対象範囲

次の作業でこのスキルを使用します。

• Node、Node2D、Node3D、Control の派生ノードを選択し、配置する。
• 再利用可能なシーンを作成し、PackedScene リソースをインスタンス化する。
• 組み込みまたはカスタムの Resource データを定義し、割り当てる。
• シーンノードに型付き GDScript を追加し、ライフサイクルコールバックを適切に使用する。
• 名前付き入力アクションを設定し、入力コールバックを選択する。
• シーン、ファイルシステム、インスペクター、出力、デバッガー、リモートシーンツリーを操作する。
• プロジェクト、インポート、ノードパス、トランスフォーム、シーン実行に関する基本的な問題を診断する。

SOLID に基づくリファクタリング、イベントアーキテクチャ、コマンド、オブジェクトプールの導入にはこのスキルを使用しないでください。プログラミングパターンのスキルを使用します。グローバル状態の所有権、マネージャーのライフタイム、シーン遷移、セーブの境界を決める用途には使用しないでください。ゲームアーキテクチャのスキルを使用します。ジャンル固有のゲームプレイや高度なレンダリングは対象外です。

編集前の確認

1. project.godot の場所を特定します。現在のディレクトリがプロジェクトルートだと決めつけないでください。
2. config/features と既存のツールを確認し、Godot 4.x の正確なバージョンを特定します。そのバージョンより後に導入された API は避けてください。
3. プロジェクト設定を変更する前に、[application]、[autoload]、[input]、[display]、関連する [rendering] の設定を確認します。
4. 周辺の .gd、.tscn、.tres、.res ファイルを確認します。フォルダー構成、命名、インデント、静的型付けのレベル、ノードの命名、シグナル接続のスタイルを合わせます。
5. 対象となるシーンツリーを把握します。ルートの型、親子の所有関係、インスタンス化されたサブシーン、編集可能な子ノード、エクスポートされた参照、一意な名前のノード、ローカルとグローバルのトランスフォームを確認します。
6. プロジェクトで通常使用する実行、テスト、リント、フォーマットのコマンドを確認します。可能であれば、変更前の基準となる実行結果を取得します。
7. 生成された .godot/ のインポート／キャッシュ内容は編集しないでください。代わりにソースアセットまたはインポート設定を変更します。

project.godot がない場合は、Godot 固有のファイルを作成する前に、プロジェクトを初期化するか確認してください。

実装ワークフロー

1. 動作を、観察可能な一文で表します。
2. 要件に合う動作を持つ、最も限定的な組み込みノードを選びます。
3. 対象がノード、再利用可能なシーン、リソース内のデータのどれに当たるかを決めます。
4. それに依存するコードを書く前に、シーン階層を構築します。
5. デザイナーが管理する値は型付きの @export プロパティとして公開し、安定した子ノードへの参照は型付きの @onready プロパティとして保持します。
6. 物理キー定数ではなく、名前付きの入力マップアクションを使用します。
7. 動作を実現する、最小限の型付きスクリプトを実装します。
8. 編集したシーンを単独でテストし、その後、プロジェクトのエントリーシーンを実行します。

基本的な判断基準

ノードとシーン

• まず動作を基準に選択します。テクスチャが表示されるからといって、ルートを自動的に Sprite2D にする必要はありません。また、クリック可能なオブジェクトだからといって、必ずしも物理ボディが必要なわけではありません。
• トランスフォーム可能な 2D グループ化ルートには Node2D、3D には Node3D、レイアウト主導の UI には Control、シーン内で空間を持たない調整には通常の Node を使用します。
• ノードの枝が独立したアイデンティティを持つ場合、再利用される場合、または単独でのテストに適している場合は、シーンにします。
• ランタイムの子ノードの追加と削除は、最も近いシーンの所有者に任せます。通常のゲームプレイノードを SceneTree.root に直接追加するのは避けてください。
• 親に依存するワールド空間のトランスフォームを割り当てる前に、インスタンスをツリーに追加します。
• 通常のシーンツリーコールバックでは、queue_free() を優先します。所有者が解放された後は、保持しているノード参照はすべて無効として扱ってください。

extends Node2D

@export var pickup_scene: PackedScene
@onready var pickups: Node2D = %Pickups

func spawn_pickup(at: Vector2) -> void:
	if pickup_scene == null:
		push_error("Assign Pickup Scene before spawning a pickup.")
		return
	var pickup := pickup_scene.instantiate() as Node2D
	if pickup == null:
		push_error("The configured pickup scene must have a Node2D root.")
		return
	pickups.add_child(pickup)
	pickup.global_position = at

リソース

• インスペクターでの編集、再利用、またはライブシーンノードから独立したシリアライズが有用なデータには、リソースを使用します。
• 複数のシーンで同じ定義を共有する場合は、外部 .tres を使用します。データが1つのシーンまたはリソースだけに属する場合は、組み込みサブリソースを使用します。
• リソースは共有参照として扱います。共有定義リソースにインスタンスごとに変更される状態を格納しないでください。
• スクリプトの解析時に判明している固定の依存関係には preload() を使用します。実行時にパスが選択される場合に限り、load() またはスレッド読み込みを使用します。
• 後で永続化される可能性があるデータには、安定した識別子を使用します。表示名やファイルパスは、適切な識別子ではありません。

入力とコールバック

• 物理演算に関わる移動では、_physics_process() 内で押下中のアクションをポーリングします。
• UI に最初にイベントを処理する機会を与える場合は、離散的なゲームプレイイベントを _unhandled_input() で処理します。
• 物理演算に依存しない、フレーム駆動の表示処理には _process() を使用します。
• 手動で設定するレートには delta を掛けます。CharacterBody2D.velocity はすでに秒あたりの値なので、move_and_slide() の前に delta を掛けないでください。
• 意図的に使用しないコールバック引数には、接頭辞として _ を付けます。

extends CharacterBody2D

@export_range(0.0, 1200.0, 1.0) var speed: float = 240.0

func _physics_process(_delta: float) -> void:
	var direction := Input.get_vector(
		&"move_left", &"move_right", &"move_up", &"move_down"
	)
	velocity = direction * speed
	move_and_slide()

ノード参照

• デザイナーが依存関係を設定する場合は、エクスポートされた型付き参照を優先します。
• %StableName は、ノードがシーン固有として明示的に指定されている場合にのみ使用します。
• 同じシーンが所有する、非公開で安定した子ノードには、短い $Child/Path を使用します。
• フレームごとのコールバックでシーンツリー全体を繰り返し検索しないでください。
• 再利用可能なシーンの境界をまたぐ、壊れやすい相対パスを作成しないでください。

検証

プロジェクトですでに設定されている実行ファイルとコマンドを使用します。プロジェクトにコマンドがない場合は、検出された Godot 実行ファイルを使い、次のようなコマンドで基本的なインポートと解析の確認を実行できます。

godot --headless --editor --path <project-root> --quit

次に、関連するすべての動作を検証します。

• エディターが、パーサー、リソース不足、または無効なノードに関する警告なしでインポートを完了すること。
• 影響を受けるシーンが F6 相当の動作で実行され、意図せずメインシーンに依存していないこと。
• プロジェクト全体が、設定されたメインシーンから実行されること。
• 新しい Input Map アクションがすべて存在し、意図した各デバイスのバインドが動作すること。
• インスタンス化と再親子化の後も、ローカル座標変換とグローバル座標変換が正しく保たれること。
• エクスポートされたリソースとノード参照が、すべてのシーンインスタンスに割り当てられていること。
• Output パネルと Debugger パネルに、新たなエラーが表示されないこと。
• Remote シーンツリーで、インスタンスが意図した所有者の下に表示され、想定どおりのタイミングでツリーから削除されること。
• 既存の自動テストが引き続き成功すること。

実行した確認項目と、自動化できなかったエディターのみの確認項目を正確に報告してください。

失敗の原因

• メインプロジェクトからのみシーンが動作する： 再利用可能なシーンが、所有権の境界を越えて参照しています。依存関係をエクスポートするか、明示的なセットアップメソッドを用意してください。
• Node not found： パス、一意名のフラグ、またはシーン階層が変更されています。実際の .tscn を確認し、代替パスを推測しないでください。
• アクションが反応しない： Input Map にアクションがない、アクション名の綴りが間違っている、UI がイベントを消費した、またはノードの処理モードが無効か一時停止中です。
• インスタンス同士が影響し合う： 共有リソースに変更可能な状態が保存されています。実行時の状態をインスタンスに移すか、意図的にリソースを複製してください。
• 生成後の位置が正しくない： ローカル座標とグローバル座標が混在しているか、親子関係を設定する前にトランスフォームが設定されています。
• 子ノードへのアクセスが null になる： _ready() より前にアクセスした、子ノードが任意になっている、またはスクリプトが異なる構造のシーンにアタッチされています。
• フレームレートによって物理挙動が異なる： 移動に _process() を使用したか、delta を一貫せず適用しています。
• エディターに古いアセットが表示される： ソースのインポート設定を迂回したか、生成されたキャッシュファイルを編集しました。

参考資料

• ノード、シーン、リソース
• 型付き GDScript と入力
• エディターとデバッグのワークフロー