個人のGodot使用テクニックと習慣
前往评论 ↓きっかけ
以前 役立つGodotプラグイン についてまとめましたが、今回はもう少し基礎的な話、つまりGodotでの開発における習慣について書いてみたいと思います。
今日、GodotHub でGodot開発経験の共有という投稿を見かけたのですが、そこに書かれていることの多くは今でも私が使っているものでした。ただ、私とはやり方が違う部分もあります。
サイト管理者もゲーム開発から始めているわけですし、自分のブログにゲーム開発の記事が少なすぎるのもなんだか気まずいですしね(笑)。
というわけで、ここでは管理者自身のGodotの使い方の習慣について書いていこうと思います。
%を唯一の名前としてアクセスする

Godotのスクリプト内でノードを参照する際、CtrlやAltを押しながらノードをドラッグして @onready や @export を生成するのは確かに便利ですが……
@onready var start_button: Button = $Panel/MarginContainer/VBoxContainer/StartButton後からUIの調整でコンテナの階層を一段増やしたりすると、このパスも書き直さなければならなくなります。
Godotのシーン一意名はまさにこういう場面で使えます。シーンツリーでノードを右クリックし、「一意名としてアクセス」を有効にすると、ノードの横に % のマークが表示され、スクリプト内でも次のように簡潔に書けるようになります。
@onready var start_button: Button = %StartButton同じ所属シーン内で名前が変わっていなければ、途中のノード階層を変更してもこの参照を書き直す必要はありません。また、シーンツリー上のマークを見るだけで、そのノードがスクリプトから使われているかもしれないということが一目で分かります。
ここでの「一意」とはシーン内での一意を意味し、ノードの owner に依存します。例えば、プレイヤーシーンの中に武器シーンがインスタンス化されている場合、プレイヤーのスクリプトから %Blade を使って武器内部のブレードを直接見つけることはできません。そのため、こうした参照はそれぞれのシーン内部に留めるようにしています。
リソース参照、プリロード、そして定数
プリロードは基本的に、設定済みのステートマシンツリーなど、同じシーン内で完結するものに対して使います。
一方、エクスポートによる参照は主にシーンをまたぐ参照に使います。
また、定数リソースは、頻繁に変更されることがなく、かつ参照しにくいもの(例えばセーブシステム用のデータクラスなど)によく使われます。これはグローバルスクリプトが必要とする抽象リソースであり、ロジックの実装にも確実に必要になるため、変更されないものです。
例えば、ポータルに目標シーンを選択させたい場合は、プロパティをエクスポートするとよいでしょう。なぜなら、このポータルシーンは他のシーンで再利用されつつ、それぞれ異なるシーンへ転送することになるからです。
extends Area2D
@export var destination_scene: PackedSceneそしてインスペクターで対応するシーンをドラッグ&ドロップすれば、同じポータルシーンを異なるステージに配置してもそれぞれ目的地を設定でき、変更も直感的に行えます。
スクリプト内でどうしてもリソースを固定して読み込む必要がある場合は、Godotのファイルシステムパネルから右クリックでUIDをコピーし、実際にコピーされた uid://... を preload() の文字列引数に貼り付ければ、リソースの移動後に元のファイルパスに依存し続ける必要がなくなります。
UIDが管理するのはリソースのアイデンティティであり、%StartButton が管理するのはシーン内のノード参照です。この2つは全く異なる問題を解決するためのものです。
テーマ

あらかじめ Theme リソースを作成し、ボタン、ラベル、パネルの共通スタイルをそこにまとめてから、それをインターフェースのルート Control に割り当てる方法をお勧めします。そうすれば、下位のコントロールもそのテーマを継承でき、後からフォントを変更したりボタンのスタイルを調整したりしたい時も、一箇所でまとめて変更できるようになります。
同じ種類のボタンであっても、通常ボタン、確認ボタン、削除ボタンといったように用途が分かれる場合があります。そういう時はテーマの型バリアントが使えます。
- テーマエディターの型リストの横にあるプラスボタンをクリックし、
DangerButtonなどの型を作成する - ツールアイコンに対応するタブに切り替え、その基本型を
Buttonに設定する - このバリアントの色やスタイルを修正し、対象のボタンの
Theme Type VariationにDangerButtonと入力する
こうすることで、共通のフォントや余白は Button に従いつつ、削除ボタンは違いのある部分だけを個別に管理できるようになります。もしドロップダウンリストにバリアントが表示されない場合は、直接名前を入力することも可能です。
個別のコントロールに特別な要件がある場合は部分的な上書きももちろん可能ですが、繰り返し登場するスタイルをテーマにまとめておけば、後からの修正がぐっと楽になります。
型ヒントとドキュメントコメントは、ついでに書いておく
GDScriptでは型を強制されませんが、変数や関数の引数、戻り値の型を書いておくと全体が非常に分かりやすくなり、エディターによる正確な補完やエラー検出も受けられるようになります。
extends Node
## 当前关卡获得的分数var score: int = 0
## 增加分数,amount 为本次获得的分数func add_score(amount: int) -> void: score += amountここでは2つのものが同時に使われています。int と -> void は型ヒントで、メンバーの頭にある ## はドキュメントコメントです。
var score := 0 のように型を明確に推論できる書き方も便利で、型を書くために毎行長々とする必要はありません。ただ、関数の引数、戻り値、そして重要なノード参照については、明示的に書くように心がけています。
関数を自動補完する際にいつも型が表示されない場合は、エディター設定で Add Type Hints を検索してみてください。該当箇所は Text Editor → Completion → Add Type Hints にあります。詳しい使い方は静的型のドキュメントをご覧ください。
コメントについてですが、最も書く価値があるのはパラメータの意味、単位、そして呼び出し条件だと思っています。例えば、時間パラメータの単位が秒なのかミリ秒なのかは、しばらく経つと自分でも忘れてしまいます。そういったことを明確に書いておくほうが、コードの1行1行に中国語の翻訳コメントをつけるよりもはるかに役に立ちます。
## に書いた内容はGodotの内蔵ヘルプからも認識され、エクスポートプロパティに記述すればインスペクターのヒントとしても表示されるため、プラグインを作ったり他人に使ってもらうコンポーネントを作ったりする際にはかなり便利です。ドキュメントコメントの完全な書き方はこちら。
長い条件の改行は、括弧を優先する
いくつかの条件が1行に詰まっていると、すぐに画面からはみ出してしまいます。特に左右にスクリプトを2つ並べて開いているときはなおさらです。
GDScriptではバックスラッシュを使って行を継続することもできますが、式を括弧で囲む方法のほうがおすすめです。これは公式スタイルガイド)でも推奨されている書き方で、後から条件を追加・削除する際にも手間がかかりません。
func can_interact(in_range: bool, target_visible: bool, dialogue_open: bool) -> bool: return ( in_range and target_visible and not dialogue_open )エディターにある2本の縦線は、行の長さのソフトリファレンスとハードリファレンスです。コードが長すぎないかを警告するためのものであり、これを超えたら実行できないわけではありませんし、リファレンス内に収めるために単純な式をバラバラに分解する必要もありません。
ファイルはシーンや機能ごとに配置し、探しやすさを優先する
チュートリアルなどでは、ファイルを scripts、scenes、assets に分ける方法が紹介されており、非常に直感的ではあります。しかし、プロジェクトがある程度大きくなると、同じプレイヤーのシーン、スクリプト、設定があちこちのディレクトリに散らばってしまい、結局探すのが面倒になります。
私は、一緒に修正することが多いものは同じ場所にまとめるほうが好みです。例えば、以下のような感じです。
res://├── characters/│ └── player/│ ├── player.tscn│ ├── player.gd│ └── player_stats.tres├── ui/│ └── inventory/│ ├── inventory.tscn│ ├── inventory.gd│ └── inventory_slot.tscn├── shared/│ ├── themes/│ └── shaders/└── assets/ ├── fonts/ └── audio/プレイヤー固有のものは player に入れ、インベントリUI固有のものは inventory に入れます。複数の場所で使われるフォントやオーディオ、テーマなどはまとめて配置します。Godotのプロジェクト構成ドキュメントでも、関連するリソースはできるだけシーンの近くに配置することが推奨されています。
今あるディレクトリで問題なく作業できているならそのままで構いません。ディレクトリを整理する最大の意味は、次に修正を行う際の時間短縮に繋がることですから。
子シーンは何が起きたかを伝え、外部のことは親層に任せる
例えばインベントリアイテムのマス目がクリックされたとき、それはアイテムのIDを載せた item_selected シグナルを発火させ、詳細を表示するかアイテムを装備するかはインベントリUI側に判断させます。
もしマス目自身が get_parent() を辿ってメインシーンまで探しに行き、プレイヤーや詳細パネルを直接書き換えようとすると、別の場所でそのマス目を再利用したときに不具合が起きやすくなります。
ここで重要だと思うのは、子シーンが外側の具体的な構造に依存しすぎないようにすることです。シーンをまたぐ接続や調整は、双方の関係性を把握している親層に極力任せるべきです。明確なシグナルを直接繋ぐだけで十分なときは、わざわざグローバルなイベントシステムをもう一層かぶせる必要もありません。
公式のシーン構成ドキュメントには、こういった関係に関する例が数多く掲載されています。
リソースの共有とインスタンス変数を明確に区別する
この点は、マテリアル、テーマ、カスタム Resource などにおいて特に起こりがちです。例えば、複数のキャラクターが同じプロパティリソースを参照している状態で、実行時にその中のHPを変更してしまうと、他のキャラクターのHPまで一緒に変わってしまうことがあります。
Godotはロード済みのリソースを再利用しますが、リソースがシーン内に内蔵されているからといって、シーンをインスタンス化するたびに自動的に独立したコピーが取得されるわけではありません。
特定のリソースをシーンのインスタンスごとに独立させたい場合は、リソースのインスペクターで Local To Scene を設定するか、本当に独立したデータが必要なときにリソースを複製すればよいのです。共通のテクスチャ、フォント、読み取り専用の設定はそのまま共有し続けましょう。
ただし、「同じスクリプトリソースを共有すること」と「スクリプト内のすべての変数を共有すること」は同じではありません。2つのノードが同じスクリプトを使用している場合でも、通常のメンバ変数はそれぞれのスクリプトインスタンスに属します。例えば先ほどの score はそれぞれ個別にスコアを記録しますし、static 変数こそがもう一つの共有セマンティクスとなります。
そのため、複数のオブジェクトが連動して変化してしまうような問題に直面したときは、あちこちコピーのロジックを追加する前に、それらが変更可能な同じリソースを参照していないかを確認するほうが、原因を素早く突き止められます。
細々とした小ネタ
スペースキーでUIが勝手に押されないようにする

一番簡単なのは、入力マップで ui_accept を見つけて、その中から space を削除することです。なぜなら、GodotのUIノードはデフォルトで ui_accept によって操作できるようになっており、space はそのデフォルトのキーになっているからです。それだけのシンプルな話です。
折りたたみにはregionを使い、説明にはコメントを使う
スクリプトが少し長くなってきたら、#region と #endregion を使って関連するコードをグループ化すると、エディターでそのセクションを折りたためるようになります。公式の文法はこちら。
#region Score
var score: int = 0
func add_score(amount: int) -> void: score += amount
#endregionこれら2つのマークの # の後にはスペースが入りません。通常のコメントの書き方とは異なり、# region のように書いてしまうと、単なる通常のコメントになってしまいます。
参考と次のステップ
この記事は、テンセントチャンネルの Godot開発経験の共有およびコメント欄での補足を参考にしています。関連する使い方についての公式ドキュメントは各セクションに記載しました。
役立つプラグインについて見てみたい場合は、役立つGodotプラグイン を続けてご覧ください。