651 lines
34 KiB
XML
651 lines
34 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<class name="@GDScript" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../doc/class.xsd">
|
|
<brief_description>
|
|
Built-in GDScript functions.
|
|
</brief_description>
|
|
<description>
|
|
A list of GDScript-specific utility functions and annotations accessible from any script.
|
|
For the list of the global functions and constants see [@GlobalScope].
|
|
</description>
|
|
<tutorials>
|
|
<link title="GDScript exports">$DOCS_URL/tutorials/scripting/gdscript/gdscript_exports.html</link>
|
|
</tutorials>
|
|
<methods>
|
|
<method name="Color8">
|
|
<return type="Color" />
|
|
<param index="0" name="r8" type="int" />
|
|
<param index="1" name="g8" type="int" />
|
|
<param index="2" name="b8" type="int" />
|
|
<param index="3" name="a8" type="int" default="255" />
|
|
<description>
|
|
Returns a [Color] constructed from red ([param r8]), green ([param g8]), blue ([param b8]), and optionally alpha ([param a8]) integer channels, each divided by [code]255.0[/code] for their final value.
|
|
[codeblock]
|
|
var red = Color8(255, 0, 0) # Same as Color(1, 0, 0).
|
|
var dark_blue = Color8(0, 0, 51) # Same as Color(0, 0, 0.2).
|
|
var my_color = Color8(306, 255, 0, 102) # Same as Color(1.2, 1, 0, 0.4).
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="assert">
|
|
<return type="void" />
|
|
<param index="0" name="condition" type="bool" />
|
|
<param index="1" name="message" type="String" default="""" />
|
|
<description>
|
|
Asserts that the [param condition] is [code]true[/code]. If the [param condition] is [code]false[/code], an error is generated. When running from the editor, the running project will also be paused until you resume it. This can be used as a stronger form of [method @GlobalScope.push_error] for reporting errors to project developers or add-on users.
|
|
An optional [param message] can be shown in addition to the generic "Assertion failed" message. You can use this to provide additional details about why the assertion failed.
|
|
[b]Warning:[/b] For performance reasons, the code inside [method assert] is only executed in debug builds or when running the project from the editor. Don't include code that has side effects in an [method assert] call. Otherwise, the project will behave differently when exported in release mode.
|
|
[codeblock]
|
|
# Imagine we always want speed to be between 0 and 20.
|
|
var speed = -10
|
|
assert(speed < 20) # True, the program will continue.
|
|
assert(speed >= 0) # False, the program will stop.
|
|
assert(speed >= 0 and speed < 20) # You can also combine the two conditional statements in one check.
|
|
assert(speed < 20, "the speed limit is 20") # Show a message.
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="char">
|
|
<return type="String" />
|
|
<param index="0" name="char" type="int" />
|
|
<description>
|
|
Returns a single character (as a [String]) of the given Unicode code point (which is compatible with ASCII code).
|
|
[codeblock]
|
|
a = char(65) # a is "A"
|
|
a = char(65 + 32) # a is "a"
|
|
a = char(8364) # a is "€"
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="convert">
|
|
<return type="Variant" />
|
|
<param index="0" name="what" type="Variant" />
|
|
<param index="1" name="type" type="int" />
|
|
<description>
|
|
Converts [param what] to [param type] in the best way possible. The [param type] uses the [enum Variant.Type] values.
|
|
[codeblock]
|
|
var a = [4, 2.5, 1.2]
|
|
print(a is Array) # Prints true
|
|
|
|
var b = convert(a, TYPE_PACKED_BYTE_ARRAY)
|
|
print(b) # Prints [4, 2, 1]
|
|
print(b is Array) # Prints false
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="dict_to_inst">
|
|
<return type="Object" />
|
|
<param index="0" name="dictionary" type="Dictionary" />
|
|
<description>
|
|
Converts a [param dictionary] (created with [method inst_to_dict]) back to an Object instance. Can be useful for deserializing.
|
|
</description>
|
|
</method>
|
|
<method name="get_stack">
|
|
<return type="Array" />
|
|
<description>
|
|
Returns an array of dictionaries representing the current call stack. See also [method print_stack].
|
|
[codeblock]
|
|
func _ready():
|
|
foo()
|
|
|
|
func foo():
|
|
bar()
|
|
|
|
func bar():
|
|
print(get_stack())
|
|
[/codeblock]
|
|
Starting from [code]_ready()[/code], [code]bar()[/code] would print:
|
|
[codeblock]
|
|
[{function:bar, line:12, source:res://script.gd}, {function:foo, line:9, source:res://script.gd}, {function:_ready, line:6, source:res://script.gd}]
|
|
[/codeblock]
|
|
[b]Note:[/b] This function only works if the running instance is connected to a debugging server (i.e. an editor instance). [method get_stack] will not work in projects exported in release mode, or in projects exported in debug mode if not connected to a debugging server.
|
|
[b]Note:[/b] Calling this function from a [Thread] is not supported. Doing so will return an empty array.
|
|
</description>
|
|
</method>
|
|
<method name="inst_to_dict">
|
|
<return type="Dictionary" />
|
|
<param index="0" name="instance" type="Object" />
|
|
<description>
|
|
Returns the passed [param instance] converted to a Dictionary. Can be useful for serializing.
|
|
[b]Note:[/b] Cannot be used to serialize objects with built-in scripts attached or objects allocated within built-in scripts.
|
|
[codeblock]
|
|
var foo = "bar"
|
|
func _ready():
|
|
var d = inst_to_dict(self)
|
|
print(d.keys())
|
|
print(d.values())
|
|
[/codeblock]
|
|
Prints out:
|
|
[codeblock]
|
|
[@subpath, @path, foo]
|
|
[, res://test.gd, bar]
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="is_instance_of">
|
|
<return type="bool" />
|
|
<param index="0" name="value" type="Variant" />
|
|
<param index="1" name="type" type="Variant" />
|
|
<description>
|
|
Returns [code]true[/code] if [param value] is an instance of [param type]. The [param type] value must be one of the following:
|
|
- A constant from the [enum Variant.Type] enumeration, for example [constant TYPE_INT].
|
|
- An [Object]-derived class which exists in [ClassDB], for example [Node].
|
|
- A [Script] (you can use any class, including inner one).
|
|
Unlike the right operand of the [code]is[/code] operator, [param type] can be a non-constant value. The [code]is[/code] operator supports more features (such as typed arrays) and is more performant. Use the operator instead of this method if you do not need dynamic type checking.
|
|
Examples:
|
|
[codeblock]
|
|
print(is_instance_of(a, TYPE_INT))
|
|
print(is_instance_of(a, Node))
|
|
print(is_instance_of(a, MyClass))
|
|
print(is_instance_of(a, MyClass.InnerClass))
|
|
[/codeblock]
|
|
[b]Note:[/b] If [param value] and/or [param type] are freed objects (see [method @GlobalScope.is_instance_valid]), or [param type] is not one of the above options, this method will raise an runtime error.
|
|
See also [method @GlobalScope.typeof], [method type_exists], [method Array.is_same_typed] (and other [Array] methods).
|
|
</description>
|
|
</method>
|
|
<method name="len">
|
|
<return type="int" />
|
|
<param index="0" name="var" type="Variant" />
|
|
<description>
|
|
Returns the length of the given Variant [param var]. The length can be the character count of a [String], the element count of any array type or the size of a [Dictionary]. For every other Variant type, a run-time error is generated and execution is stopped.
|
|
[codeblock]
|
|
a = [1, 2, 3, 4]
|
|
len(a) # Returns 4
|
|
|
|
b = "Hello!"
|
|
len(b) # Returns 6
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="load">
|
|
<return type="Resource" />
|
|
<param index="0" name="path" type="String" />
|
|
<description>
|
|
Returns a [Resource] from the filesystem located at the absolute [param path]. Unless it's already referenced elsewhere (such as in another script or in the scene), the resource is loaded from disk on function call, which might cause a slight delay, especially when loading large scenes. To avoid unnecessary delays when loading something multiple times, either store the resource in a variable or use [method preload].
|
|
[b]Note:[/b] Resource paths can be obtained by right-clicking on a resource in the FileSystem dock and choosing "Copy Path", or by dragging the file from the FileSystem dock into the current script.
|
|
[codeblock]
|
|
# Load a scene called "main" located in the root of the project directory and cache it in a variable.
|
|
var main = load("res://main.tscn") # main will contain a PackedScene resource.
|
|
[/codeblock]
|
|
[b]Important:[/b] The path must be absolute. A relative path will always return [code]null[/code].
|
|
This function is a simplified version of [method ResourceLoader.load], which can be used for more advanced scenarios.
|
|
[b]Note:[/b] Files have to be imported into the engine first to load them using this function. If you want to load [Image]s at run-time, you may use [method Image.load]. If you want to import audio files, you can use the snippet described in [member AudioStreamMP3.data].
|
|
</description>
|
|
</method>
|
|
<method name="preload">
|
|
<return type="Resource" />
|
|
<param index="0" name="path" type="String" />
|
|
<description>
|
|
Returns a [Resource] from the filesystem located at [param path]. During run-time, the resource is loaded when the script is being parsed. This function effectively acts as a reference to that resource. Note that this function requires [param path] to be a constant [String]. If you want to load a resource from a dynamic/variable path, use [method load].
|
|
[b]Note:[/b] Resource paths can be obtained by right-clicking on a resource in the Assets Panel and choosing "Copy Path", or by dragging the file from the FileSystem dock into the current script.
|
|
[codeblock]
|
|
# Create instance of a scene.
|
|
var diamond = preload("res://diamond.tscn").instantiate()
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="print_debug" qualifiers="vararg">
|
|
<return type="void" />
|
|
<description>
|
|
Like [method @GlobalScope.print], but includes the current stack frame when running with the debugger turned on.
|
|
The output in the console may look like the following:
|
|
[codeblock]
|
|
Test print
|
|
At: res://test.gd:15:_process()
|
|
[/codeblock]
|
|
[b]Note:[/b] Calling this function from a [Thread] is not supported. Doing so will instead print the thread ID.
|
|
</description>
|
|
</method>
|
|
<method name="print_stack">
|
|
<return type="void" />
|
|
<description>
|
|
Prints a stack trace at the current code location. See also [method get_stack].
|
|
The output in the console may look like the following:
|
|
[codeblock]
|
|
Frame 0 - res://test.gd:16 in function '_process'
|
|
[/codeblock]
|
|
[b]Note:[/b] This function only works if the running instance is connected to a debugging server (i.e. an editor instance). [method print_stack] will not work in projects exported in release mode, or in projects exported in debug mode if not connected to a debugging server.
|
|
[b]Note:[/b] Calling this function from a [Thread] is not supported. Doing so will instead print the thread ID.
|
|
</description>
|
|
</method>
|
|
<method name="range" qualifiers="vararg">
|
|
<return type="Array" />
|
|
<description>
|
|
Returns an array with the given range. [method range] can be called in three ways:
|
|
[code]range(n: int)[/code]: Starts from 0, increases by steps of 1, and stops [i]before[/i] [code]n[/code]. The argument [code]n[/code] is [b]exclusive[/b].
|
|
[code]range(b: int, n: int)[/code]: Starts from [code]b[/code], increases by steps of 1, and stops [i]before[/i] [code]n[/code]. The arguments [code]b[/code] and [code]n[/code] are [b]inclusive[/b] and [b]exclusive[/b], respectively.
|
|
[code]range(b: int, n: int, s: int)[/code]: Starts from [code]b[/code], increases/decreases by steps of [code]s[/code], and stops [i]before[/i] [code]n[/code]. The arguments [code]b[/code] and [code]n[/code] are [b]inclusive[/b] and [b]exclusive[/b], respectively. The argument [code]s[/code] [b]can[/b] be negative, but not [code]0[/code]. If [code]s[/code] is [code]0[/code], an error message is printed.
|
|
[method range] converts all arguments to [int] before processing.
|
|
[b]Note:[/b] Returns an empty array if no value meets the value constraint (e.g. [code]range(2, 5, -1)[/code] or [code]range(5, 5, 1)[/code]).
|
|
Examples:
|
|
[codeblock]
|
|
print(range(4)) # Prints [0, 1, 2, 3]
|
|
print(range(2, 5)) # Prints [2, 3, 4]
|
|
print(range(0, 6, 2)) # Prints [0, 2, 4]
|
|
print(range(4, 1, -1)) # Prints [4, 3, 2]
|
|
[/codeblock]
|
|
To iterate over an [Array] backwards, use:
|
|
[codeblock]
|
|
var array = [3, 6, 9]
|
|
for i in range(array.size(), 0, -1):
|
|
print(array[i - 1])
|
|
[/codeblock]
|
|
Output:
|
|
[codeblock]
|
|
9
|
|
6
|
|
3
|
|
[/codeblock]
|
|
To iterate over [float], convert them in the loop.
|
|
[codeblock]
|
|
for i in range (3, 0, -1):
|
|
print(i / 10.0)
|
|
[/codeblock]
|
|
Output:
|
|
[codeblock]
|
|
0.3
|
|
0.2
|
|
0.1
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
<method name="type_exists">
|
|
<return type="bool" />
|
|
<param index="0" name="type" type="StringName" />
|
|
<description>
|
|
Returns [code]true[/code] if the given [Object]-derived class exists in [ClassDB]. Note that [Variant] data types are not registered in [ClassDB].
|
|
[codeblock]
|
|
type_exists("Sprite2D") # Returns true
|
|
type_exists("NonExistentClass") # Returns false
|
|
[/codeblock]
|
|
</description>
|
|
</method>
|
|
</methods>
|
|
<constants>
|
|
<constant name="PI" value="3.14159265358979">
|
|
Constant that represents how many times the diameter of a circle fits around its perimeter. This is equivalent to [code]TAU / 2[/code], or 180 degrees in rotations.
|
|
</constant>
|
|
<constant name="TAU" value="6.28318530717959">
|
|
The circle constant, the circumference of the unit circle in radians. This is equivalent to [code]PI * 2[/code], or 360 degrees in rotations.
|
|
</constant>
|
|
<constant name="INF" value="inf">
|
|
Positive floating-point infinity. This is the result of floating-point division when the divisor is [code]0.0[/code]. For negative infinity, use [code]-INF[/code]. Dividing by [code]-0.0[/code] will result in negative infinity if the numerator is positive, so dividing by [code]0.0[/code] is not the same as dividing by [code]-0.0[/code] (despite [code]0.0 == -0.0[/code] returning [code]true[/code]).
|
|
[b]Warning:[/b] Numeric infinity is only a concept with floating-point numbers, and has no equivalent for integers. Dividing an integer number by [code]0[/code] will not result in [constant INF] and will result in a run-time error instead.
|
|
</constant>
|
|
<constant name="NAN" value="nan">
|
|
"Not a Number", an invalid floating-point value. [constant NAN] has special properties, including that it is not equal to itself ([code]NAN == NAN[/code] returns [code]false[/code]). It is output by some invalid operations, such as dividing floating-point [code]0.0[/code] by [code]0.0[/code].
|
|
[b]Warning:[/b] "Not a Number" is only a concept with floating-point numbers, and has no equivalent for integers. Dividing an integer [code]0[/code] by [code]0[/code] will not result in [constant NAN] and will result in a run-time error instead.
|
|
</constant>
|
|
</constants>
|
|
<annotations>
|
|
<annotation name="@export">
|
|
<return type="void" />
|
|
<description>
|
|
Mark the following property as exported (editable in the Inspector dock and saved to disk). To control the type of the exported property, use the type hint notation.
|
|
[codeblock]
|
|
@export var string = ""
|
|
@export var int_number = 5
|
|
@export var float_number: float = 5
|
|
@export var image: Image
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_category">
|
|
<return type="void" />
|
|
<param index="0" name="name" type="String" />
|
|
<description>
|
|
Define a new category for the following exported properties. This helps to organize properties in the Inspector dock.
|
|
See also [constant PROPERTY_USAGE_CATEGORY].
|
|
[codeblock]
|
|
@export_category("Statistics")
|
|
@export var hp = 30
|
|
@export var speed = 1.25
|
|
[/codeblock]
|
|
[b]Note:[/b] Categories in the Inspector dock's list usually divide properties coming from different classes (Node, Node2D, Sprite, etc.). For better clarity, it's recommended to use [annotation @export_group] and [annotation @export_subgroup], instead.
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_color_no_alpha">
|
|
<return type="void" />
|
|
<description>
|
|
Export a [Color] property without allowing its transparency ([member Color.a]) to be edited.
|
|
See also [constant PROPERTY_HINT_COLOR_NO_ALPHA].
|
|
[codeblock]
|
|
@export_color_no_alpha var dye_color: Color
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_dir">
|
|
<return type="void" />
|
|
<description>
|
|
Export a [String] property as a path to a directory. The path will be limited to the project folder and its subfolders. See [annotation @export_global_dir] to allow picking from the entire filesystem.
|
|
See also [constant PROPERTY_HINT_DIR].
|
|
[codeblock]
|
|
@export_dir var sprite_folder_path: String
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_enum" qualifiers="vararg">
|
|
<return type="void" />
|
|
<param index="0" name="names" type="String" />
|
|
<description>
|
|
Export an [int] or [String] property as an enumerated list of options. If the property is an [int], then the index of the value is stored, in the same order the values are provided. You can add explicit values using a colon. If the property is a [String], then the value is stored.
|
|
See also [constant PROPERTY_HINT_ENUM].
|
|
[codeblock]
|
|
@export_enum("Warrior", "Magician", "Thief") var character_class: int
|
|
@export_enum("Slow:30", "Average:60", "Very Fast:200") var character_speed: int
|
|
@export_enum("Rebecca", "Mary", "Leah") var character_name: String
|
|
[/codeblock]
|
|
If you want to set an initial value, you must specify it explicitly:
|
|
[codeblock]
|
|
@export_enum("Rebecca", "Mary", "Leah") var character_name: String = "Rebecca"
|
|
[/codeblock]
|
|
If you want to use named GDScript enums, then use [annotation @export] instead:
|
|
[codeblock]
|
|
enum CharacterName {REBECCA, MARY, LEAH}
|
|
@export var character_name: CharacterName
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_exp_easing" qualifiers="vararg">
|
|
<return type="void" />
|
|
<param index="0" name="hints" type="String" default="""" />
|
|
<description>
|
|
Export a floating-point property with an easing editor widget. Additional hints can be provided to adjust the behavior of the widget. [code]"attenuation"[/code] flips the curve, which makes it more intuitive for editing attenuation properties. [code]"positive_only"[/code] limits values to only be greater than or equal to zero.
|
|
See also [constant PROPERTY_HINT_EXP_EASING].
|
|
[codeblock]
|
|
@export_exp_easing var transition_speed
|
|
@export_exp_easing("attenuation") var fading_attenuation
|
|
@export_exp_easing("positive_only") var effect_power
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_file" qualifiers="vararg">
|
|
<return type="void" />
|
|
<param index="0" name="filter" type="String" default="""" />
|
|
<description>
|
|
Export a [String] property as a path to a file. The path will be limited to the project folder and its subfolders. See [annotation @export_global_file] to allow picking from the entire filesystem.
|
|
If [param filter] is provided, only matching files will be available for picking.
|
|
See also [constant PROPERTY_HINT_FILE].
|
|
[codeblock]
|
|
@export_file var sound_effect_path: String
|
|
@export_file("*.txt") var notes_path: String
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_flags" qualifiers="vararg">
|
|
<return type="void" />
|
|
<param index="0" name="names" type="String" />
|
|
<description>
|
|
Export an integer property as a bit flag field. This allows to store several "checked" or [code]true[/code] values with one property, and comfortably select them from the Inspector dock.
|
|
See also [constant PROPERTY_HINT_FLAGS].
|
|
[codeblock]
|
|
@export_flags("Fire", "Water", "Earth", "Wind") var spell_elements = 0
|
|
[/codeblock]
|
|
You can add explicit values using a colon:
|
|
[codeblock]
|
|
@export_flags("Self:4", "Allies:8", "Foes:16") var spell_targets = 0
|
|
[/codeblock]
|
|
You can also combine several flags:
|
|
[codeblock]
|
|
@export_flags("Self:4", "Allies:8", "Self and Allies:12", "Foes:16")
|
|
var spell_targets = 0
|
|
[/codeblock]
|
|
[b]Note:[/b] A flag value must be at least [code]1[/code] and at most [code]2 ** 32 - 1[/code].
|
|
[b]Note:[/b] Unlike [annotation @export_enum], the previous explicit value is not taken into account. In the following example, A is 16, B is 2, C is 4.
|
|
[codeblock]
|
|
@export_flags("A:16", "B", "C") var x
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_flags_2d_navigation">
|
|
<return type="void" />
|
|
<description>
|
|
Export an integer property as a bit flag field for 2D navigation layers. The widget in the Inspector dock will use the layer names defined in [member ProjectSettings.layer_names/2d_navigation/layer_1].
|
|
See also [constant PROPERTY_HINT_LAYERS_2D_NAVIGATION].
|
|
[codeblock]
|
|
@export_flags_2d_navigation var navigation_layers: int
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_flags_2d_physics">
|
|
<return type="void" />
|
|
<description>
|
|
Export an integer property as a bit flag field for 2D physics layers. The widget in the Inspector dock will use the layer names defined in [member ProjectSettings.layer_names/2d_physics/layer_1].
|
|
See also [constant PROPERTY_HINT_LAYERS_2D_PHYSICS].
|
|
[codeblock]
|
|
@export_flags_2d_physics var physics_layers: int
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_flags_2d_render">
|
|
<return type="void" />
|
|
<description>
|
|
Export an integer property as a bit flag field for 2D render layers. The widget in the Inspector dock will use the layer names defined in [member ProjectSettings.layer_names/2d_render/layer_1].
|
|
See also [constant PROPERTY_HINT_LAYERS_2D_RENDER].
|
|
[codeblock]
|
|
@export_flags_2d_render var render_layers: int
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_flags_3d_navigation">
|
|
<return type="void" />
|
|
<description>
|
|
Export an integer property as a bit flag field for 3D navigation layers. The widget in the Inspector dock will use the layer names defined in [member ProjectSettings.layer_names/3d_navigation/layer_1].
|
|
See also [constant PROPERTY_HINT_LAYERS_3D_NAVIGATION].
|
|
[codeblock]
|
|
@export_flags_3d_navigation var navigation_layers: int
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_flags_3d_physics">
|
|
<return type="void" />
|
|
<description>
|
|
Export an integer property as a bit flag field for 3D physics layers. The widget in the Inspector dock will use the layer names defined in [member ProjectSettings.layer_names/3d_physics/layer_1].
|
|
See also [constant PROPERTY_HINT_LAYERS_3D_PHYSICS].
|
|
[codeblock]
|
|
@export_flags_3d_physics var physics_layers: int
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_flags_3d_render">
|
|
<return type="void" />
|
|
<description>
|
|
Export an integer property as a bit flag field for 3D render layers. The widget in the Inspector dock will use the layer names defined in [member ProjectSettings.layer_names/3d_render/layer_1].
|
|
See also [constant PROPERTY_HINT_LAYERS_3D_RENDER].
|
|
[codeblock]
|
|
@export_flags_3d_render var render_layers: int
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_global_dir">
|
|
<return type="void" />
|
|
<description>
|
|
Export a [String] property as an absolute path to a directory. The path can be picked from the entire filesystem. See [annotation @export_dir] to limit it to the project folder and its subfolders.
|
|
See also [constant PROPERTY_HINT_GLOBAL_DIR].
|
|
[codeblock]
|
|
@export_global_dir var sprite_folder_path: String
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_global_file" qualifiers="vararg">
|
|
<return type="void" />
|
|
<param index="0" name="filter" type="String" default="""" />
|
|
<description>
|
|
Export a [String] property as an absolute path to a file. The path can be picked from the entire filesystem. See [annotation @export_file] to limit it to the project folder and its subfolders.
|
|
If [param filter] is provided, only matching files will be available for picking.
|
|
See also [constant PROPERTY_HINT_GLOBAL_FILE].
|
|
[codeblock]
|
|
@export_global_file var sound_effect_path: String
|
|
@export_global_file("*.txt") var notes_path: String
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_group">
|
|
<return type="void" />
|
|
<param index="0" name="name" type="String" />
|
|
<param index="1" name="prefix" type="String" default="""" />
|
|
<description>
|
|
Define a new group for the following exported properties. This helps to organize properties in the Inspector dock. Groups can be added with an optional [param prefix], which would make group to only consider properties that have this prefix. The grouping will break on the first property that doesn't have a prefix. The prefix is also removed from the property's name in the Inspector dock.
|
|
If no [param prefix] is provided, the every following property is added to the group. The group ends when then next group or category is defined. You can also force end a group by using this annotation with empty strings for parameters, [code]@export_group("", "")[/code].
|
|
Groups cannot be nested, use [annotation @export_subgroup] to add subgroups within groups.
|
|
See also [constant PROPERTY_USAGE_GROUP].
|
|
[codeblock]
|
|
@export_group("Racer Properties")
|
|
@export var nickname = "Nick"
|
|
@export var age = 26
|
|
|
|
@export_group("Car Properties", "car_")
|
|
@export var car_label = "Speedy"
|
|
@export var car_number = 3
|
|
|
|
@export_group("", "")
|
|
@export var ungrouped_number = 3
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_multiline">
|
|
<return type="void" />
|
|
<description>
|
|
Export a [String] property with a large [TextEdit] widget instead of a [LineEdit]. This adds support for multiline content and makes it easier to edit large amount of text stored in the property.
|
|
See also [constant PROPERTY_HINT_MULTILINE_TEXT].
|
|
[codeblock]
|
|
@export_multiline var character_biography
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_node_path" qualifiers="vararg">
|
|
<return type="void" />
|
|
<param index="0" name="type" type="String" default="""" />
|
|
<description>
|
|
Export a [NodePath] property with a filter for allowed node types.
|
|
See also [constant PROPERTY_HINT_NODE_PATH_VALID_TYPES].
|
|
[codeblock]
|
|
@export_node_path("Button", "TouchScreenButton") var some_button
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_placeholder">
|
|
<return type="void" />
|
|
<param index="0" name="placeholder" type="String" />
|
|
<description>
|
|
Export a [String] property with a placeholder text displayed in the editor widget when no value is present.
|
|
See also [constant PROPERTY_HINT_PLACEHOLDER_TEXT].
|
|
[codeblock]
|
|
@export_placeholder("Name in lowercase") var character_id: String
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_range" qualifiers="vararg">
|
|
<return type="void" />
|
|
<param index="0" name="min" type="float" />
|
|
<param index="1" name="max" type="float" />
|
|
<param index="2" name="step" type="float" default="1.0" />
|
|
<param index="3" name="extra_hints" type="String" default="""" />
|
|
<description>
|
|
Export an [int] or [float] property as a range value. The range must be defined by [param min] and [param max], as well as an optional [param step] and a variety of extra hints. The [param step] defaults to [code]1[/code] for integer properties. For floating-point numbers this value depends on your [code]EditorSettings.interface/inspector/default_float_step[/code] setting.
|
|
If hints [code]"or_greater"[/code] and [code]"or_less"[/code] are provided, the editor widget will not cap the value at range boundaries. The [code]"exp"[/code] hint will make the edited values on range to change exponentially. The [code]"hide_slider"[/code] hint will hide the slider element of the editor widget.
|
|
Hints also allow to indicate the units for the edited value. Using [code]"radians"[/code] you can specify that the actual value is in radians, but should be displayed in degrees in the Inspector dock. [code]"degrees"[/code] allows to add a degree sign as a unit suffix. Finally, a custom suffix can be provided using [code]"suffix:unit"[/code], where "unit" can be any string.
|
|
See also [constant PROPERTY_HINT_RANGE].
|
|
[codeblock]
|
|
@export_range(0, 20) var number
|
|
@export_range(-10, 20) var number
|
|
@export_range(-10, 20, 0.2) var number: float
|
|
|
|
@export_range(0, 100, 1, "or_greater") var power_percent
|
|
@export_range(0, 100, 1, "or_greater", "or_less") var health_delta
|
|
|
|
@export_range(-3.14, 3.14, 0.001, "radians") var angle_radians
|
|
@export_range(0, 360, 1, "degrees") var angle_degrees
|
|
@export_range(-8, 8, 2, "suffix:px") var target_offset
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@export_subgroup">
|
|
<return type="void" />
|
|
<param index="0" name="name" type="String" />
|
|
<param index="1" name="prefix" type="String" default="""" />
|
|
<description>
|
|
Define a new subgroup for the following exported properties. This helps to organize properties in the Inspector dock. Subgroups work exactly like groups, except they need a parent group to exist. See [annotation @export_group].
|
|
See also [constant PROPERTY_USAGE_SUBGROUP].
|
|
[codeblock]
|
|
@export_group("Racer Properties")
|
|
@export var nickname = "Nick"
|
|
@export var age = 26
|
|
|
|
@export_subgroup("Car Properties", "car_")
|
|
@export var car_label = "Speedy"
|
|
@export var car_number = 3
|
|
[/codeblock]
|
|
[b]Note:[/b] Subgroups cannot be nested, they only provide one extra level of depth. Just like the next group ends the previous group, so do the subsequent subgroups.
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@icon">
|
|
<return type="void" />
|
|
<param index="0" name="icon_path" type="String" />
|
|
<description>
|
|
Add a custom icon to the current script. The script must be registered as a global class using the [code]class_name[/code] keyword for this to have a visible effect. The icon specified at [param icon_path] is displayed in the Scene dock for every node of that class, as well as in various editor dialogs.
|
|
[codeblock]
|
|
@icon("res://path/to/class/icon.svg")
|
|
[/codeblock]
|
|
[b]Note:[/b] Only the script can have a custom icon. Inner classes are not supported.
|
|
[b]Note:[/b] As annotations describe their subject, the [code]@icon[/code] annotation must be placed before the class definition and inheritance.
|
|
[b]Note:[/b] Unlike other annotations, the argument of the [code]@icon[/code] annotation must be a string literal (constant expressions are not supported).
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@onready">
|
|
<return type="void" />
|
|
<description>
|
|
Mark the following property as assigned when the [Node] is ready. Values for these properties are not assigned immediately when the node is initialized ([method Object._init]), and instead are computed and stored right before [method Node._ready].
|
|
[codeblock]
|
|
@onready var character_name: Label = $Label
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@rpc" qualifiers="vararg">
|
|
<return type="void" />
|
|
<param index="0" name="mode" type="String" default=""authority"" />
|
|
<param index="1" name="sync" type="String" default=""call_remote"" />
|
|
<param index="2" name="transfer_mode" type="String" default=""unreliable"" />
|
|
<param index="3" name="transfer_channel" type="int" default="0" />
|
|
<description>
|
|
Mark the following method for remote procedure calls. See [url=$DOCS_URL/tutorials/networking/high_level_multiplayer.html]High-level multiplayer[/url].
|
|
The order of [code]mode[/code], [code]sync[/code] and [code]transfer_mode[/code] does not matter and all arguments can be omitted, but [code]transfer_channel[/code] always has to be the last argument. The accepted values for [code]mode[/code] are [code]"any_peer"[/code] or [code]"authority"[/code], for [code]sync[/code] are [code]"call_remote"[/code] or [code]"call_local"[/code] and for [code]transfer_mode[/code] are [code]"unreliable"[/code], [code]"unreliable_ordered"[/code] or [code]"reliable"[/code].
|
|
[codeblock]
|
|
@rpc
|
|
func fn(): pass
|
|
|
|
@rpc("any_peer", "unreliable_ordered")
|
|
func fn_update_pos(): pass
|
|
|
|
@rpc("authority", "call_remote", "unreliable", 0) # Equivalent to @rpc
|
|
func fn_default(): pass
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@tool">
|
|
<return type="void" />
|
|
<description>
|
|
Mark the current script as a tool script, allowing it to be loaded and executed by the editor. See [url=$DOCS_URL/tutorials/plugins/running_code_in_the_editor.html]Running code in the editor[/url].
|
|
[codeblock]
|
|
@tool
|
|
extends Node
|
|
[/codeblock]
|
|
[b]Note:[/b] As annotations describe their subject, the [code]@tool[/code] annotation must be placed before the class definition and inheritance.
|
|
</description>
|
|
</annotation>
|
|
<annotation name="@warning_ignore" qualifiers="vararg">
|
|
<return type="void" />
|
|
<param index="0" name="warning" type="String" />
|
|
<description>
|
|
Mark the following statement to ignore the specified [param warning]. See [url=$DOCS_URL/tutorials/scripting/gdscript/warning_system.html]GDScript warning system[/url].
|
|
[codeblock]
|
|
func test():
|
|
print("hello")
|
|
return
|
|
@warning_ignore("unreachable_code")
|
|
print("unreachable")
|
|
[/codeblock]
|
|
</description>
|
|
</annotation>
|
|
</annotations>
|
|
</class>
|