Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

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 の値が保存され、プロパティ エディタにも表示されます。

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

One of the fundamental benefits of exporting member variables is to have them visible and editable in the editor. This way, artists and game designers can modify values that later influence how the program runs. For this, a special export syntax is provided. Additionally, documentation comments can be used for tooltip descriptions, visible on mouse over.

注釈

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

基本的な使い方

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

@export var number = 5

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

@export var number: int

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

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

Even if a script is not executed in the editor, exported properties can still be edited. However, getters and setters will only be used if the script is in ツールモード.

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

Strings as input actions

String as an input action defined in the project's input map.

@export_custom(PROPERTY_HINT_INPUT_NAME) var my_input

String as an input action defined in the project's input map, plus default built-in values such as ui_accept and ui_cancel.

@export_custom(PROPERTY_HINT_INPUT_NAME, "show_builtin") var my_input

String as an input action defined in the project's input map, plus arbitrary values that can manually be entered.

@export_custom(PROPERTY_HINT_INPUT_NAME, "loose_mode") var my_input

String as an input action defined in the project's input map, plus default built-in values such as ui_accept and ui_cancel and arbitrary values that can manually be entered.

@export_custom(PROPERTY_HINT_INPUT_NAME, "show_builtin,loose_mode") var my_input

入力範囲の制限

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

On the other hand, the "prefer_slider" hint can be used to show a horizontal bar below int properties instead of up/down arrows:

@export_range(0, 100, 1, "prefer_slider") var with_slider: int

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.

Linking vector values together

It is possible to link vector values together. When the user adjusts one of the vector's components, the other components are automatically adjusted proportionally. For example, this is useful to maintain the aspect ratio of a 2D sprite when adjusting its scale. This feature can be temporarily disabled by the user by clicking the link icon to the right of the property.

# Leave the hint string empty if you don't want to add a suffix.
@export_custom(PROPERTY_HINT_LINK, "suffix:px") var vector2_linked: Vector2 = Vector2(16, 16)

Results in:

Linked Vector2i property with the "px" suffix

This hint is effective on Vector2, Vector2i, Vector3, Vector3i, Vector4, and Vector4i. It can be used at the same time as a property suffix, as seen in the example above.

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

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

ノード

Nodes can also be directly exported as properties in a script without having to use NodePaths:

# 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.

注釈

Using @export variables for Resource objects makes them a dependency of the instance, meaning that all the resources referenced by @export variables are loaded when the scene containing the script is loaded. If you want to reference a Resource object but load it manually when you need it (which, for example, is often the case for PackedScenes containing a whole level), use @export_file or @export_file_path instead.

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

See @export_flags.

Integers used as bit flags can store multiple true/false (boolean) values in one property. By using the @export_flags annotation, they can be set from the editor:

# 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 など)。

You can add explicit values using a colon:

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

Only power of 2 values are valid as bit flags options. The lowest allowed value is 1, as 0 means that nothing is selected. You can also add options that are a combination of other flags:

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

Export annotations are also provided for the physics, render, and navigation layers defined in the project settings:

@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

You can add explicit values using a colon:

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

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

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

If you want to set an initial value, you must specify it explicitly:

@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つの効果があります。

1. プロパティの値はシーン/リソースファイルに保存されます (PROPERTY_USAGE_STORAGE);

2. インスペクタにフィールドが追加されます (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 an 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.

You can specify a custom icon name, which must match one of the icon file names from the editor/icons folder of the Godot source repository (case-sensitive). You can also browse the editor icons using the Godot editor icons website.

For example, if you wish to use Node2D.svg from that folder, you must specify "Node2D" as the second parameter of @export_tool_button. It is not currently possible to use custom icons from the project folder; only built-in editor icons can be used.

This exports a button with label "Hello" and icon "Callable" (which is the default if no icon is specified). 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() を呼び出します。

Reading an exported variable's value early on

If you read an exported variable's value in _init(), it will return the default value specified in the export annotation instead of the value that was set in the inspector. This is because assigning values from the saved scene/resource file occurs after object initialization; until then, the default value is used.

To get the value that was set in the inspector (and therefore saved in the scene/resource file), you need to read it after the object is constructed, such as in Node._ready(). You can also read the value in a setter that's defined on the exported property, which is useful in custom resources where _ready() is not available:

# Set this property to 3 in the inspector.
@export var exported_variable = 2:
    set(value):
        exported_variable = value
        print("Inspector-set value: ", exported_variable)

func _init():
    print("Initial value: ", exported_variable)

Results in:

Initial value: 2
Inspector-set value: 3

高度なエクスポート

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

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

参考

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

警告

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