1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
|
<?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 accessed in any script.
For the list of the global functions and constants see [@GlobalScope].
</description>
<tutorials>
</tutorials>
<methods>
<method name="Color8">
<return type="Color" />
<argument index="0" name="r8" type="int" />
<argument index="1" name="g8" type="int" />
<argument index="2" name="b8" type="int" />
<argument index="3" name="a8" type="int" default="255" />
<description>
Returns a color constructed from integer red, green, blue, and alpha channels. Each channel should have 8 bits of information ranging from 0 to 255.
[code]r8[/code] red channel
[code]g8[/code] green channel
[code]b8[/code] blue channel
[code]a8[/code] alpha channel
[codeblock]
red = Color8(255, 0, 0)
[/codeblock]
</description>
</method>
<method name="assert">
<return type="void" />
<argument index="0" name="condition" type="bool" />
<argument index="1" name="message" type="String" default="""" />
<description>
Asserts that the [code]condition[/code] is [code]true[/code]. If the [code]condition[/code] 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.
[b]Note:[/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.
The optional [code]message[/code] argument, if given, is shown in addition to the generic "Assertion failed" message. You can use this to provide additional details about why the assertion failed.
[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, "speed = %f, but the speed limit is 20" % speed) # Show a message with clarifying details
[/codeblock]
</description>
</method>
<method name="char">
<return type="String" />
<argument index="0" name="char" type="int" />
<description>
Returns a 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" />
<argument index="0" name="what" type="Variant" />
<argument index="1" name="type" type="int" />
<description>
Converts from a type to another in the best way possible. The [code]type[/code] parameter uses the [enum Variant.Type] values.
[codeblock]
a = Vector2(1, 0)
# Prints 1
print(a.length())
a = convert(a, TYPE_STRING)
# Prints 6 as "(1, 0)" is 6 characters
print(a.length())
[/codeblock]
</description>
</method>
<method name="dict2inst">
<return type="Object" />
<argument index="0" name="dictionary" type="Dictionary" />
<description>
Converts a dictionary (previously created with [method inst2dict]) back to an instance. Useful for deserializing.
</description>
</method>
<method name="get_stack">
<return type="Array" />
<description>
Returns an array of dictionaries representing the current call stack.
[codeblock]
func _ready():
foo()
func foo():
bar()
func bar():
print(get_stack())
[/codeblock]
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] Not supported for calling from threads. Instead, this will return an empty array.
</description>
</method>
<method name="inst2dict">
<return type="Dictionary" />
<argument index="0" name="instance" type="Object" />
<description>
Returns the passed instance converted to a dictionary (useful for serializing).
[codeblock]
var foo = "bar"
func _ready():
var d = inst2dict(self)
print(d.keys())
print(d.values())
[/codeblock]
Prints out:
[codeblock]
[@subpath, @path, foo]
[, res://test.gd, bar]
[/codeblock]
</description>
</method>
<method name="len">
<return type="int" />
<argument index="0" name="var" type="Variant" />
<description>
Returns length of Variant [code]var[/code]. Length is the character count of String, element count of Array, size of Dictionary, etc.
[b]Note:[/b] Generates a fatal error if Variant can not provide a length.
[codeblock]
a = [1, 2, 3, 4]
len(a) # Returns 4
[/codeblock]
</description>
</method>
<method name="load">
<return type="Resource" />
<argument index="0" name="path" type="String" />
<description>
Loads a resource from the filesystem located at [code]path[/code]. The resource is loaded on the method call (unless it's referenced already elsewhere, e.g. in another script or in the scene), which might cause slight delay, especially when loading 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 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 local path will just return [code]null[/code].
This method is a simplified version of [method ResourceLoader.load], which can be used for more advanced scenarios.
[b]Note:[/b] You have to import the files into the engine first to load them using [method load]. 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" />
<argument index="0" name="path" type="String" />
<description>
Returns a [Resource] from the filesystem located at [code]path[/code]. The resource is loaded during script parsing, i.e. is loaded with the script and [method preload] effectively acts as a reference to that resource. Note that the method requires a constant path. 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 script.
[codeblock]
# Instance 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.
Output in the console would look something like this:
[codeblock]
Test print
At: res://test.gd:15:_process()
[/codeblock]
[b]Note:[/b] Not supported for calling from threads. Instead of the stack frame, this will print the thread ID.
</description>
</method>
<method name="print_stack">
<return type="void" />
<description>
Prints a stack trace at the current code location. Only works when running with debugger turned on.
Output in the console would look something like this:
[codeblock]
Frame 0 - res://test.gd:16 in function '_process'
[/codeblock]
[b]Note:[/b] Not supported for calling from threads. Instead of the stack trace, this will 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="str" qualifiers="vararg">
<return type="String" />
<description>
Converts one or more arguments to string in the best way possible.
[codeblock]
var a = [10, 20, 30]
var b = str(a);
len(a) # Returns 3
len(b) # Returns 12
[/codeblock]
</description>
</method>
<method name="type_exists">
<return type="bool" />
<argument index="0" name="type" type="StringName" />
<description>
</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]Note:[/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]Note:[/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>
</class>
|