forked from godotengine/godot
-
Notifications
You must be signed in to change notification settings - Fork 0
/
@GlobalScope.xml
3129 lines (3104 loc) · 134 KB
/
@GlobalScope.xml
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
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="UTF-8" ?>
<class name="@GlobalScope" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Global scope constants and functions.
</brief_description>
<description>
A list of global scope enumerated constants and built-in functions. This is all that resides in the globals, constants regarding error codes, keycodes, property hints, etc.
Singletons are also documented here, since they can be accessed from anywhere.
For the entries related to GDScript which can be accessed in any script see [@GDScript].
</description>
<tutorials>
<link title="Random number generation">$DOCS_URL/tutorials/math/random_number_generation.html</link>
</tutorials>
<methods>
<method name="abs">
<return type="Variant" />
<param index="0" name="x" type="Variant" />
<description>
Returns the absolute value of a [Variant] parameter [param x] (i.e. non-negative value). Supported types: [int], [float], [Vector2], [Vector2i], [Vector3], [Vector3i], [Vector4], [Vector4i].
[codeblock]
var a = abs(-1)
# a is 1
var b = abs(-1.2)
# b is 1.2
var c = abs(Vector2(-3.5, -4))
# c is (3.5, 4)
var d = abs(Vector2i(-5, -6))
# d is (5, 6)
var e = abs(Vector3(-7, 8.5, -3.8))
# e is (7, 8.5, 3.8)
var f = abs(Vector3i(-7, -8, -9))
# f is (7, 8, 9)
[/codeblock]
[b]Note:[/b] For better type safety, use [method absf], [method absi], [method Vector2.abs], [method Vector2i.abs], [method Vector3.abs], [method Vector3i.abs], [method Vector4.abs], or [method Vector4i.abs].
</description>
</method>
<method name="absf">
<return type="float" />
<param index="0" name="x" type="float" />
<description>
Returns the absolute value of float parameter [param x] (i.e. positive value).
[codeblock]
# a is 1.2
var a = absf(-1.2)
[/codeblock]
</description>
</method>
<method name="absi">
<return type="int" />
<param index="0" name="x" type="int" />
<description>
Returns the absolute value of int parameter [param x] (i.e. positive value).
[codeblock]
# a is 1
var a = absi(-1)
[/codeblock]
</description>
</method>
<method name="acos">
<return type="float" />
<param index="0" name="x" type="float" />
<description>
Returns the arc cosine of [param x] in radians. Use to get the angle of cosine [param x]. [param x] will be clamped between [code]-1.0[/code] and [code]1.0[/code] (inclusive), in order to prevent [method acos] from returning [constant @GDScript.NAN].
[codeblock]
# c is 0.523599 or 30 degrees if converted with rad_to_deg(c)
var c = acos(0.866025)
[/codeblock]
</description>
</method>
<method name="asin">
<return type="float" />
<param index="0" name="x" type="float" />
<description>
Returns the arc sine of [param x] in radians. Use to get the angle of sine [param x]. [param x] will be clamped between [code]-1.0[/code] and [code]1.0[/code] (inclusive), in order to prevent [method asin] from returning [constant @GDScript.NAN].
[codeblock]
# s is 0.523599 or 30 degrees if converted with rad_to_deg(s)
var s = asin(0.5)
[/codeblock]
</description>
</method>
<method name="atan">
<return type="float" />
<param index="0" name="x" type="float" />
<description>
Returns the arc tangent of [param x] in radians. Use it to get the angle from an angle's tangent in trigonometry.
The method cannot know in which quadrant the angle should fall. See [method atan2] if you have both [code]y[/code] and [code]x[/code].
[codeblock]
var a = atan(0.5) # a is 0.463648
[/codeblock]
If [param x] is between [code]-PI / 2[/code] and [code]PI / 2[/code] (inclusive), [code]atan(tan(x))[/code] is equal to [param x].
</description>
</method>
<method name="atan2">
<return type="float" />
<param index="0" name="y" type="float" />
<param index="1" name="x" type="float" />
<description>
Returns the arc tangent of [code]y/x[/code] in radians. Use to get the angle of tangent [code]y/x[/code]. To compute the value, the method takes into account the sign of both arguments in order to determine the quadrant.
Important note: The Y coordinate comes first, by convention.
[codeblock]
var a = atan2(0, -1) # a is 3.141593
[/codeblock]
</description>
</method>
<method name="bezier_derivative">
<return type="float" />
<param index="0" name="start" type="float" />
<param index="1" name="control_1" type="float" />
<param index="2" name="control_2" type="float" />
<param index="3" name="end" type="float" />
<param index="4" name="t" type="float" />
<description>
Returns the derivative at the given [param t] on a one-dimensional [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bézier curve[/url] defined by the given [param control_1], [param control_2], and [param end] points.
</description>
</method>
<method name="bezier_interpolate">
<return type="float" />
<param index="0" name="start" type="float" />
<param index="1" name="control_1" type="float" />
<param index="2" name="control_2" type="float" />
<param index="3" name="end" type="float" />
<param index="4" name="t" type="float" />
<description>
Returns the point at the given [param t] on a one-dimensional [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bézier curve[/url] defined by the given [param control_1], [param control_2], and [param end] points.
</description>
</method>
<method name="bytes_to_var">
<return type="Variant" />
<param index="0" name="bytes" type="PackedByteArray" />
<description>
Decodes a byte array back to a [Variant] value, without decoding objects.
[b]Note:[/b] If you need object deserialization, see [method bytes_to_var_with_objects].
</description>
</method>
<method name="bytes_to_var_with_objects">
<return type="Variant" />
<param index="0" name="bytes" type="PackedByteArray" />
<description>
Decodes a byte array back to a [Variant] value. Decoding objects is allowed.
[b]Warning:[/b] Deserialized object can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats (remote code execution).
</description>
</method>
<method name="ceil">
<return type="Variant" />
<param index="0" name="x" type="Variant" />
<description>
Rounds [param x] upward (towards positive infinity), returning the smallest whole number that is not less than [param x]. Supported types: [int], [float], [Vector2], [Vector3], [Vector4].
[codeblock]
var i = ceil(1.45) # i is 2.0
i = ceil(1.001) # i is 2.0
[/codeblock]
See also [method floor], [method round], and [method snapped].
[b]Note:[/b] For better type safety, use [method ceilf], [method ceili], [method Vector2.ceil], [method Vector3.ceil], or [method Vector4.ceil].
</description>
</method>
<method name="ceilf">
<return type="float" />
<param index="0" name="x" type="float" />
<description>
Rounds [param x] upward (towards positive infinity), returning the smallest whole number that is not less than [param x].
A type-safe version of [method ceil], returning a [float].
</description>
</method>
<method name="ceili">
<return type="int" />
<param index="0" name="x" type="float" />
<description>
Rounds [param x] upward (towards positive infinity), returning the smallest whole number that is not less than [param x].
A type-safe version of [method ceil], returning an [int].
</description>
</method>
<method name="clamp">
<return type="Variant" />
<param index="0" name="value" type="Variant" />
<param index="1" name="min" type="Variant" />
<param index="2" name="max" type="Variant" />
<description>
Clamps the [param value], returning a [Variant] not less than [param min] and not more than [param max]. Any values that can be compared with the less than and greater than operators will work.
[codeblock]
var a = clamp(-10, -1, 5)
# a is -1
var b = clamp(8.1, 0.9, 5.5)
# b is 5.5
var c = clamp(Vector2(-3.5, -4), Vector2(-3.2, -2), Vector2(2, 6.5))
# c is (-3.2, -2)
var d = clamp(Vector2i(7, 8), Vector2i(-3, -2), Vector2i(2, 6))
# d is (2, 6)
var e = clamp(Vector3(-7, 8.5, -3.8), Vector3(-3, -2, 5.4), Vector3(-2, 6, -4.1))
# e is (-3, -2, 5.4)
var f = clamp(Vector3i(-7, -8, -9), Vector3i(-1, 2, 3), Vector3i(-4, -5, -6))
# f is (-4, -5, -6)
[/codeblock]
[b]Note:[/b] For better type safety, use [method clampf], [method clampi], [method Vector2.clamp], [method Vector2i.clamp], [method Vector3.clamp], [method Vector3i.clamp], [method Vector4.clamp], [method Vector4i.clamp], or [method Color.clamp].
</description>
</method>
<method name="clampf">
<return type="float" />
<param index="0" name="value" type="float" />
<param index="1" name="min" type="float" />
<param index="2" name="max" type="float" />
<description>
Clamps the [param value], returning a [float] not less than [param min] and not more than [param max].
[codeblock]
var speed = 42.1
var a = clampf(speed, 1.0, 20.5) # a is 20.5
speed = -10.0
var b = clampf(speed, -1.0, 1.0) # b is -1.0
[/codeblock]
</description>
</method>
<method name="clampi">
<return type="int" />
<param index="0" name="value" type="int" />
<param index="1" name="min" type="int" />
<param index="2" name="max" type="int" />
<description>
Clamps the [param value], returning an [int] not less than [param min] and not more than [param max].
[codeblock]
var speed = 42
var a = clampi(speed, 1, 20) # a is 20
speed = -10
var b = clampi(speed, -1, 1) # b is -1
[/codeblock]
</description>
</method>
<method name="cos">
<return type="float" />
<param index="0" name="angle_rad" type="float" />
<description>
Returns the cosine of angle [param angle_rad] in radians.
[codeblock]
cos(PI * 2) # Returns 1.0
cos(PI) # Returns -1.0
cos(deg_to_rad(90)) # Returns 0.0
[/codeblock]
</description>
</method>
<method name="cosh">
<return type="float" />
<param index="0" name="x" type="float" />
<description>
Returns the hyperbolic cosine of [param x] in radians.
[codeblock]
print(cosh(1)) # Prints 1.543081
[/codeblock]
</description>
</method>
<method name="cubic_interpolate">
<return type="float" />
<param index="0" name="from" type="float" />
<param index="1" name="to" type="float" />
<param index="2" name="pre" type="float" />
<param index="3" name="post" type="float" />
<param index="4" name="weight" type="float" />
<description>
Cubic interpolates between two values by the factor defined in [param weight] with [param pre] and [param post] values.
</description>
</method>
<method name="cubic_interpolate_angle">
<return type="float" />
<param index="0" name="from" type="float" />
<param index="1" name="to" type="float" />
<param index="2" name="pre" type="float" />
<param index="3" name="post" type="float" />
<param index="4" name="weight" type="float" />
<description>
Cubic interpolates between two rotation values with shortest path by the factor defined in [param weight] with [param pre] and [param post] values. See also [method lerp_angle].
</description>
</method>
<method name="cubic_interpolate_angle_in_time">
<return type="float" />
<param index="0" name="from" type="float" />
<param index="1" name="to" type="float" />
<param index="2" name="pre" type="float" />
<param index="3" name="post" type="float" />
<param index="4" name="weight" type="float" />
<param index="5" name="to_t" type="float" />
<param index="6" name="pre_t" type="float" />
<param index="7" name="post_t" type="float" />
<description>
Cubic interpolates between two rotation values with shortest path by the factor defined in [param weight] with [param pre] and [param post] values. See also [method lerp_angle].
It can perform smoother interpolation than [code]cubic_interpolate()[/code] by the time values.
</description>
</method>
<method name="cubic_interpolate_in_time">
<return type="float" />
<param index="0" name="from" type="float" />
<param index="1" name="to" type="float" />
<param index="2" name="pre" type="float" />
<param index="3" name="post" type="float" />
<param index="4" name="weight" type="float" />
<param index="5" name="to_t" type="float" />
<param index="6" name="pre_t" type="float" />
<param index="7" name="post_t" type="float" />
<description>
Cubic interpolates between two values by the factor defined in [param weight] with [param pre] and [param post] values.
It can perform smoother interpolation than [method cubic_interpolate] by the time values.
</description>
</method>
<method name="db_to_linear">
<return type="float" />
<param index="0" name="db" type="float" />
<description>
Converts from decibels to linear energy (audio).
</description>
</method>
<method name="deg_to_rad">
<return type="float" />
<param index="0" name="deg" type="float" />
<description>
Converts an angle expressed in degrees to radians.
[codeblock]
var r = deg_to_rad(180) # r is 3.141593
[/codeblock]
</description>
</method>
<method name="ease">
<return type="float" />
<param index="0" name="x" type="float" />
<param index="1" name="curve" type="float" />
<description>
Returns an "eased" value of [param x] based on an easing function defined with [param curve]. This easing function is based on an exponent. The [param curve] can be any floating-point number, with specific values leading to the following behaviors:
[codeblock]
- Lower than -1.0 (exclusive): Ease in-out
- 1.0: Linear
- Between -1.0 and 0.0 (exclusive): Ease out-in
- 0.0: Constant
- Between 0.0 to 1.0 (exclusive): Ease out
- 1.0: Linear
- Greater than 1.0 (exclusive): Ease in
[/codeblock]
[url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/ease_cheatsheet.png]ease() curve values cheatsheet[/url]
See also [method smoothstep]. If you need to perform more advanced transitions, use [method Tween.interpolate_value].
</description>
</method>
<method name="error_string">
<return type="String" />
<param index="0" name="error" type="int" />
<description>
Returns a human-readable name for the given [enum Error] code.
[codeblock]
print(OK) # Prints 0
print(error_string(OK)) # Prints OK
print(error_string(ERR_BUSY)) # Prints Busy
print(error_string(ERR_OUT_OF_MEMORY)) # Prints Out of memory
[/codeblock]
</description>
</method>
<method name="exp">
<return type="float" />
<param index="0" name="x" type="float" />
<description>
The natural exponential function. It raises the mathematical constant [i]e[/i] to the power of [param x] and returns it.
[i]e[/i] has an approximate value of 2.71828, and can be obtained with [code]exp(1)[/code].
For exponents to other bases use the method [method pow].
[codeblock]
var a = exp(2) # Approximately 7.39
[/codeblock]
</description>
</method>
<method name="floor">
<return type="Variant" />
<param index="0" name="x" type="Variant" />
<description>
Rounds [param x] downward (towards negative infinity), returning the largest whole number that is not more than [param x]. Supported types: [int], [float], [Vector2], [Vector3], [Vector4].
[codeblock]
var a = floor(2.99) # a is 2.0
a = floor(-2.99) # a is -3.0
[/codeblock]
See also [method ceil], [method round], and [method snapped].
[b]Note:[/b] For better type safety, use [method floorf], [method floori], [method Vector2.floor], [method Vector3.floor], or [method Vector4.floor].
</description>
</method>
<method name="floorf">
<return type="float" />
<param index="0" name="x" type="float" />
<description>
Rounds [param x] downward (towards negative infinity), returning the largest whole number that is not more than [param x].
A type-safe version of [method floor], returning a [float].
</description>
</method>
<method name="floori">
<return type="int" />
<param index="0" name="x" type="float" />
<description>
Rounds [param x] downward (towards negative infinity), returning the largest whole number that is not more than [param x].
A type-safe version of [method floor], returning an [int].
[b]Note:[/b] This function is [i]not[/i] the same as [code]int(x)[/code], which rounds towards 0.
</description>
</method>
<method name="fmod">
<return type="float" />
<param index="0" name="x" type="float" />
<param index="1" name="y" type="float" />
<description>
Returns the floating-point remainder of [param x] divided by [param y], keeping the sign of [param x].
[codeblock]
var remainder = fmod(7, 5.5) # remainder is 1.5
[/codeblock]
For the integer remainder operation, use the [code]%[/code] operator.
</description>
</method>
<method name="fposmod">
<return type="float" />
<param index="0" name="x" type="float" />
<param index="1" name="y" type="float" />
<description>
Returns the floating-point modulus of [param x] divided by [param y], wrapping equally in positive and negative.
[codeblock]
print(" (x) (fmod(x, 1.5)) (fposmod(x, 1.5))")
for i in 7:
var x = i * 0.5 - 1.5
print("%4.1f %4.1f | %4.1f" % [x, fmod(x, 1.5), fposmod(x, 1.5)])
[/codeblock]
Produces:
[codeblock]
(x) (fmod(x, 1.5)) (fposmod(x, 1.5))
-1.5 -0.0 | 0.0
-1.0 -1.0 | 0.5
-0.5 -0.5 | 1.0
0.0 0.0 | 0.0
0.5 0.5 | 0.5
1.0 1.0 | 1.0
1.5 0.0 | 0.0
[/codeblock]
</description>
</method>
<method name="hash">
<return type="int" />
<param index="0" name="variable" type="Variant" />
<description>
Returns the integer hash of the passed [param variable].
[codeblocks]
[gdscript]
print(hash("a")) # Prints 177670
[/gdscript]
[csharp]
GD.Print(GD.Hash("a")); // Prints 177670
[/csharp]
[/codeblocks]
</description>
</method>
<method name="instance_from_id">
<return type="Object" />
<param index="0" name="instance_id" type="int" />
<description>
Returns the [Object] that corresponds to [param instance_id]. All Objects have a unique instance ID. See also [method Object.get_instance_id].
[codeblocks]
[gdscript]
var foo = "bar"
func _ready():
var id = get_instance_id()
var inst = instance_from_id(id)
print(inst.foo) # Prints bar
[/gdscript]
[csharp]
public partial class MyNode : Node
{
public string Foo { get; set; } = "bar";
public override void _Ready()
{
ulong id = GetInstanceId();
var inst = (MyNode)InstanceFromId(Id);
GD.Print(inst.Foo); // Prints bar
}
}
[/csharp]
[/codeblocks]
</description>
</method>
<method name="inverse_lerp">
<return type="float" />
<param index="0" name="from" type="float" />
<param index="1" name="to" type="float" />
<param index="2" name="weight" type="float" />
<description>
Returns an interpolation or extrapolation factor considering the range specified in [param from] and [param to], and the interpolated value specified in [param weight]. The returned value will be between [code]0.0[/code] and [code]1.0[/code] if [param weight] is between [param from] and [param to] (inclusive). If [param weight] is located outside this range, then an extrapolation factor will be returned (return value lower than [code]0.0[/code] or greater than [code]1.0[/code]). Use [method clamp] on the result of [method inverse_lerp] if this is not desired.
[codeblock]
# The interpolation ratio in the `lerp()` call below is 0.75.
var middle = lerp(20, 30, 0.75)
# middle is now 27.5.
# Now, we pretend to have forgotten the original ratio and want to get it back.
var ratio = inverse_lerp(20, 30, 27.5)
# ratio is now 0.75.
[/codeblock]
See also [method lerp], which performs the reverse of this operation, and [method remap] to map a continuous series of values to another.
</description>
</method>
<method name="is_equal_approx">
<return type="bool" />
<param index="0" name="a" type="float" />
<param index="1" name="b" type="float" />
<description>
Returns [code]true[/code] if [param a] and [param b] are approximately equal to each other.
Here, "approximately equal" means that [param a] and [param b] are within a small internal epsilon of each other, which scales with the magnitude of the numbers.
Infinity values of the same sign are considered equal.
</description>
</method>
<method name="is_finite">
<return type="bool" />
<param index="0" name="x" type="float" />
<description>
Returns whether [param x] is a finite value, i.e. it is not [constant @GDScript.NAN], positive infinity, or negative infinity.
</description>
</method>
<method name="is_inf">
<return type="bool" />
<param index="0" name="x" type="float" />
<description>
Returns [code]true[/code] if [param x] is either positive infinity or negative infinity.
</description>
</method>
<method name="is_instance_id_valid">
<return type="bool" />
<param index="0" name="id" type="int" />
<description>
Returns [code]true[/code] if the Object that corresponds to [param id] is a valid object (e.g. has not been deleted from memory). All Objects have a unique instance ID.
</description>
</method>
<method name="is_instance_valid">
<return type="bool" />
<param index="0" name="instance" type="Variant" />
<description>
Returns [code]true[/code] if [param instance] is a valid Object (e.g. has not been deleted from memory).
</description>
</method>
<method name="is_nan">
<return type="bool" />
<param index="0" name="x" type="float" />
<description>
Returns [code]true[/code] if [param x] is a NaN ("Not a Number" or invalid) value.
</description>
</method>
<method name="is_same">
<return type="bool" />
<param index="0" name="a" type="Variant" />
<param index="1" name="b" type="Variant" />
<description>
Returns [code]true[/code], for value types, if [param a] and [param b] share the same value. Returns [code]true[/code], for reference types, if the references of [param a] and [param b] are the same.
[codeblock]
# Vector2 is a value type
var vec2_a = Vector2(0, 0)
var vec2_b = Vector2(0, 0)
var vec2_c = Vector2(1, 1)
is_same(vec2_a, vec2_a) # true
is_same(vec2_a, vec2_b) # true
is_same(vec2_a, vec2_c) # false
# Array is a reference type
var arr_a = []
var arr_b = []
is_same(arr_a, arr_a) # true
is_same(arr_a, arr_b) # false
[/codeblock]
These are [Variant] value types: [code]null[/code], [bool], [int], [float], [String], [StringName], [Vector2], [Vector2i], [Vector3], [Vector3i], [Vector4], [Vector4i], [Rect2], [Rect2i], [Transform2D], [Transform3D], [Plane], [Quaternion], [AABB], [Basis], [Projection], [Color], [NodePath], [RID], [Callable] and [Signal].
These are [Variant] reference types: [Object], [Dictionary], [Array], [PackedByteArray], [PackedInt32Array], [PackedInt64Array], [PackedFloat32Array], [PackedFloat64Array], [PackedStringArray], [PackedVector2Array], [PackedVector3Array] and [PackedColorArray].
</description>
</method>
<method name="is_zero_approx">
<return type="bool" />
<param index="0" name="x" type="float" />
<description>
Returns [code]true[/code] if [param x] is zero or almost zero. The comparison is done using a tolerance calculation with a small internal epsilon.
This function is faster than using [method is_equal_approx] with one value as zero.
</description>
</method>
<method name="lerp">
<return type="Variant" />
<param index="0" name="from" type="Variant" />
<param index="1" name="to" type="Variant" />
<param index="2" name="weight" type="Variant" />
<description>
Linearly interpolates between two values by the factor defined in [param weight]. To perform interpolation, [param weight] should be between [code]0.0[/code] and [code]1.0[/code] (inclusive). However, values outside this range are allowed and can be used to perform [i]extrapolation[/i]. If this is not desired, use [method clamp] on the result of this function.
Both [param from] and [param to] must be the same type. Supported types: [int], [float], [Vector2], [Vector3], [Vector4], [Color], [Quaternion], [Basis].
[codeblock]
lerp(0, 4, 0.75) # Returns 3.0
[/codeblock]
See also [method inverse_lerp] which performs the reverse of this operation. To perform eased interpolation with [method lerp], combine it with [method ease] or [method smoothstep]. See also [method remap] to map a continuous series of values to another.
[b]Note:[/b] For better type safety, use [method lerpf], [method Vector2.lerp], [method Vector3.lerp], [method Vector4.lerp], [method Color.lerp], [method Quaternion.slerp] or [method Basis.slerp].
</description>
</method>
<method name="lerp_angle">
<return type="float" />
<param index="0" name="from" type="float" />
<param index="1" name="to" type="float" />
<param index="2" name="weight" type="float" />
<description>
Linearly interpolates between two angles (in radians) by a [param weight] value between 0.0 and 1.0.
Similar to [method lerp], but interpolates correctly when the angles wrap around [constant @GDScript.TAU]. To perform eased interpolation with [method lerp_angle], combine it with [method ease] or [method smoothstep].
[codeblock]
extends Sprite
var elapsed = 0.0
func _process(delta):
var min_angle = deg_to_rad(0.0)
var max_angle = deg_to_rad(90.0)
rotation = lerp_angle(min_angle, max_angle, elapsed)
elapsed += delta
[/codeblock]
[b]Note:[/b] This function lerps through the shortest path between [param from] and [param to]. However, when these two angles are approximately [code]PI + k * TAU[/code] apart for any integer [code]k[/code], it's not obvious which way they lerp due to floating-point precision errors. For example, [code]lerp_angle(0, PI, weight)[/code] lerps counter-clockwise, while [code]lerp_angle(0, PI + 5 * TAU, weight)[/code] lerps clockwise.
</description>
</method>
<method name="lerpf">
<return type="float" />
<param index="0" name="from" type="float" />
<param index="1" name="to" type="float" />
<param index="2" name="weight" type="float" />
<description>
Linearly interpolates between two values by the factor defined in [param weight]. To perform interpolation, [param weight] should be between [code]0.0[/code] and [code]1.0[/code] (inclusive). However, values outside this range are allowed and can be used to perform [i]extrapolation[/i]. If this is not desired, use [method clampf] on the result of this function.
[codeblock]
lerpf(0, 4, 0.75) # Returns 3.0
[/codeblock]
See also [method inverse_lerp] which performs the reverse of this operation. To perform eased interpolation with [method lerp], combine it with [method ease] or [method smoothstep].
</description>
</method>
<method name="linear_to_db">
<return type="float" />
<param index="0" name="lin" type="float" />
<description>
Converts from linear energy to decibels (audio). This can be used to implement volume sliders that behave as expected (since volume isn't linear).
[b]Example:[/b]
[codeblock]
# "Slider" refers to a node that inherits Range such as HSlider or VSlider.
# Its range must be configured to go from 0 to 1.
# Change the bus name if you'd like to change the volume of a specific bus only.
AudioServer.set_bus_volume_db(AudioServer.get_bus_index("Master"), linear_to_db($Slider.value))
[/codeblock]
</description>
</method>
<method name="log">
<return type="float" />
<param index="0" name="x" type="float" />
<description>
Returns the [url=https://en.wikipedia.org/wiki/Natural_logarithm]natural logarithm[/url] of [param x] (base [url=https://en.wikipedia.org/wiki/E_(mathematical_constant)][i]e[/i][/url], with [i]e[/i] being approximately 2.71828). This is the amount of time needed to reach a certain level of continuous growth.
[b]Note:[/b] This is not the same as the "log" function on most calculators, which uses a base 10 logarithm. To use base 10 logarithm, use [code]log(x) / log(10)[/code].
[codeblock]
log(10) # Returns 2.302585
[/codeblock]
[b]Note:[/b] The logarithm of [code]0[/code] returns [code]-inf[/code], while negative values return [code]-nan[/code].
</description>
</method>
<method name="max" qualifiers="vararg">
<return type="Variant" />
<description>
Returns the maximum of the given numeric values. This function can take any number of arguments.
[codeblock]
max(1, 7, 3, -6, 5) # Returns 7
[/codeblock]
</description>
</method>
<method name="maxf">
<return type="float" />
<param index="0" name="a" type="float" />
<param index="1" name="b" type="float" />
<description>
Returns the maximum of two [float] values.
[codeblock]
maxf(3.6, 24) # Returns 24.0
maxf(-3.99, -4) # Returns -3.99
[/codeblock]
</description>
</method>
<method name="maxi">
<return type="int" />
<param index="0" name="a" type="int" />
<param index="1" name="b" type="int" />
<description>
Returns the maximum of two [int] values.
[codeblock]
maxi(1, 2) # Returns 2
maxi(-3, -4) # Returns -3
[/codeblock]
</description>
</method>
<method name="min" qualifiers="vararg">
<return type="Variant" />
<description>
Returns the minimum of the given numeric values. This function can take any number of arguments.
[codeblock]
min(1, 7, 3, -6, 5) # Returns -6
[/codeblock]
</description>
</method>
<method name="minf">
<return type="float" />
<param index="0" name="a" type="float" />
<param index="1" name="b" type="float" />
<description>
Returns the minimum of two [float] values.
[codeblock]
minf(3.6, 24) # Returns 3.6
minf(-3.99, -4) # Returns -4.0
[/codeblock]
</description>
</method>
<method name="mini">
<return type="int" />
<param index="0" name="a" type="int" />
<param index="1" name="b" type="int" />
<description>
Returns the minimum of two [int] values.
[codeblock]
mini(1, 2) # Returns 1
mini(-3, -4) # Returns -4
[/codeblock]
</description>
</method>
<method name="move_toward">
<return type="float" />
<param index="0" name="from" type="float" />
<param index="1" name="to" type="float" />
<param index="2" name="delta" type="float" />
<description>
Moves [param from] toward [param to] by the [param delta] amount. Will not go past [param to].
Use a negative [param delta] value to move away.
[codeblock]
move_toward(5, 10, 4) # Returns 9
move_toward(10, 5, 4) # Returns 6
move_toward(5, 10, 9) # Returns 10
move_toward(10, 5, -1.5) # Returns 11.5
[/codeblock]
</description>
</method>
<method name="nearest_po2">
<return type="int" />
<param index="0" name="value" type="int" />
<description>
Returns the smallest integer power of 2 that is greater than or equal to [param value].
[codeblock]
nearest_po2(3) # Returns 4
nearest_po2(4) # Returns 4
nearest_po2(5) # Returns 8
nearest_po2(0) # Returns 0 (this may not be expected)
nearest_po2(-1) # Returns 0 (this may not be expected)
[/codeblock]
[b]Warning:[/b] Due to its implementation, this method returns [code]0[/code] rather than [code]1[/code] for values less than or equal to [code]0[/code], with an exception for [param value] being the smallest negative 64-bit integer ([code]-9223372036854775808[/code]) in which case the [param value] is returned unchanged.
</description>
</method>
<method name="pingpong">
<return type="float" />
<param index="0" name="value" type="float" />
<param index="1" name="length" type="float" />
<description>
Wraps [param value] between [code]0[/code] and the [param length]. If the limit is reached, the next value the function returns is decreased to the [code]0[/code] side or increased to the [param length] side (like a triangle wave). If [param length] is less than zero, it becomes positive.
[codeblock]
pingpong(-3.0, 3.0) # Returns 3.0
pingpong(-2.0, 3.0) # Returns 2.0
pingpong(-1.0, 3.0) # Returns 1.0
pingpong(0.0, 3.0) # Returns 0.0
pingpong(1.0, 3.0) # Returns 1.0
pingpong(2.0, 3.0) # Returns 2.0
pingpong(3.0, 3.0) # Returns 3.0
pingpong(4.0, 3.0) # Returns 2.0
pingpong(5.0, 3.0) # Returns 1.0
pingpong(6.0, 3.0) # Returns 0.0
[/codeblock]
</description>
</method>
<method name="posmod">
<return type="int" />
<param index="0" name="x" type="int" />
<param index="1" name="y" type="int" />
<description>
Returns the integer modulus of [param x] divided by [param y] that wraps equally in positive and negative.
[codeblock]
print("#(i) (i % 3) (posmod(i, 3))")
for i in range(-3, 4):
print("%2d %2d | %2d" % [i, i % 3, posmod(i, 3)])
[/codeblock]
Produces:
[codeblock]
(i) (i % 3) (posmod(i, 3))
-3 0 | 0
-2 -2 | 1
-1 -1 | 2
0 0 | 0
1 1 | 1
2 2 | 2
3 0 | 0
[/codeblock]
</description>
</method>
<method name="pow">
<return type="float" />
<param index="0" name="base" type="float" />
<param index="1" name="exp" type="float" />
<description>
Returns the result of [param base] raised to the power of [param exp].
In GDScript, this is the equivalent of the [code]**[/code] operator.
[codeblock]
pow(2, 5) # Returns 32.0
pow(4, 1.5) # Returns 8.0
[/codeblock]
</description>
</method>
<method name="print" qualifiers="vararg">
<description>
Converts one or more arguments of any type to string in the best way possible and prints them to the console.
[codeblocks]
[gdscript]
var a = [1, 2, 3]
print("a", "b", a) # Prints ab[1, 2, 3]
[/gdscript]
[csharp]
var a = new Godot.Collections.Array { 1, 2, 3 };
GD.Print("a", "b", a); // Prints ab[1, 2, 3]
[/csharp]
[/codeblocks]
[b]Note:[/b] Consider using [method push_error] and [method push_warning] to print error and warning messages instead of [method print] or [method print_rich]. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed.
</description>
</method>
<method name="print_rich" qualifiers="vararg">
<description>
Converts one or more arguments of any type to string in the best way possible and prints them to the console.
The following BBCode tags are supported: [code]b[/code], [code]i[/code], [code]u[/code], [code]s[/code], [code]indent[/code], [code]code[/code], [code]url[/code], [code]center[/code], [code]right[/code], [code]color[/code], [code]bgcolor[/code], [code]fgcolor[/code].
Color tags only support the following named colors: [code]black[/code], [code]red[/code], [code]green[/code], [code]yellow[/code], [code]blue[/code], [code]magenta[/code], [code]pink[/code], [code]purple[/code], [code]cyan[/code], [code]white[/code], [code]orange[/code], [code]gray[/code]. Hexadecimal color codes are not supported.
URL tags only support URLs wrapped by a URL tag, not URLs with a different title.
When printing to standard output, the supported subset of BBCode is converted to ANSI escape codes for the terminal emulator to display. Support for ANSI escape codes varies across terminal emulators, especially for italic and strikethrough. In standard output, [code]code[/code] is represented with faint text but without any font change. Unsupported tags are left as-is in standard output.
[codeblocks]
[gdscript]
print_rich("[color=green][b]Hello world![/b][/color]") # Prints out "Hello world!" in green with a bold font
[/gdscript]
[csharp]
GD.PrintRich("[color=green][b]Hello world![/b][/color]"); // Prints out "Hello world!" in green with a bold font
[/csharp]
[/codeblocks]
[b]Note:[/b] Consider using [method push_error] and [method push_warning] to print error and warning messages instead of [method print] or [method print_rich]. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed.
[b]Note:[/b] On Windows, only Windows 10 and later correctly displays ANSI escape codes in standard output.
</description>
</method>
<method name="print_verbose" qualifiers="vararg">
<description>
If verbose mode is enabled ([method OS.is_stdout_verbose] returning [code]true[/code]), converts one or more arguments of any type to string in the best way possible and prints them to the console.
</description>
</method>
<method name="printerr" qualifiers="vararg">
<description>
Prints one or more arguments to strings in the best way possible to standard error line.
[codeblocks]
[gdscript]
printerr("prints to stderr")
[/gdscript]
[csharp]
GD.PrintErr("prints to stderr");
[/csharp]
[/codeblocks]
</description>
</method>
<method name="printraw" qualifiers="vararg">
<description>
Prints one or more arguments to strings in the best way possible to the OS terminal. Unlike [method print], no newline is automatically added at the end.
[codeblocks]
[gdscript]
printraw("A")
printraw("B")
printraw("C")
# Prints ABC to terminal
[/gdscript]
[csharp]
GD.PrintRaw("A");
GD.PrintRaw("B");
GD.PrintRaw("C");
// Prints ABC to terminal
[/csharp]
[/codeblocks]
</description>
</method>
<method name="prints" qualifiers="vararg">
<description>
Prints one or more arguments to the console with a space between each argument.
[codeblocks]
[gdscript]
prints("A", "B", "C") # Prints A B C
[/gdscript]
[csharp]
GD.PrintS("A", "B", "C"); // Prints A B C
[/csharp]
[/codeblocks]
</description>
</method>
<method name="printt" qualifiers="vararg">
<description>
Prints one or more arguments to the console with a tab between each argument.
[codeblocks]
[gdscript]
printt("A", "B", "C") # Prints A B C
[/gdscript]
[csharp]
GD.PrintT("A", "B", "C"); // Prints A B C
[/csharp]
[/codeblocks]
</description>
</method>
<method name="push_error" qualifiers="vararg">
<description>
Pushes an error message to Godot's built-in debugger and to the OS terminal.
[codeblocks]
[gdscript]
push_error("test error") # Prints "test error" to debugger and terminal as error call
[/gdscript]
[csharp]
GD.PushError("test error"); // Prints "test error" to debugger and terminal as error call
[/csharp]
[/codeblocks]
[b]Note:[/b] This function does not pause project execution. To print an error message and pause project execution in debug builds, use [code]assert(false, "test error")[/code] instead.
</description>
</method>
<method name="push_warning" qualifiers="vararg">
<description>
Pushes a warning message to Godot's built-in debugger and to the OS terminal.
[codeblocks]
[gdscript]
push_warning("test warning") # Prints "test warning" to debugger and terminal as warning call
[/gdscript]
[csharp]
GD.PushWarning("test warning"); // Prints "test warning" to debugger and terminal as warning call
[/csharp]
[/codeblocks]
</description>
</method>
<method name="rad_to_deg">
<return type="float" />
<param index="0" name="rad" type="float" />
<description>
Converts an angle expressed in radians to degrees.
[codeblock]
rad_to_deg(0.523599) # Returns 30
rad_to_deg(PI) # Returns 180
rad_to_deg(PI * 2) # Returns 360
[/codeblock]
</description>
</method>
<method name="rand_from_seed">
<return type="PackedInt64Array" />
<param index="0" name="seed" type="int" />
<description>
Given a [param seed], returns a [PackedInt64Array] of size [code]2[/code], where its first element is the randomized [int] value, and the second element is the same as [param seed]. Passing the same [param seed] consistently returns the same array.
[b]Note:[/b] "Seed" here refers to the internal state of the pseudo random number generator, currently implemented as a 64 bit integer.
[codeblock]
var a = rand_from_seed(4)
print(a[0]) # Prints 2879024997
print(a[1]) # Prints 4
[/codeblock]
</description>
</method>
<method name="randf">
<return type="float" />
<description>
Returns a random floating point value between [code]0.0[/code] and [code]1.0[/code] (inclusive).
[codeblocks]
[gdscript]
randf() # Returns e.g. 0.375671
[/gdscript]
[csharp]
GD.Randf(); // Returns e.g. 0.375671
[/csharp]
[/codeblocks]
</description>
</method>
<method name="randf_range">
<return type="float" />
<param index="0" name="from" type="float" />
<param index="1" name="to" type="float" />
<description>
Returns a random floating point value between [param from] and [param to] (inclusive).
[codeblocks]
[gdscript]
randf_range(0, 20.5) # Returns e.g. 7.45315
randf_range(-10, 10) # Returns e.g. -3.844535
[/gdscript]
[csharp]
GD.RandRange(0.0, 20.5); // Returns e.g. 7.45315
GD.RandRange(-10.0, 10.0); // Returns e.g. -3.844535
[/csharp]
[/codeblocks]
</description>
</method>
<method name="randfn">
<return type="float" />
<param index="0" name="mean" type="float" />
<param index="1" name="deviation" type="float" />
<description>
Returns a normally-distributed pseudo-random floating point value using Box-Muller transform with the specified [param mean] and a standard [param deviation]. This is also called Gaussian distribution.
</description>