GDScriptプロパティのエクスポート

In Godot, class members can be exported. This means their value gets saved along with the resource (such as the scene) they're attached to, and get transferred over when using RPCs. They will also be available for editing in the property editor. Exporting is done by using the @export annotation.

@export var number: int = 5

この例では 5 の値が保存され、プロパティエディタにも表示されます。

エクスポートされた変数は定数式に初期化されるか、型が指定されている必要があります。ただしエクスポートアノテーションの一部には特定の型があり、変数を型指定する必要はありません (以下の例セクションを参照)。

メンバー変数をエクスポートする基本的な利点の1つは、エディタで表示および編集できることです。このようにして、アーティストやゲームデザイナーは後でプログラムの実行方法に影響する値を変更できます。このために特別なエクスポート構文が用意されています。

注釈

プロパティのエクスポートは C#のような別の言語でも実行できます。構文の違いは言語に依存します。 C# エクスポートの詳細については、C# exported properties を参照してください。

基本的な使い方

エクスポートされた値が定数または定数式を割り当てている場合、型が推論されてエディタで使用されます。

@export var number = 5

デフォルト値がない場合は、変数に型を付ける必要があります。

@export var number: int

リソースとノードもエクスポートできます。

@export var resource: Resource
@export var node: Node

Grouping exports

@export_group アノテーションを使用して、インスペクタ内でエクスポートされたプロパティをグループ化することができます。このアノテーションの後にエクスポートされたすべてのプロパティがグループに追加されます。別の新しいグループを開始するか @export_group("") を使用するとグループを終了します。

@export_group("My Properties")
@export var number = 3

アノテーションの2番目の引数は、指定されたプレフィックスを持つプロパティをグループ化するためにのみ使用できます。

グループをネストすることはできません。グループ内にサブグループを作成するには、@export_subgroup を使用してください。

@export_subgroup("Extra Properties")
@export var string = ""
@export var flag = false

メインカテゴリの名前を変更したり、@export_category 注釈を使用してプロパティリストに追加のカテゴリを作成したりすることもできます。

@export_category("Main Category")
@export var number = 3
@export var string = ""

@export_category("Extra Category")
@export var flag = false

注釈

プロパティのリストはクラスの継承をもとに並んでいますが、新しいカテゴリはその法則を壊します。特に公開用のプロジェクトを作成する場合は慎重に使用してください。

パス文字列

String as a path to a file. See @export_file.

@export_file var f

String as a path to a directory. See @export_dir.

@export_dir var f

String as a path to a file, custom filter provided as hint. See again @export_file.

@export_file("*.txt") var f

グローバルファイルシステム内のパスを使用することも可能ですが、ツールモードのスクリプトでのみ使用できます。

String as a path to a PNG file in the global filesystem. See @export_global_file.

@export_global_file("*.png") var tool_image

String as a path to a directory in the global filesystem. See @export_global_dir.

@export_global_dir var tool_dir

The multiline annotation tells the editor to show a large input field for editing over multiple lines. See @export_multiline.

@export_multiline var text

入力範囲の制限

See @export_range for all of the following.

0 ～ 20 の整数値を指定可能。

@export_range(0, 20) var i

-10 ～ 20 の整数値を指定可能。

@export_range(-10, 20) var j

-10 から 20 までの浮動小数点を指定でき、値は 0.2 の倍数にスナップします。

@export_range(-10, 20, 0.2) var k: float

The limits can be made to affect only the slider if you add the hints "or_less" and/or "or_greater". If either these hints are used, it will be possible for the user to enter any value or drag the value with the mouse when not using the slider, even if outside the specified range.

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

The "exp" hint can be used to make a value have an exponential slider instead of a linear slider. This means that when dragging the slider towards the right, changes will become progressively faster when dragging the mouse. This is useful to make editing values that can be either very small or very large easier, at the cost of being less intuitive.

@export_range(0, 100000, 0.01, "exp") var exponential: float

For values that are meant to represent an easing factor, use イージングヒント付き実数 instead.

The "hide_slider" hint can be used to hide the horizontal bar that appears below float properties, or the up/down arrows that appear besides int properties:

@export_range(0, 1000, 0.01, "hide_slider") var no_slider: float

Adding suffixes and handling degrees/radians

A suffix can also be defined to make the value more self-explanatory in the inspector. For example, to define a value that is meant to be configured as "meters" (m) by the user:

@export_range(0, 100, 1, "suffix:m") var m: int

For angles that are stored in radians but displayed as degrees to the user, use the "radians_as_degrees" hint:

@export_range(0, 360, 0.1, "radians_as_degrees") var angle: float

This performs automatic conversion when the value is displayed or modified in the inspector and also displays a degree (°) suffix. This approach is used by Godot's own rotation properties throughout the editor.

If the angle is stored in degrees instead, use the "degrees" hint to display the degree symbol while disabling the automatic degrees-to-radians conversion when the value is modified from the inspector.

イージングヒント付き実数

Display a visual representation of the ease() function when editing. See @export_exp_easing.

@export_exp_easing var transition_speed

色

RGBAの値として指定される通常の色。

@export var col: Color

Color given as red-green-blue value (alpha will always be 1). See @export_color_no_alpha.

@export_color_no_alpha var col: Color

ノード

Godot 4.0以降は、NodePathを使用せずにノードをスクリプト内のプロパティとして直接エクスポートできるようになりました。

# Allows any node.
@export var node: Node

# Allows any node that inherits from BaseButton.
# Custom classes declared with `class_name` can also be used.
@export var some_button: BaseButton

必要に応じてGodot 3.x のようにNodePathをエクスポートすることも可能です。

@export var node_path: NodePath
var node = get_node(node_path)

NodePathのノードのタイプを制限したい場合は @export_node_path アノテーションを使用できます。

@export_node_path("Button", "TouchScreenButton") var some_button

リソース

@export var resource: Resource

リソースファイルはファイルシステムドックから、インスペクタのプロパティスロットにドラッグ＆ドロップできます。

インスペクタのドロップダウンを開くと、作成可能クラスの非常に長いリストが表示される場合があります。作成できるリソースを限定するには、次のようにリソースの型を指定します。

@export var resource: AnimationNode

The drop-down menu will be limited to AnimationNode and all its derived classes.

スクリプトがエディタで実行されていない場合でも、エクスポートされたプロパティはまだ編集可能です。これは script in "tool" mode と共に使うことが出来ます。

ビットフラグのエクスポート

See @export_flags.

ビットフラグとして使用される整数は、1つのプロパティに複数の true/false (ブール)値を格納できます。 @export_flags アノテーションを使用すると、ビットフラグがエディタから設定できるようになります:

# Set any of the given flags from the editor.
@export_flags("Fire", "Water", "Earth", "Wind") var spell_elements = 0

各フラグにはエディタで表示する文字列を指定する必要があります。この例では Fire の値は1、 Water の値は2、 Earth の値は4、 Wind の値は8に対応します。通常、定数はそれに応じて定義する必要があります(例: const ELEMENT_WIND = 8 など)。

コロン:: を使用して明示的な値を指定できます。

@export_flags("Self:4", "Allies:8", "Foes:16") var spell_targets = 0

ビットフラグオプションとして、2の累乗値のみが有効です。 0は何も選択されていないことを意味するため、許容される最小値は1です。他のフラグを組み合わせたオプションを追加することもできます。

@export_flags("Self:4", "Allies:8", "Self and Allies:12", "Foes:16")
var spell_targets = 0

エクスポートアノテーションは、プロジェクト設定で定義された物理レイヤー、レンダリングレイヤー、およびナビゲーションレイヤーにも提供されます:

@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

ビットフラグを使用するには、ビット単位の演算についてある程度理解する必要があります。疑わしい場合は、代わりにブール変数を使用してください。

列挙型のエクスポート

See @export_enum.

プロパティを列挙型の値に制限するために、列挙型を参照する型ヒントを使用してエクスポートできます。エディタはインスペクタにウィジェットを作成し、以下を "Thing 1"、 "Thing 2" 、 "Another Thing" として列挙します。値は整数として保存されます。

enum NamedEnum {THING_1, THING_2, ANOTHER_THING = -1}
@export var x: NamedEnum

@export_enum アノテーションを使用して、整数および文字列のプロパティを特定の値のリストに制限することもできます。エディターはインスペクターにウィジェットを作成し、以下をWarrior、Magician、Thiefとして列挙します。値は選択したオプションのインデックス (つまり 0 、 1 、 2) に対応する整数として保存されます。

@export_enum("Warrior", "Magician", "Thief") var character_class: int

コロン:: を使用して明示的な値を指定できます。

@export_enum("Slow:30", "Average:60", "Very Fast:200") var character_speed: int

型がStringの場合、値は文字列として保存されます。

@export_enum("Rebecca", "Mary", "Leah") var character_name: String

初期値を設定したい場合は、それを明示的に指定する必要があります:

@export_enum("Rebecca", "Mary", "Leah") var character_name: String = "Rebecca"

配列のエクスポート

エクスポートされた配列は初期化子を持つことができますが、それらは定数式でなければなりません。

エクスポートされた配列が、Resourceを継承する型を指定している場合は、ファイルシステムドックから複数のファイルを一度にドラッグ＆ドロップすることで、インスペクタ上で配列の値を設定することができます。

デフォルト値は定数式である必要があります**。

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

エクスポートされる配列は型を指定できます (以前と同じヒントを使用して) 。

@export var ints: Array[int] = [1, 2, 3]

# Nested typed arrays such as `Array[Array[float]]` are not supported yet.
@export var two_dimensional: Array[Array] = [[1.0, 2.0], [3.0, 4.0]]

デフォルト値は省略できますが、指定しない場合は null になります。

@export var b: Array
@export var scenes: Array[PackedScene]

リソースを継承する型の配列は、ファイルシステムドックから複数のファイルをドラッグ＆ドロップすることで設定できます。

@export var textures: Array[Texture] = []
@export var scenes: Array[PackedScene] = []

パック配列も機能しますが、空の配列で初期化されます:

@export var vector3s = PackedVector3Array()
@export var strings = PackedStringArray()

配列をエクスポートする場合、他のエクスポートアノテーションも使用できます。

@export_range(-360, 360, 0.001, "degrees") var laser_angles: Array[float] = []
@export_file("*.json") var skill_trees: Array[String] = []
@export_color_no_alpha var hair_colors = PackedColorArray()
@export_enum("Espresso", "Mocha", "Latte", "Capuccino") var barista_suggestions: Array[String] = []

`@export_storage`

See @export_storage.

デフォルトでは、プロパティをエクスポートすると次の2つの効果があります。

プロパティの値はシーン/リソースファイルに保存されます (PROPERTY_USAGE_STORAGE);
インスペクタにフィールドが追加されます (PROPERTY_USAGE_EDITOR)。

ただし意図しない変更やインターフェイスの煩雑さを防ぐため、プロパティをシリアライズ可能にしてもエディタに表示したくない場合があります。

これを行うには @export_storage を使用できます。これは @tool スクリプトで設定するときに役立ちます。またエクスポートされない変数とは異なり、 Resource.duplicate() または Node.duplicate() が呼び出されたときにプロパティ値がコピーされます。

var a # Not stored in the file, not displayed in the editor.
@export_storage var b # Stored in the file, not displayed in the editor.
@export var c: int # Stored in the file, displayed in the editor.

`@export_custom`

If you need more control than what's exposed with the built-in @export annotations, you can use @export_custom instead. This allows defining any property hint, hint string and usage flags, with a syntax similar to the one used by the editor for built-in nodes.

For example, this exposes the altitude property with no range limits but a m (meter) suffix defined:

@export_custom(PROPERTY_HINT_NONE, "suffix:m") var altitude: float

The above is normally not feasible with the standard @export_range syntax, since it requires defining a range.

See the class reference for a list of parameters and their allowed values.

警告

When using @export_custom, GDScript does not perform any validation on the syntax. Invalid syntax may have unexpected behavior in the inspector.

`@export_tool_button`

If you need to create a clickable inspector button, you can use @export_tool_button. This exports a Callable property as a clickable button. When the button is pressed, the callable is called.

Export a button with label "Hello" and icon "Callable". When you press it, it will print "Hello world!".

@tool
extends Node

@export_tool_button("Hello", "Callable") var hello_action = hello

func hello():
    print("Hello world!")

エクスポートされた変数をツールスクリプトから設定する

ツールモードのスクリプトからエクスポートされた変数の値を変更する場合、インスペクタ内の値は自動的に更新されません。これを更新するにはエクスポートされた変数の値を設定した後、 notify_property_list_changed() を呼び出します。

高度なエクスポート

不必要な設計の複雑さを避けるために、言語自体のレベルですべてのタイプのエクスポートを提供できるわけではありません。以下では低レベルAPIで実装できる一般的なエクスポート機能について説明します。

さらに読み進める前に、プロパティの処理方法とカスタマイズ方法 ( doc_accessing_data_or_logic_from_object`で説明されている方法の :ref:`_set() 、 _get() 、 _get_property_list()) についてよく理解しておく必要があります。

参考

C++で上記のメソッドを使用してプロパティをバインドする場合は _set/_get/_get_property_list を使用してプロパティをバインドしますを参照してください。

警告

上記のメソッドがエディタ内から機能できるように、スクリプトは @tool モードで動作する必要があります。