@GDScript

Built-in GDScript functions.

Description

List of core built-in GDScript functions. Math functions and other utilities. Everything else is provided by objects. (Keywords: builtin, built in, global functions.)

Methods

Color

Color8 ( int r8, int g8, int b8, int a8=255 )

void

assert ( bool condition, String message="" )

String

char ( int char )

Variant

convert ( Variant what, int type )

Object

dict2inst ( Dictionary dictionary )

Array

get_stack ( )

Dictionary

inst2dict ( Object instance )

int

len ( Variant var )

Resource

load ( String path )

Resource

preload ( String path )

void

print_debug ( ... ) vararg

void

print_stack ( )

Array

range ( ... ) vararg

String

str ( ... ) vararg

bool

type_exists ( StringName type )

Constants

  • PI = 3.14159265358979 --- Constant that represents how many times the diameter of a circle fits around its perimeter. This is equivalent to TAU / 2, or 180 degrees in rotations.

  • TAU = 6.28318530717959 --- The circle constant, the circumference of the unit circle in radians. This is equivalent to PI * 2, or 360 degrees in rotations.

  • INF = inf --- Positive floating-point infinity. This is the result of floating-point division when the divisor is 0.0. For negative infinity, use -INF. Dividing by -0.0 will result in negative infinity if the numerator is positive, so dividing by 0.0 is not the same as dividing by -0.0 (despite 0.0 == -0.0 returning true).

Note: Numeric infinity is only a concept with floating-point numbers, and has no equivalent for integers. Dividing an integer number by 0 will not result in INF and will result in a run-time error instead.

  • NAN = nan --- "Not a Number", an invalid floating-point value. NAN has special properties, including that it is not equal to itself (NAN == NAN returns false). It is output by some invalid operations, such as dividing floating-point 0.0 by 0.0.

Note: "Not a Number" is only a concept with floating-point numbers, and has no equivalent for integers. Dividing an integer 0 by 0 will not result in NAN and will result in a run-time error instead.

Method Descriptions

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.

r8 red channel

g8 green channel

b8 blue channel

a8 alpha channel

red = Color8(255, 0, 0)

  • void assert ( bool condition, String message="" )

Asserts that the condition is true. If the condition is false, 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 @GlobalScope.push_error for reporting errors to project developers or add-on users.

Note: For performance reasons, the code inside 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 assert call. Otherwise, the project will behave differently when exported in release mode.

The optional message 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.

# 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

Returns a character as a String of the given Unicode code point (which is compatible with ASCII code).

a = char(65)      # a is "A"
a = char(65 + 32) # a is "a"
a = char(8364)    # a is "€"

Converts from a type to another in the best way possible. The type parameter uses the Variant.Type values.

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())

Converts a dictionary (previously created with inst2dict) back to an instance. Useful for deserializing.


Returns an array of dictionaries representing the current call stack.

func _ready():
    foo()

func foo():
    bar()

func bar():
    print(get_stack())

would print

[{function:bar, line:12, source:res://script.gd}, {function:foo, line:9, source:res://script.gd}, {function:_ready, line:6, source:res://script.gd}]

Returns the passed instance converted to a dictionary (useful for serializing).

var foo = "bar"
func _ready():
    var d = inst2dict(self)
    print(d.keys())
    print(d.values())

Prints out:

[@subpath, @path, foo]
[, res://test.gd, bar]

Returns length of Variant var. Length is the character count of String, element count of Array, size of Dictionary, etc.

Note: Generates a fatal error if Variant can not provide a length.

a = [1, 2, 3, 4]
len(a) # Returns 4

Loads a resource from the filesystem located at path. 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 preload.

Note: 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.

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

Important: The path must be absolute, a local path will just return null.

This method is a simplified version of ResourceLoader.load, which can be used for more advanced scenarios.


Returns a Resource from the filesystem located at path. The resource is loaded during script parsing, i.e. is loaded with the script and 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 load.

Note: 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.

# Instance a scene.
var diamond = preload("res://diamond.tscn").instantiate()

  • void print_debug ( ... ) vararg

Like @GlobalScope.print, but prints only when used in debug mode.


  • void print_stack ( )

Prints a stack track at code location, only works when running with debugger turned on.

Output in the console would look something like this:

Frame 0 - res://test.gd:16 in function '_process'

  • Array range ( ... ) vararg

Returns an array with the given range. Range can be 1 argument N (0 to N - 1), two arguments (initial, final - 1) or three arguments (initial, final - 1, increment). Returns an empty array if the range isn't valid (e.g. range(2, 5, -1) or range(5, 5, 1)).

Returns an array with the given range. range() can have 1 argument N (0 to N - 1), two arguments (initial, final - 1) or three arguments (initial, final - 1, increment). increment can be negative. If increment is negative, final - 1 will become final + 1. Also, the initial value must be greater than the final value for the loop to run.

print(range(4))
print(range(2, 5))
print(range(0, 6, 2))

Output:

[0, 1, 2, 3]
[2, 3, 4]
[0, 2, 4]

To iterate over an Array backwards, use:

var array = [3, 6, 9]
var i := array.size() - 1
while i >= 0:
    print(array[i])
    i -= 1

Output:

9
6
3

Converts one or more arguments to string in the best way possible.

var a = [10, 20, 30]
var b = str(a);
len(a) # Returns 3
len(b) # Returns 12