【Godot】@export系のアノテーションを使って、インスペクターの表示を整理しよう

はじめに

Godotのインスペクターにノードやクラスを参照したりできる、@exportなどのアノテーションについてをまとめます。

一応、公式ドキュメントにもまとまっていますが、インスペクターの表示がされていないのでわかりづらいです

使用環境

• Godot: 4.1.1 stable

@exportについて

GDScriptで、他のノードやクラスを参照したいときや、エディタ側でintやstringなどの値を調整するために使います。
(Unityでいう[SerializeField]属性みたいな感じです)

実際の使用例です↓

@export_category("Animations")
@export_group("Spawn")
@export var spawn_duration = 0.5

@export_subgroup("Easing")
@export var spawn_trans = Tween.TRANS_QUAD
@export var spawn_ease = Tween.EASE_IN_OUT

外部ノード・クラスの参照

他にもNodeクラスのget_node()やfind_children()などで動的に参照する方法がありますが、@exportに比べるとちょっと負荷がかかるので、できることなら@exportで参照するのがベストかと思います

(公式ドキュメントのfind_child系のメソッドには、このような注意書きもされています)

注:このメソッドはノードのすべての子孫をたどるので、他のノードへの参照を取得するのに最も遅い方法です。可能な限り、ノード参照を変数にキャッシュすることを検討してください。

一覧

基本

@export

インスペクターの表示

@export var speed: float = 100.0

配列

型指定なしのArray

動的型付け言語なので、型を指定しないと配列にはバラバラの型を格納できちゃいます

@export var array: Array

初期値を設定した配列はこんな感じです

@export var dynamic_array = [1, 2, 3]

int型のみ、などの制限はありません。(下図では後からVector3型の要素を追加しています)

型指定付きのArray

こんな感じで型を指定すると、指定された型の配列ができます

@export var int_array: Array[int]

PackedArray

PackedArrayは、指定の型に特化した配列です。
静的なのでメモリなども最適化されています。
詳細は公式ドキュメントをご覧ください

@export var packed_array = PackedInt32Array()

通常の配列と同様に表示されています

PackedArrayの場合、初期値を設定しても、nullになってしまいます

@export var packed_array = PackedInt32Array([1, 2, 3])

列挙体

定義した列挙体から選択する(enum型)

定義した列挙体をインスペクター上で選択できる

enum EnumTest {
	ONE,
	TWO,
	THREE
}

@export var enum_test: EnumTest

@export_enum

enumを定義せずに、enumのような選択肢をインスペクター上に表示できる

int

@export_enum("ONE:1", "TWO:2", "THREE:3") var enum_test_2: int

print(enum_test_2)    # result: 2

初期値を設定することもできる

@export_enum("ONE:1", "TWO:2", "THREE:3") var enum_test_2: int = 2

(矢印ついてないのがデフォルト)

string

見た目はintと同様
出力結果が、選択した項目の文字列

@export_enum("ONE", "TWO", "THREE") var enum_test_3: String

print(enum_test_3)    # result: TWO

グループ系

@export_category

見出し付きのグループ分けができる

@export_category("Parameters")
@export var hp: int = 100
@export var mp: int = 100

@export_category("Movement Parameters")
@export var speed: float = 100.0

@export_group

開閉できるトグル付きのグループ分けができる

@export_category("Parameters")
@export_group("Base")
@export var hp: int = 100
@export var mp: int = 100

@export_group("Movement")
@export var speed: float = 100.0

@exort_subgroup

グループの中でさらにグループ分けができる

@export_group("Movement")
@export_subgroup("Base")
@export var speed: float = 100.0

@export_subgroup("Jump")
@export var jump_height: float = 100.0
@export var jump_count: int = 2

パス系

@export_file

ファイルを選択して、ファイルパスを参照できる

ファイルを選択すると、選択したファイルのパスが取得できる

@export_file var file

また、拡張子を指定して、指定された拡張子のみを選択対象にすることもできる

例えば、このように*.gdと指定すると、gdscriptファイルのみを選択可能になる

@export_file("*.gd") var script_file

@export_dir

ファイル同様、ディレクトリパスを取得

フォルダ以外のファイルも表示されていますが、選択可能なのはフォルダのみです

@export_global_file / @export_global_dir

プロジェクト外のファイルパスを参照できる
一応参照できますが、ゲーム内で使うことは少ないと思います
基本的にツールモード(エディタ拡張)で使います

Using paths in the global filesystem is also possible, but only in scripts in tool mode.
(グローバル ファイル システム内のパスを使用することも可能ですが、ツール モードのスクリプトでのみ使用できます。)
(公式ドキュメントより抜粋)

ノード、クラス、Resourceなど

ノードの参照

ノードを参照できる

@export var node: Node

また、4.0以前でのノードの参照方法として、NodePathを参照してget_node()する方法がありますが、手間なので普通にNode参照した方がいいです

@export var node_path: NodePath
@onready var node_path_node = get_node(node_path)

クラスの参照

自身が定義したクラスを参照することもできる

referenced_class.py

@icon("res://icon.svg")
class_name ReferencedClass
extends Node

export_test.py

@export var referenced_class: ReferencedClass

(デフォルトのGodot君をアイコンに指定したら、プロパティの高さが広くなった)

アセット(Resource)の参照

テクスチャ、オーディオなどのアセット(Resource)を参照できる

@export_category("Resources")
@export var resource: Resource
@export var gdscript: GDScript
@export var icon: Texture

その他の@export

@export_range

intやfloatなどの範囲を制限した値を取得できる
変数を静的型付けで型を指定することで、見た目と操作が変わる

int

@export_range(0, 100) var range_int: int

float

@export_range(0, 100) var range_float: float

スナップ付き

@export_range()の第三引数に値を指定すると、スナップ(その値ごとに値を増減させること)ができる

以下のようにすると、float型でもint型のような操作方法になる

@export_range(0, 100, 1) var range_float: float

スナップ値を0.1くらいにすると、細かすぎる値にならなくていい感じになる

@export_range(0, 100, .1) var range_float: float

スライダー操作時のみに値の制限をする

第四引数以降に、"or_greater"や"or_less"などを追加すると、スライダーのみの制限をかけられる
値を数値入力によって変更した場合には、制限しない

@export_range(0, 100, 1, "or_greater", "or_less") var range_int: int

@export_multiline

複数行テキストを編集できる

@export_multiline var text

@export_exp_easing

ease()メソッドの結果を確認できる…？
ease()については、下記リンクを参照してください

こんな感じでカーブを取得できる

@export_exp_easing var easing

色の指定

静的型付けでColor型を指定すると、色を選択できるようになる

@export var color: Color

アルファ値を無視

@export_color_no_alphaで、アルファ値が1の色を取得する

@export_color_no_alpha var color_no_alpha:

ビットフラグ

ビットフラグとは、ビット演算でフラグ管理をすることです
int型でフラグの配列を持たせることができる感じです

@export_flags

チェックボックスでフラグ管理できるビットフラグです

@export_flags("A", "B", "C") var flags: int

その他のビットフラグ

Node2DのCanvasItemノードのレイヤーとかもビットフラグで管理されています

これを自前で用意したい場合は、@export_flags_2d_renderなどのアノテーションを使います

@export_flags_2d_render var layers_2d_render

他にもこんな感じのがあります

@export_flags_2d_physics var layers_2d_physics
@export_flags_2d_render var layers_2d_render
@export_flags_2d_navigation var layers_2d_navigation
@export_flags_3d_physics var layers_3d_physics
@export_flags_3d_render var layers_3d_render
@export_flags_3d_navigation var layers_3d_navigation

その他

ツールチップ(プロパティの説明)を付与

プロパティにマウスオーバーすると表示される説明ですが、@export変数に対してドキュメントコメントを付与することで追加できます

## This is a test variable
@export var test: int = 0

ただ、バグなのか不明ですが、@export_categoryなどの直下にある変数に対してドキュメントコメントを付与しても、ツールチップが表示されません。

@export_category("Parameters")
## This is a test variable
@export var test: int = 0

さいごに

基本的に@exportだけ使ってれば問題なさそうですね
グループ分けを使うと、もっと分かりやすくなりそうです。

Unityの属性のように、自作でカスタマイズしたものも作れるのかも調べたいです！