Class @GlobalScope

Global scope constants and functions.

@GlobalScope

Remarks

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 that can only be accessed from scripts written in GDScript, see @GDScript.

See Also

Random number generation

Properties

AudioServer

The AudioServer singleton.

var AudioServer : AudioServer

Property Value

AudioServer

CameraServer

The CameraServer singleton.

var CameraServer : CameraServer

Property Value

CameraServer

ClassDB

The ClassDB singleton.

var ClassDB : ClassDB

Property Value

ClassDB

DisplayServer

The DisplayServer singleton.

var DisplayServer : DisplayServer

Property Value

DisplayServer

EditorInterface

The EditorInterface singleton.

Note: Only available in editor builds.

var EditorInterface : EditorInterface

Property Value

EditorInterface

Engine

The Engine singleton.

var Engine : Engine

Property Value

Engine

EngineDebugger

The EngineDebugger singleton.

var EngineDebugger : EngineDebugger

Property Value

EngineDebugger

GDExtensionManager

The GDExtensionManager singleton.

var GDExtensionManager : GDExtensionManager

Property Value

GDExtensionManager

Geometry2D

The Geometry2D singleton.

var Geometry2D : Geometry2D

Property Value

Geometry2D

Geometry3D

The Geometry3D singleton.

var Geometry3D : Geometry3D

Property Value

Geometry3D

IP

The IP singleton.

var IP : IP

Property Value

IP

Input

The Input singleton.

var Input : Input

Property Value

Input

InputMap

The InputMap singleton.

var InputMap : InputMap

Property Value

InputMap

JavaClassWrapper

The JavaClassWrapper singleton.

Note: Only implemented on Android.

var JavaClassWrapper : JavaClassWrapper

Property Value

JavaClassWrapper

JavaScriptBridge

The JavaScriptBridge singleton.

Note: Only implemented on the Web platform.

var JavaScriptBridge : JavaScriptBridge

Property Value

JavaScriptBridge

Marshalls

The Marshalls singleton.

var Marshalls : Marshalls

Property Value

Marshalls

NativeMenu

The NativeMenu singleton.

Note: Only implemented on macOS.

var NativeMenu : NativeMenu

Property Value

NativeMenu

NavigationMeshGenerator

The NavigationMeshGenerator singleton.

var NavigationMeshGenerator : NavigationMeshGenerator

Property Value

NavigationMeshGenerator

NavigationServer2D

The NavigationServer2D singleton.

var NavigationServer2D : NavigationServer2D

Property Value

NavigationServer2D

NavigationServer3D

The NavigationServer3D singleton.

var NavigationServer3D : NavigationServer3D

Property Value

NavigationServer3D

OS

The OS singleton.

var OS : OS

Property Value

OS

Performance

The Performance singleton.

var Performance : Performance

Property Value

Performance

PhysicsServer2D

The PhysicsServer2D singleton.

var PhysicsServer2D : PhysicsServer2D

Property Value

PhysicsServer2D

PhysicsServer2DManager

The PhysicsServer2DManager singleton.

var PhysicsServer2DManager : PhysicsServer2DManager

Property Value

PhysicsServer2DManager

PhysicsServer3D

The PhysicsServer3D singleton.

var PhysicsServer3D : PhysicsServer3D

Property Value

PhysicsServer3D

PhysicsServer3DManager

The PhysicsServer3DManager singleton.

var PhysicsServer3DManager : PhysicsServer3DManager

Property Value

PhysicsServer3DManager

ProjectSettings

The ProjectSettings singleton.

var ProjectSettings : ProjectSettings

Property Value

ProjectSettings

RenderingServer

The RenderingServer singleton.

var RenderingServer : RenderingServer

Property Value

RenderingServer

ResourceLoader

The ResourceLoader singleton.

var ResourceLoader : ResourceLoader

Property Value

ResourceLoader

ResourceSaver

The ResourceSaver singleton.

var ResourceSaver : ResourceSaver

Property Value

ResourceSaver

ResourceUID

The ResourceUID singleton.

var ResourceUID : ResourceUID

Property Value

ResourceUID

TextServerManager

The TextServerManager singleton.

var TextServerManager : TextServerManager

Property Value

TextServerManager

ThemeDB

The ThemeDB singleton.

var ThemeDB : ThemeDB

Property Value

ThemeDB

Time

The Time singleton.

var Time : Time

Property Value

Time

TranslationServer

The TranslationServer singleton.

var TranslationServer : TranslationServer

Property Value

TranslationServer

WorkerThreadPool

The WorkerThreadPool singleton.

var WorkerThreadPool : WorkerThreadPool

Property Value

WorkerThreadPool

XRServer

The XRServer singleton.

var XRServer : XRServer

Property Value

XRServer

Methods

abs(Variant)

Returns the absolute value of a Variant parameter x (i.e. non-negative value). Supported types: int, float, Vector2, Vector2i, Vector3, Vector3i, Vector4, Vector4i.

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)

Note: For better type safety, use @GlobalScope.absf, @GlobalScope.absi, abs, abs, abs, abs, abs, or abs.

Variant abs(Variant x)

Parameters

x Variant

absf(float)

Returns the absolute value of float parameter x (i.e. positive value).

# a is 1.2
var a = absf(-1.2)

float absf(float x)

Parameters

x float

absi(int)

Returns the absolute value of int parameter x (i.e. positive value).

# a is 1
var a = absi(-1)

int absi(int x)

Parameters

x int

acos(float)

Returns the arc cosine of x in radians. Use to get the angle of cosine x. x will be clamped between -1.0 and 1.0 (inclusive), in order to prevent @GlobalScope.acos from returning NAN.

# c is 0.523599 or 30 degrees if converted with rad_to_deg(c)
var c = acos(0.866025)

float acos(float x)

Parameters

x float

acosh(float)

Returns the hyperbolic arc (also called inverse) cosine of x, returning a value in radians. Use it to get the angle from an angle's cosine in hyperbolic space if x is larger or equal to 1. For values of x lower than 1, it will return 0, in order to prevent @GlobalScope.acosh from returning NAN.

var a = acosh(2) # Returns 1.31695789692482
cosh(a) # Returns 2

var b = acosh(-1) # Returns 0

float acosh(float x)

Parameters

x float

angle_difference(float, float)

Returns the difference between the two angles (in radians), in the range of [-PI, +PI]. When from and to are opposite, returns -PI if from is smaller than to, or PI otherwise.

float angle_difference(float from, float to)

Parameters

from float

to float

asin(float)

Returns the arc sine of x in radians. Use to get the angle of sine x. x will be clamped between -1.0 and 1.0 (inclusive), in order to prevent @GlobalScope.asin from returning NAN.

# s is 0.523599 or 30 degrees if converted with rad_to_deg(s)
var s = asin(0.5)

float asin(float x)

Parameters

x float

asinh(float)

Returns the hyperbolic arc (also called inverse) sine of x, returning a value in radians. Use it to get the angle from an angle's sine in hyperbolic space.

var a = asinh(0.9) # Returns 0.8088669356527824
sinh(a) # Returns 0.9

float asinh(float x)

Parameters

x float

atan(float)

Returns the arc tangent of 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 @GlobalScope.atan2 if you have both y and x.

var a = atan(0.5) # a is 0.463648

If x is between -PI / 2 and PI / 2 (inclusive), atan(tan(x)) is equal to x.

float atan(float x)

Parameters

x float

atan2(float, float)

Returns the arc tangent of y/x in radians. Use to get the angle of tangent y/x. 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.

var a = atan2(0, -1) # a is 3.141593

float atan2(float y, float x)

Parameters

y float

x float

atanh(float)

Returns the hyperbolic arc (also called inverse) tangent of x, returning a value in radians. Use it to get the angle from an angle's tangent in hyperbolic space if x is between -1 and 1 (non-inclusive).

In mathematics, the inverse hyperbolic tangent is only defined for -1 < x < 1 in the real set, so values equal or lower to -1 for x return negative INF and values equal or higher than 1 return positive INF in order to prevent @GlobalScope.atanh from returning NAN.

var a = atanh(0.9) # Returns 1.47221948958322
tanh(a) # Returns 0.9

var b = atanh(-2) # Returns -inf
tanh(b) # Returns -1

float atanh(float x)

Parameters

x float

bezier_derivative(float, float, float, float, float)

Returns the derivative at the given t on a one-dimensional Bézier curve defined by the given control_1, control_2, and end points.

float bezier_derivative(float start, float control_1, float control_2, float end, float t)

Parameters

start float

control_1 float

control_2 float

end float

t float

bezier_interpolate(float, float, float, float, float)

Returns the point at the given t on a one-dimensional Bézier curve defined by the given control_1, control_2, and end points.

float bezier_interpolate(float start, float control_1, float control_2, float end, float t)

Parameters

start float

control_1 float

control_2 float

end float

t float

bytes_to_var(PackedByteArray)

Decodes a byte array back to a Variant value, without decoding objects.

Note: If you need object deserialization, see @GlobalScope.bytes_to_var_with_objects.

Variant bytes_to_var(PackedByteArray bytes)

Parameters

bytes PackedByteArray

bytes_to_var_with_objects(PackedByteArray)

Decodes a byte array back to a Variant value. Decoding objects is allowed.

Warning: 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).

Variant bytes_to_var_with_objects(PackedByteArray bytes)

Parameters

bytes PackedByteArray

ceil(Variant)

Rounds x upward (towards positive infinity), returning the smallest whole number that is not less than x. Supported types: int, float, Vector2, Vector2i, Vector3, Vector3i, Vector4, Vector4i.

var i = ceil(1.45) # i is 2.0
i = ceil(1.001)    # i is 2.0

See also @GlobalScope.floor, @GlobalScope.round, and @GlobalScope.snapped.

Note: For better type safety, use @GlobalScope.ceilf, @GlobalScope.ceili, ceil, ceil, or ceil.

Variant ceil(Variant x)

Parameters

x Variant

ceilf(float)

Rounds x upward (towards positive infinity), returning the smallest whole number that is not less than x.

A type-safe version of @GlobalScope.ceil, returning a float.

float ceilf(float x)

Parameters

x float

ceili(float)

Rounds x upward (towards positive infinity), returning the smallest whole number that is not less than x.

A type-safe version of @GlobalScope.ceil, returning an int.

int ceili(float x)

Parameters

x float

clamp(Variant, Variant, Variant)

Clamps the value, returning a Variant not less than min and not more than max. Any values that can be compared with the less than and greater than operators will work.

var a = clamp(-10, -1, 5)
# a is -1

var b = clamp(8.1, 0.9, 5.5)
# b is 5.5

Note: For better type safety, use @GlobalScope.clampf, @GlobalScope.clampi, Vector2.clamp, Vector2i.clamp, Vector3.clamp, Vector3i.clamp, Vector4.clamp, Vector4i.clamp, or Color.clamp (not currently supported by this method).

Note: When using this on vectors it will not perform component-wise clamping, and will pick min if value < min or max if value > max. To perform component-wise clamping use the methods listed above.

Variant clamp(Variant value, Variant min, Variant max)

Parameters

value Variant

min Variant

max Variant

clampf(float, float, float)

Clamps the value, returning a float not less than min and not more than max.

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

float clampf(float value, float min, float max)

Parameters

value float

min float

max float

clampi(int, int, int)

Clamps the value, returning an int not less than min and not more than max.

var speed = 42
var a = clampi(speed, 1, 20) # a is 20

speed = -10
var b = clampi(speed, -1, 1) # b is -1

int clampi(int value, int min, int max)

Parameters

value int

min int

max int

cos(float)

Returns the cosine of angle angle_rad in radians.

cos(PI * 2)         # Returns 1.0
cos(PI)             # Returns -1.0
cos(deg_to_rad(90)) # Returns 0.0

float cos(float angle_rad)

Parameters

angle_rad float

cosh(float)

Returns the hyperbolic cosine of x in radians.

print(cosh(1)) # Prints 1.543081

float cosh(float x)

Parameters

x float

cubic_interpolate(float, float, float, float, float)

Cubic interpolates between two values by the factor defined in weight with pre and post values.

float cubic_interpolate(float from, float to, float pre, float post, float weight)

Parameters

from float

to float

pre float

post float

weight float

cubic_interpolate_angle(float, float, float, float, float)

Cubic interpolates between two rotation values with shortest path by the factor defined in weight with pre and post values. See also @GlobalScope.lerp_angle.

float cubic_interpolate_angle(float from, float to, float pre, float post, float weight)

Parameters

from float

to float

pre float

post float

weight float

cubic_interpolate_angle_in_time(float, float, float, float, float, float, float, float)

Cubic interpolates between two rotation values with shortest path by the factor defined in weight with pre and post values. See also @GlobalScope.lerp_angle.

It can perform smoother interpolation than @GlobalScope.cubic_interpolate by the time values.

float cubic_interpolate_angle_in_time(float from, float to, float pre, float post, float weight, float to_t, float pre_t, float post_t)

Parameters

from float

to float

pre float

post float

weight float

to_t float

pre_t float

post_t float

cubic_interpolate_in_time(float, float, float, float, float, float, float, float)

Cubic interpolates between two values by the factor defined in weight with pre and post values.

It can perform smoother interpolation than @GlobalScope.cubic_interpolate by the time values.

float cubic_interpolate_in_time(float from, float to, float pre, float post, float weight, float to_t, float pre_t, float post_t)

Parameters

from float

to float

pre float

post float

weight float

to_t float

pre_t float

post_t float

db_to_linear(float)

Converts from decibels to linear energy (audio).

float db_to_linear(float db)

Parameters

db float

deg_to_rad(float)

Converts an angle expressed in degrees to radians.

var r = deg_to_rad(180) # r is 3.141593

float deg_to_rad(float deg)

Parameters

deg float

ease(float, float)

Returns an "eased" value of x based on an easing function defined with curve. This easing function is based on an exponent. The curve can be any floating-point number, with specific values leading to the following behaviors:

• text

- 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

\ ease() curve values cheatsheet\

See also @GlobalScope.smoothstep. If you need to perform more advanced transitions, use Tween.interpolate_value.

float ease(float x, float curve)

Parameters

x float

curve float

error_string(int)

Returns a human-readable name for the given Error code.

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"

String error_string(int error)

Parameters

error int

exp(float)

The natural exponential function. It raises the mathematical constant e to the power of x and returns it.

e has an approximate value of 2.71828, and can be obtained with exp(1).

For exponents to other bases use the method @GlobalScope.pow.

var a = exp(2) # Approximately 7.39

float exp(float x)

Parameters

x float

floor(Variant)

Rounds x downward (towards negative infinity), returning the largest whole number that is not more than x. Supported types: int, float, Vector2, Vector2i, Vector3, Vector3i, Vector4, Vector4i.

var a = floor(2.99) # a is 2.0
a = floor(-2.99)    # a is -3.0

See also @GlobalScope.ceil, @GlobalScope.round, and @GlobalScope.snapped.

Note: For better type safety, use @GlobalScope.floorf, @GlobalScope.floori, floor, floor, or floor.

Variant floor(Variant x)

Parameters

x Variant

floorf(float)

Rounds x downward (towards negative infinity), returning the largest whole number that is not more than x.

A type-safe version of @GlobalScope.floor, returning a float.

float floorf(float x)

Parameters

x float

floori(float)

Rounds x downward (towards negative infinity), returning the largest whole number that is not more than x.

A type-safe version of @GlobalScope.floor, returning an int.

Note: This function is not the same as int(x), which rounds towards 0.

int floori(float x)

Parameters

x float

fmod(float, float)

Returns the floating-point remainder of x divided by y, keeping the sign of x.

var remainder = fmod(7, 5.5) # remainder is 1.5

For the integer remainder operation, use the % operator.

float fmod(float x, float y)

Parameters

x float

y float

fposmod(float, float)

Returns the floating-point modulus of x divided by y, wrapping equally in positive and negative.

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

Prints:

• text

 (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

float fposmod(float x, float y)

Parameters

x float

y float

hash(Variant)

Returns the integer hash of the passed variable.

• gdscript
• C#

print(hash("a")) # Prints 177670

int hash(Variant variable)

Parameters

variable Variant

instance_from_id(int)

Returns the Object that corresponds to instance_id. All Objects have a unique instance ID. See also get_instance_id.

• gdscript
• C#

var drink = "water"

func _ready():
    var id = get_instance_id()
    var instance = instance_from_id(id)
    print(instance.foo) # Prints "water"

Object instance_from_id(int instance_id)

Parameters

instance_id int

inverse_lerp(float, float, float)

Returns an interpolation or extrapolation factor considering the range specified in from and to, and the interpolated value specified in weight. The returned value will be between 0.0 and 1.0 if weight is between from and to (inclusive). If weight is located outside this range, then an extrapolation factor will be returned (return value lower than 0.0 or greater than 1.0). Use @GlobalScope.clamp on the result of @GlobalScope.inverse_lerp if this is not desired.

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

See also @GlobalScope.lerp, which performs the reverse of this operation, and @GlobalScope.remap to map a continuous series of values to another.

float inverse_lerp(float from, float to, float weight)

Parameters

from float

to float

weight float

is_equal_approx(float, float)

Returns true if a and b are approximately equal to each other.

Here, "approximately equal" means that a and 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.

bool is_equal_approx(float a, float b)

Parameters

a float

b float

is_finite(float)

Returns whether x is a finite value, i.e. it is not NAN, positive infinity, or negative infinity.

bool is_finite(float x)

Parameters

x float

is_inf(float)

Returns true if x is either positive infinity or negative infinity.

bool is_inf(float x)

Parameters

x float

is_instance_id_valid(int)

Returns true if the Object that corresponds to id is a valid object (e.g. has not been deleted from memory). All Objects have a unique instance ID.

bool is_instance_id_valid(int id)

Parameters

id int

is_instance_valid(Variant)

Returns true if instance is a valid Object (e.g. has not been deleted from memory).

bool is_instance_valid(Variant instance)

Parameters

instance Variant

is_nan(float)

Returns true if x is a NaN ("Not a Number" or invalid) value.

bool is_nan(float x)

Parameters

x float

is_same(Variant, Variant)

Returns true, for value types, if a and b share the same value. Returns true, for reference types, if the references of a and b are the same.

# 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

These are Variant value types: null, 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, PackedVector4Array, and PackedColorArray.

bool is_same(Variant a, Variant b)

Parameters

a Variant

b Variant

is_zero_approx(float)

Returns true if 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 @GlobalScope.is_equal_approx with one value as zero.

bool is_zero_approx(float x)

Parameters

x float

lerp(Variant, Variant, Variant)

Linearly interpolates between two values by the factor defined in weight. To perform interpolation, weight should be between 0.0 and 1.0 (inclusive). However, values outside this range are allowed and can be used to perform extrapolation. If this is not desired, use @GlobalScope.clampf to limit weight.

Both from and to must be the same type. Supported types: int, float, Vector2, Vector3, Vector4, Color, Quaternion, Basis, Transform2D, Transform3D.

lerp(0, 4, 0.75) # Returns 3.0

See also @GlobalScope.inverse_lerp which performs the reverse of this operation. To perform eased interpolation with @GlobalScope.lerp, combine it with @GlobalScope.ease or @GlobalScope.smoothstep. See also @GlobalScope.remap to map a continuous series of values to another.

Note: For better type safety, use @GlobalScope.lerpf, Vector2.lerp, Vector3.lerp, Vector4.lerp, Color.lerp, Quaternion.slerp, Basis.slerp, Transform2D.interpolate_with, or Transform3D.interpolate_with.

Variant lerp(Variant from, Variant to, Variant weight)

Parameters

from Variant

to Variant

weight Variant

lerp_angle(float, float, float)

Linearly interpolates between two angles (in radians) by a weight value between 0.0 and 1.0.

Similar to @GlobalScope.lerp, but interpolates correctly when the angles wrap around TAU. To perform eased interpolation with @GlobalScope.lerp_angle, combine it with @GlobalScope.ease or @GlobalScope.smoothstep.

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

Note: This function lerps through the shortest path between from and to. However, when these two angles are approximately PI + k * TAU apart for any integer k, it's not obvious which way they lerp due to floating-point precision errors. For example, lerp_angle(0, PI, weight) lerps counter-clockwise, while lerp_angle(0, PI + 5 * TAU, weight) lerps clockwise.

float lerp_angle(float from, float to, float weight)

Parameters

from float

to float

weight float

lerpf(float, float, float)

Linearly interpolates between two values by the factor defined in weight. To perform interpolation, weight should be between 0.0 and 1.0 (inclusive). However, values outside this range are allowed and can be used to perform extrapolation. If this is not desired, use @GlobalScope.clampf on the result of this function.

lerpf(0, 4, 0.75) # Returns 3.0

See also @GlobalScope.inverse_lerp which performs the reverse of this operation. To perform eased interpolation with @GlobalScope.lerp, combine it with @GlobalScope.ease or @GlobalScope.smoothstep.

float lerpf(float from, float to, float weight)

Parameters

from float

to float

weight float

linear_to_db(float)

Converts from linear energy to decibels (audio). Since volume is not normally linear, this can be used to implement volume sliders that behave as expected.

Example: Change the Master bus's volume through a Slider node, which ranges from 0.0 to 1.0:

AudioServer.set_bus_volume_db(AudioServer.get_bus_index("Master"), linear_to_db($Slider.value))

float linear_to_db(float lin)

Parameters

lin float

log(float)

Returns the natural logarithm of x (base [i]e[/i], with e being approximately 2.71828). This is the amount of time needed to reach a certain level of continuous growth.

Note: This is not the same as the "log" function on most calculators, which uses a base 10 logarithm. To use base 10 logarithm, use log(x) / log(10).

log(10) # Returns 2.302585

Note: The logarithm of 0 returns -inf, while negative values return -nan.

float log(float x)

Parameters

x float

max(...)

Qualifiers: vararg

Returns the maximum of the given numeric values. This function can take any number of arguments.

max(1, 7, 3, -6, 5) # Returns 7

Note: When using this on vectors it will not perform component-wise maximum, and will pick the largest value when compared using x < y. To perform component-wise maximum, use Vector2.max, Vector2i.max, Vector3.max, Vector3i.max, Vector4.max, and Vector4i.max.

Variant max(...)

maxf(float, float)

Returns the maximum of two float values.

maxf(3.6, 24)   # Returns 24.0
maxf(-3.99, -4) # Returns -3.99

float maxf(float a, float b)

Parameters

a float

b float

maxi(int, int)

Returns the maximum of two int values.

maxi(1, 2)   # Returns 2
maxi(-3, -4) # Returns -3

int maxi(int a, int b)

Parameters

a int

b int

min(...)

Qualifiers: vararg

Returns the minimum of the given numeric values. This function can take any number of arguments.

min(1, 7, 3, -6, 5) # Returns -6

Note: When using this on vectors it will not perform component-wise minimum, and will pick the smallest value when compared using x < y. To perform component-wise minimum, use Vector2.min, Vector2i.min, Vector3.min, Vector3i.min, Vector4.min, and Vector4i.min.

Variant min(...)

minf(float, float)

Returns the minimum of two float values.

minf(3.6, 24)   # Returns 3.6
minf(-3.99, -4) # Returns -4.0

float minf(float a, float b)

Parameters

a float

b float

mini(int, int)

Returns the minimum of two int values.

mini(1, 2)   # Returns 1
mini(-3, -4) # Returns -4

int mini(int a, int b)

Parameters

a int

b int

move_toward(float, float, float)

Moves from toward to by the delta amount. Will not go past to.

Use a negative delta value to move away.

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

float move_toward(float from, float to, float delta)

Parameters

from float

to float

delta float

nearest_po2(int)

Returns the smallest integer power of 2 that is greater than or equal to value.

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)

Warning: Due to its implementation, this method returns 0 rather than 1 for values less than or equal to 0, with an exception for value being the smallest negative 64-bit integer (-9223372036854775808) in which case the value is returned unchanged.

int nearest_po2(int value)

Parameters

value int

pingpong(float, float)

Wraps value between 0 and the length. If the limit is reached, the next value the function returns is decreased to the 0 side or increased to the length side (like a triangle wave). If length is less than zero, it becomes positive.

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

float pingpong(float value, float length)

Parameters

value float

length float

posmod(int, int)

Returns the integer modulus of x divided by y that wraps equally in positive and negative.

print("#(i)  (i % 3)   (posmod(i, 3))")
for i in range(-3, 4):
    print("%2d       %2d  | %2d" % [i, i % 3, posmod(i, 3)])

Prints:

• text

(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

int posmod(int x, int y)

Parameters

x int

y int

pow(float, float)

Returns the result of base raised to the power of exp.

In GDScript, this is the equivalent of the ** operator.

pow(2, 5)   # Returns 32.0
pow(4, 1.5) # Returns 8.0

float pow(float base, float exp)

Parameters

base float

exp float

print(...)

Qualifiers: vararg

Converts one or more arguments of any type to string in the best way possible and prints them to the console.

• gdscript
• C#

var a = [1, 2, 3]
print("a", "b", a) # Prints "ab[1, 2, 3]"

Note: Consider using @GlobalScope.push_error and @GlobalScope.push_warning to print error and warning messages instead of @GlobalScope.print or @GlobalScope.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. See also print_to_stdout and application/run/disable_stdout.

void print(...)

print_rich(...)

Qualifiers: vararg

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: b, i, u, s, indent, code, url, center, right, color, bgcolor, fgcolor.

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 is represented with faint text but without any font change. Unsupported tags are left as-is in standard output.

• gdscript
• C#

print_rich("[color=green][b]Hello world![/b][/color]") # Prints "Hello world!", in green with a bold font.

Note: Consider using @GlobalScope.push_error and @GlobalScope.push_warning to print error and warning messages instead of @GlobalScope.print or @GlobalScope.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.

Note: On Windows, only Windows 10 and later correctly displays ANSI escape codes in standard output.

Note: Output displayed in the editor supports clickable [url=address]text[/url] tags. The [url] tag's address value is handled by OS.shell_open when clicked.

void print_rich(...)

print_verbose(...)

Qualifiers: vararg

If verbose mode is enabled (is_stdout_verbose returning true), converts one or more arguments of any type to string in the best way possible and prints them to the console.

void print_verbose(...)

printerr(...)

Qualifiers: vararg

Prints one or more arguments to strings in the best way possible to standard error line.

• gdscript
• C#

printerr("prints to stderr")

void printerr(...)

printraw(...)

Qualifiers: vararg

Prints one or more arguments to strings in the best way possible to the OS terminal. Unlike @GlobalScope.print, no newline is automatically added at the end.

Note: The OS terminal is not the same as the editor's Output dock. The output sent to the OS terminal can be seen when running Godot from a terminal. On Windows, this requires using the console.exe executable.

• gdscript
• C#

# Prints "ABC" to terminal.
printraw("A")
printraw("B")
printraw("C")

void printraw(...)

prints(...)

Qualifiers: vararg

Prints one or more arguments to the console with a space between each argument.

• gdscript
• C#

prints("A", "B", "C") # Prints "A B C"

void prints(...)

printt(...)

Qualifiers: vararg

Prints one or more arguments to the console with a tab between each argument.

• gdscript
• C#

printt("A", "B", "C") # Prints "A       B       C"

void printt(...)

push_error(...)

Qualifiers: vararg

Pushes an error message to Godot's built-in debugger and to the OS terminal.

• gdscript
• C#

push_error("test error") # Prints "test error" to debugger and terminal as an error.

Note: This function does not pause project execution. To print an error message and pause project execution in debug builds, use assert(false, "test error") instead.

void push_error(...)

push_warning(...)

Qualifiers: vararg

Pushes a warning message to Godot's built-in debugger and to the OS terminal.

• gdscript
• C#

push_warning("test warning") # Prints "test warning" to debugger and terminal as a warning.

void push_warning(...)

rad_to_deg(float)

Converts an angle expressed in radians to degrees.

rad_to_deg(0.523599) # Returns 30
rad_to_deg(PI)       # Returns 180
rad_to_deg(PI * 2)   # Returns 360

float rad_to_deg(float rad)

Parameters

rad float

rand_from_seed(int)

Given a seed, returns a PackedInt64Array of size 2, where its first element is the randomized int value, and the second element is the same as seed. Passing the same seed consistently returns the same array.

Note: "Seed" here refers to the internal state of the pseudo random number generator, currently implemented as a 64 bit integer.

var a = rand_from_seed(4)

print(a[0]) # Prints 2879024997
print(a[1]) # Prints 4

PackedInt64Array rand_from_seed(int seed)

Parameters

seed int

randf

Returns a random floating-point value between 0.0 and 1.0 (inclusive).

• gdscript
• C#

randf() # Returns e.g. 0.375671

float randf

randf_range(float, float)

Returns a random floating-point value between from and to (inclusive).

• gdscript
• C#

randf_range(0, 20.5) # Returns e.g. 7.45315
randf_range(-10, 10) # Returns e.g. -3.844535

float randf_range(float from, float to)

Parameters

from float

to float

randfn(float, float)

Returns a normally-distributed, pseudo-random floating-point value from the specified mean and a standard deviation. This is also known as a Gaussian distribution.

Note: This method uses the Box-Muller transform algorithm.

float randfn(float mean, float deviation)

Parameters

mean float

deviation float

randi

Returns a random unsigned 32-bit integer. Use remainder to obtain a random value in the interval [0, N - 1] (where N is smaller than 2^32).

• gdscript
• C#

randi()           # Returns random integer between 0 and 2^32 - 1
randi() % 20      # Returns random integer between 0 and 19
randi() % 100     # Returns random integer between 0 and 99
randi() % 100 + 1 # Returns random integer between 1 and 100

int randi

randi_range(int, int)

Returns a random signed 32-bit integer between from and to (inclusive). If to is lesser than from, they are swapped.

• gdscript
• C#

randi_range(0, 1)      # Returns either 0 or 1
randi_range(-10, 1000) # Returns random integer between -10 and 1000

int randi_range(int from, int to)

Parameters

from int

to int

randomize

Randomizes the seed (or the internal state) of the random number generator. The current implementation uses a number based on the device's time.

Note: This function is called automatically when the project is run. If you need to fix the seed to have consistent, reproducible results, use @GlobalScope.seed to initialize the random number generator.

void randomize

remap(float, float, float, float, float)

Maps a value from range [istart, istop] to [ostart, ostop]. See also @GlobalScope.lerp and @GlobalScope.inverse_lerp. If value is outside [istart, istop], then the resulting value will also be outside [ostart, ostop]. If this is not desired, use @GlobalScope.clamp on the result of this function.

remap(75, 0, 100, -1, 1) # Returns 0.5

For complex use cases where multiple ranges are needed, consider using Curve or Gradient instead.

Note: If istart == istop, the return value is undefined (most likely NaN, INF, or -INF).

float remap(float value, float istart, float istop, float ostart, float ostop)

Parameters

value float

istart float

istop float

ostart float

ostop float

rid_allocate_id

Allocates a unique ID which can be used by the implementation to construct an RID. This is used mainly from native extensions to implement servers.

int rid_allocate_id

rid_from_int64(int)

Creates an RID from a base. This is used mainly from native extensions to build servers.

RID rid_from_int64(int base)

Parameters

base int

rotate_toward(float, float, float)

Rotates from toward to by the delta amount. Will not go past to.

Similar to @GlobalScope.move_toward, but interpolates correctly when the angles wrap around TAU.

If delta is negative, this function will rotate away from to, toward the opposite angle, and will not go past the opposite angle.

float rotate_toward(float from, float to, float delta)

Parameters

from float

to float

delta float

round(Variant)

Rounds x to the nearest whole number, with halfway cases rounded away from 0. Supported types: int, float, Vector2, Vector2i, Vector3, Vector3i, Vector4, Vector4i.

round(2.4) # Returns 2
round(2.5) # Returns 3
round(2.6) # Returns 3

See also @GlobalScope.floor, @GlobalScope.ceil, and @GlobalScope.snapped.

Note: For better type safety, use @GlobalScope.roundf, @GlobalScope.roundi, round, round, or round.

Variant round(Variant x)

Parameters

x Variant

roundf(float)

Rounds x to the nearest whole number, with halfway cases rounded away from 0.

A type-safe version of @GlobalScope.round, returning a float.

float roundf(float x)

Parameters

x float

roundi(float)

Rounds x to the nearest whole number, with halfway cases rounded away from 0.

A type-safe version of @GlobalScope.round, returning an int.

int roundi(float x)

Parameters

x float

seed(int)

Sets the seed for the random number generator to base. Setting the seed manually can ensure consistent, repeatable results for most random functions.

• gdscript
• C#

var my_seed = "Godot Rocks".hash()
seed(my_seed)
var a = randf() + randi()
seed(my_seed)
var b = randf() + randi()
# a and b are now identical

void seed(int base)

Parameters

base int

sign(Variant)

Returns the same type of Variant as x, with -1 for negative values, 1 for positive values, and 0 for zeros. For nan values it returns 0.

Supported types: int, float, Vector2, Vector2i, Vector3, Vector3i, Vector4, Vector4i.

sign(-6.0) # Returns -1
sign(0.0)  # Returns 0
sign(6.0)  # Returns 1
sign(NAN)  # Returns 0

sign(Vector3(-6.0, 0.0, 6.0)) # Returns (-1, 0, 1)

Note: For better type safety, use @GlobalScope.signf, @GlobalScope.signi, sign, sign, sign, sign, sign, or sign.

Variant sign(Variant x)

Parameters

x Variant

signf(float)

Returns -1.0 if x is negative, 1.0 if x is positive, and 0.0 if x is zero. For nan values of x it returns 0.0.

signf(-6.5) # Returns -1.0
signf(0.0)  # Returns 0.0
signf(6.5)  # Returns 1.0
signf(NAN)  # Returns 0.0

float signf(float x)

Parameters

x float

signi(int)

Returns -1 if x is negative, 1 if x is positive, and 0 if x is zero.

signi(-6) # Returns -1
signi(0)  # Returns 0
signi(6)  # Returns 1

int signi(int x)

Parameters

x int

sin(float)

Returns the sine of angle angle_rad in radians.

sin(0.523599)       # Returns 0.5
sin(deg_to_rad(90)) # Returns 1.0

float sin(float angle_rad)

Parameters

angle_rad float

sinh(float)

Returns the hyperbolic sine of x.

var a = log(2.0) # Returns 0.693147
sinh(a) # Returns 0.75

float sinh(float x)

Parameters

x float

smoothstep(float, float, float)

Returns a smooth cubic Hermite interpolation between 0 and 1.

For positive ranges (when from <= to) the return value is 0 when x <= from, and 1 when x >= to. If x lies between from and to, the return value follows an S-shaped curve that smoothly transitions from 0 to 1.

For negative ranges (when from > to) the function is mirrored and returns 1 when x <= to and 0 when x >= from.

This S-shaped curve is the cubic Hermite interpolator, given by f(y) = 3*y^2 - 2*y^3 where y = (x-from) / (to-from).

smoothstep(0, 2, -5.0) # Returns 0.0
smoothstep(0, 2, 0.5) # Returns 0.15625
smoothstep(0, 2, 1.0) # Returns 0.5
smoothstep(0, 2, 2.0) # Returns 1.0

Compared to @GlobalScope.ease with a curve value of -1.6521, @GlobalScope.smoothstep returns the smoothest possible curve with no sudden changes in the derivative. If you need to perform more advanced transitions, use Tween or AnimationPlayer.

\ Comparison between smoothstep() and ease(x, -1.6521) return values\

\ Smoothstep() return values with positive, zero, and negative ranges

float smoothstep(float from, float to, float x)

Parameters

from float

to float

x float

snapped(Variant, Variant)

Returns the multiple of step that is the closest to x. This can also be used to round a floating-point number to an arbitrary number of decimals.

The returned value is the same type of Variant as step. Supported types: int, float, Vector2, Vector2i, Vector3, Vector3i, Vector4, Vector4i.

snapped(100, 32)  # Returns 96
snapped(3.14159, 0.01)  # Returns 3.14

snapped(Vector2(34, 70), Vector2(8, 8))  # Returns (32, 72)

See also @GlobalScope.ceil, @GlobalScope.floor, and @GlobalScope.round.

Note: For better type safety, use @GlobalScope.snappedf, @GlobalScope.snappedi, Vector2.snapped, Vector2i.snapped, Vector3.snapped, Vector3i.snapped, Vector4.snapped, or Vector4i.snapped.

Variant snapped(Variant x, Variant step)

Parameters

x Variant

step Variant

snappedf(float, float)

Returns the multiple of step that is the closest to x. This can also be used to round a floating-point number to an arbitrary number of decimals.

A type-safe version of @GlobalScope.snapped, returning a float.

snappedf(32.0, 2.5)  # Returns 32.5
snappedf(3.14159, 0.01)  # Returns 3.14

float snappedf(float x, float step)

Parameters

x float

step float

snappedi(float, int)

Returns the multiple of step that is the closest to x.

A type-safe version of @GlobalScope.snapped, returning an int.

snappedi(53, 16)  # Returns 48
snappedi(4096, 100)  # Returns 4100

int snappedi(float x, int step)

Parameters

x float

step int

sqrt(float)

Returns the square root of x, where x is a non-negative number.

sqrt(9)     # Returns 3
sqrt(10.24) # Returns 3.2
sqrt(-1)    # Returns NaN

Note: Negative values of x return NaN ("Not a Number"). in C#, if you need negative inputs, use System.Numerics.Complex.

float sqrt(float x)

Parameters

x float

step_decimals(float)

Returns the position of the first non-zero digit, after the decimal point. Note that the maximum return value is 10, which is a design decision in the implementation.

var n = step_decimals(5)       # n is 0
n = step_decimals(1.0005)      # n is 4
n = step_decimals(0.000000005) # n is 9

int step_decimals(float x)

Parameters

x float

str(...)

Qualifiers: vararg

Converts one or more arguments of any Variant type to a String in the best way possible.

var a = [10, 20, 30]
var b = str(a)
print(len(a)) # Prints 3 (the number of elements in the array).
print(len(b)) # Prints 12 (the length of the string "[10, 20, 30]").

String str(...)

str_to_var(String)

Converts a formatted string that was returned by @GlobalScope.var_to_str to the original Variant.

• gdscript
• C#

var data = '{ "a": 1, "b": 2 }' # data is a String
var dict = str_to_var(data)     # dict is a Dictionary
print(dict["a"])                # Prints 1

Variant str_to_var(String string)

Parameters

string String

tan(float)

Returns the tangent of angle angle_rad in radians.

tan(deg_to_rad(45)) # Returns 1

float tan(float angle_rad)

Parameters

angle_rad float

tanh(float)

Returns the hyperbolic tangent of x.

var a = log(2.0) # Returns 0.693147
tanh(a)          # Returns 0.6

float tanh(float x)

Parameters

x float

type_convert(Variant, int)

Converts the given variant to the given type, using the Variant.Type values. This method is generous with how it handles types, it can automatically convert between array types, convert numeric Strings to int, and converting most things to String.

If the type conversion cannot be done, this method will return the default value for that type, for example converting Rect2 to Vector2 will always return ZERO. This method will never show error messages as long as type is a valid Variant type.

The returned value is a Variant, but the data inside and its type will be the same as the requested type.

type_convert("Hi!", TYPE_INT) # Returns 0
type_convert("123", TYPE_INT) # Returns 123
type_convert(123.4, TYPE_INT) # Returns 123
type_convert(5, TYPE_VECTOR2) # Returns (0, 0)
type_convert("Hi!", TYPE_NIL) # Returns null

Variant type_convert(Variant variant, int type)

Parameters

variant Variant

type int

type_string(int)

Returns a human-readable name of the given type, using the Variant.Type values.

print(TYPE_INT) # Prints 2
print(type_string(TYPE_INT)) # Prints "int"
print(type_string(TYPE_STRING)) # Prints "String"

See also @GlobalScope.typeof.

String type_string(int type)

Parameters

type int

typeof(Variant)

Returns the internal type of the given variable, using the Variant.Type values.

var json = JSON.new()
json.parse('["a", "b", "c"]')
var result = json.get_data()
if result is Array:
    print(result[0]) # Prints "a"
else:
    print("Unexpected result!")

See also @GlobalScope.type_string.

int typeof(Variant variable)

Parameters

variable Variant

var_to_bytes(Variant)

Encodes a Variant value to a byte array, without encoding objects. Deserialization can be done with @GlobalScope.bytes_to_var.

Note: If you need object serialization, see @GlobalScope.var_to_bytes_with_objects.

Note: Encoding Callable is not supported and will result in an empty value, regardless of the data.

PackedByteArray var_to_bytes(Variant variable)

Parameters

variable Variant

var_to_bytes_with_objects(Variant)

Encodes a Variant value to a byte array. Encoding objects is allowed (and can potentially include executable code). Deserialization can be done with @GlobalScope.bytes_to_var_with_objects.

Note: Encoding Callable is not supported and will result in an empty value, regardless of the data.

PackedByteArray var_to_bytes_with_objects(Variant variable)

Parameters

variable Variant

var_to_str(Variant)

Converts a Variant variable to a formatted String that can then be parsed using @GlobalScope.str_to_var.

• gdscript
• C#

var a = { "a": 1, "b": 2 }
print(var_to_str(a))

Prints:

• text

{
    "a": 1,
    "b": 2

}

Note: Converting Signal or Callable is not supported and will result in an empty value for these types, regardless of their data.

String var_to_str(Variant variable)

Parameters

variable Variant

weakref(Variant)

Returns a WeakRef instance holding a weak reference to obj. Returns an empty WeakRef instance if obj is null. Prints an error and returns null if obj is neither Object-derived nor null.

A weak reference to an object is not enough to keep the object alive: when the only remaining references to a referent are weak references, garbage collection is free to destroy the referent and reuse its memory for something else. However, until the object is actually destroyed the weak reference may return the object even if there are no strong references to it.

Variant weakref(Variant obj)

Parameters

obj Variant

wrap(Variant, Variant, Variant)

Wraps the Variant value between min and max. Can be used for creating loop-alike behavior or infinite surfaces.

Variant types int and float are supported. If any of the arguments is float this function returns a float, otherwise it returns an int.

var a = wrap(4, 5, 10)
# a is 9 (int)

var a = wrap(7, 5, 10)
# a is 7 (int)

var a = wrap(10.5, 5, 10)
# a is 5.5 (float)

Variant wrap(Variant value, Variant min, Variant max)

Parameters

value Variant

min Variant

max Variant

wrapf(float, float, float)

Wraps the float value between min and max. Can be used for creating loop-alike behavior or infinite surfaces.

# Infinite loop between 5.0 and 9.9
value = wrapf(value + 0.1, 5.0, 10.0)

# Infinite rotation (in radians)
angle = wrapf(angle + 0.1, 0.0, TAU)

# Infinite rotation (in radians)
angle = wrapf(angle + 0.1, -PI, PI)

Note: If min is 0, this is equivalent to @GlobalScope.fposmod, so prefer using that instead.

@GlobalScope.wrapf is more flexible than using the @GlobalScope.fposmod approach by giving the user control over the minimum value.

float wrapf(float value, float min, float max)

Parameters

value float

min float

max float

wrapi(int, int, int)

Wraps the integer value between min and max. Can be used for creating loop-alike behavior or infinite surfaces.

# Infinite loop between 5 and 9
frame = wrapi(frame + 1, 5, 10)

# result is -2
var result = wrapi(-6, -5, -1)

int wrapi(int value, int min, int max)

Parameters

value int

min int

max int