Class GD

Namespace

Godot

Assembly

GodotSharp.dll

Godot's global functions.

public static class GD

Inheritance

object

GD

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Methods

BytesToVar(Span<byte>)

Decodes a byte array back to a Variant value, without decoding objects. Note: If you need object deserialization, see BytesToVarWithObjects(Span<byte>).

public static Variant BytesToVar(Span<byte> bytes)

Parameters

bytes Span<byte>

Byte array that will be decoded to a Variant.

Returns

Variant

The decoded Variant.

BytesToVarWithObjects(Span<byte>)

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

public static Variant BytesToVarWithObjects(Span<byte> bytes)

Parameters

bytes Span<byte>

Byte array that will be decoded to a Variant.

Returns

Variant

The decoded Variant.

Convert(Variant, Type)

Converts what to type in the best way possible. The type parameter uses the Variant.Type values.

public static Variant Convert(Variant what, Variant.Type type)

Parameters

what Variant

type Variant.Type

Returns

Variant

The Variant converted to the given type.

Examples

Variant a = new Godot.Collections.Array { 4, 2.5, 1.2 };
GD.Print(a.VariantType == Variant.Type.Array); // Prints true

var b = GD.Convert(a, Variant.Type.PackedByteArray);
GD.Print(b); // Prints [4, 2, 1]
GD.Print(b.VariantType == Variant.Type.Array); // Prints false

Hash(Variant)

Returns the integer hash of the passed var.

public static int Hash(Variant var)

Parameters

var Variant

Variable that will be hashed.

Returns

int

Hash of the variable passed.

Examples

GD.Print(GD.Hash("a")); // Prints 177670

IsEmpty(Color[])

Returns true if this Color array is empty or doesn't exist.

public static bool IsEmpty(this Color[] instance)

Parameters

instance Color[]

The Color array check.

Returns

bool

Whether or not the array is empty.

IsEmpty(Vector2I[])

Returns true if this Vector2I array is empty or doesn't exist.

public static bool IsEmpty(this Vector2I[] instance)

Parameters

instance Vector2I[]

The Vector2I array check.

Returns

bool

Whether or not the array is empty.

IsEmpty(Vector2[])

Returns true if this Vector2 array is empty or doesn't exist.

public static bool IsEmpty(this Vector2[] instance)

Parameters

instance Vector2[]

The Vector2 array check.

Returns

bool

Whether or not the array is empty.

IsEmpty(Vector3I[])

Returns true if this Vector3I array is empty or doesn't exist.

public static bool IsEmpty(this Vector3I[] instance)

Parameters

instance Vector3I[]

The Vector3I array check.

Returns

bool

Whether or not the array is empty.

IsEmpty(Vector3[])

Returns true if this Vector3 array is empty or doesn't exist.

public static bool IsEmpty(this Vector3[] instance)

Parameters

instance Vector3[]

The Vector3 array check.

Returns

bool

Whether or not the array is empty.

IsEmpty(Vector4I[])

Returns true if this Vector4I array is empty or doesn't exist.

public static bool IsEmpty(this Vector4I[] instance)

Parameters

instance Vector4I[]

The Vector4I array check.

Returns

bool

Whether or not the array is empty.

IsEmpty(Vector4[])

Returns true if this Vector4 array is empty or doesn't exist.

public static bool IsEmpty(this Vector4[] instance)

Parameters

instance Vector4[]

The Vector4 array check.

Returns

bool

Whether or not the array is empty.

IsEmpty(byte[])

Returns true if this byte array is empty or doesn't exist.

public static bool IsEmpty(this byte[] instance)

Parameters

instance byte[]

The byte array check.

Returns

bool

Whether or not the array is empty.

IsEmpty(double[])

Returns true if this double array is empty or doesn't exist.

public static bool IsEmpty(this double[] instance)

Parameters

instance double[]

The double array check.

Returns

bool

Whether or not the array is empty.

IsEmpty(int[])

Returns true if this int array is empty or doesn't exist.

public static bool IsEmpty(this int[] instance)

Parameters

instance int[]

The int array check.

Returns

bool

Whether or not the array is empty.

IsEmpty(long[])

Returns true if this long array is empty or doesn't exist.

public static bool IsEmpty(this long[] instance)

Parameters

instance long[]

The long array check.

Returns

bool

Whether or not the array is empty.

IsEmpty(float[])

Returns true if this float array is empty or doesn't exist.

public static bool IsEmpty(this float[] instance)

Parameters

instance float[]

The float array check.

Returns

bool

Whether or not the array is empty.

IsEmpty(string[])

Returns true if this string array is empty or doesn't exist.

public static bool IsEmpty(this string[] instance)

Parameters

instance string[]

The string array check.

Returns

bool

Whether or not the array is empty.

Join(Color[], string)

Converts this Color array to a string delimited by the given string.

public static string Join(this Color[] instance, string delimiter = ", ")

Parameters

instance Color[]

The Color array to convert.

delimiter string

The delimiter to use between items.

Returns

string

A single string with all items.

Join(Vector2I[], string)

Converts this Vector2I array to a string delimited by the given string.

public static string Join(this Vector2I[] instance, string delimiter = ", ")

Parameters

instance Vector2I[]

The Vector2I array to convert.

delimiter string

The delimiter to use between items.

Returns

string

A single string with all items.

Join(Vector2[], string)

Converts this Vector2 array to a string delimited by the given string.

public static string Join(this Vector2[] instance, string delimiter = ", ")

Parameters

instance Vector2[]

The Vector2 array to convert.

delimiter string

The delimiter to use between items.

Returns

string

A single string with all items.

Join(Vector3I[], string)

Converts this Vector3I array to a string delimited by the given string.

public static string Join(this Vector3I[] instance, string delimiter = ", ")

Parameters

instance Vector3I[]

The Vector3I array to convert.

delimiter string

The delimiter to use between items.

Returns

string

A single string with all items.

Join(Vector3[], string)

Converts this Vector3 array to a string delimited by the given string.

public static string Join(this Vector3[] instance, string delimiter = ", ")

Parameters

instance Vector3[]

The Vector3 array to convert.

delimiter string

The delimiter to use between items.

Returns

string

A single string with all items.

Join(Vector4I[], string)

Converts this Vector4I array to a string delimited by the given string.

public static string Join(this Vector4I[] instance, string delimiter = ", ")

Parameters

instance Vector4I[]

The Vector4I array to convert.

delimiter string

The delimiter to use between items.

Returns

string

A single string with all items.

Join(Vector4[], string)

Converts this Vector4 array to a string delimited by the given string.

public static string Join(this Vector4[] instance, string delimiter = ", ")

Parameters

instance Vector4[]

The Vector4 array to convert.

delimiter string

The delimiter to use between items.

Returns

string

A single string with all items.

Join(byte[], string)

Converts this byte array to a string delimited by the given string.

public static string Join(this byte[] instance, string delimiter = ", ")

Parameters

instance byte[]

The byte array to convert.

delimiter string

The delimiter to use between items.

Returns

string

A single string with all items.

Join(double[], string)

Converts this double array to a string delimited by the given string.

public static string Join(this double[] instance, string delimiter = ", ")

Parameters

instance double[]

The double array to convert.

delimiter string

The delimiter to use between items.

Returns

string

A single string with all items.

Join(int[], string)

Converts this int array to a string delimited by the given string.

public static string Join(this int[] instance, string delimiter = ", ")

Parameters

instance int[]

The int array to convert.

delimiter string

The delimiter to use between items.

Returns

string

A single string with all items.

Join(long[], string)

Converts this long array to a string delimited by the given string.

public static string Join(this long[] instance, string delimiter = ", ")

Parameters

instance long[]

The long array to convert.

delimiter string

The delimiter to use between items.

Returns

string

A single string with all items.

Join(float[], string)

Converts this float array to a string delimited by the given string.

public static string Join(this float[] instance, string delimiter = ", ")

Parameters

instance float[]

The float array to convert.

delimiter string

The delimiter to use between items.

Returns

string

A single string with all items.

Join(string[], string)

Converts this string array to a string delimited by the given string.

public static string Join(this string[] instance, string delimiter = ", ")

Parameters

instance string[]

The string array to convert.

delimiter string

The delimiter to use between items.

Returns

string

A single string with all items.

Load(string)

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.

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.

Important: The path must be absolute, a local path will just return null. This method is a simplified version of Load(string, string, CacheMode), which can be used for more advanced scenarios.

public static Resource Load(string path)

Parameters

path string

Path of the Resource to load.

Returns

Resource

The loaded Resource.

Examples

// Load a scene called main located in the root of the project directory and cache it in a variable.
var main = GD.Load("res://main.tscn"); // main will contain a PackedScene resource.

Load<T>(string)

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.

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.

Important: The path must be absolute, a local path will just return null. This method is a simplified version of Load(string, string, CacheMode), which can be used for more advanced scenarios.

public static T Load<T>(string path) where T : class

Parameters

path string

Path of the Resource to load.

Returns

T

Type Parameters

T

The type to cast to. Should be a descendant of Resource.

Examples

// Load a scene called main located in the root of the project directory and cache it in a variable.
var main = GD.Load<PackedScene>("res://main.tscn"); // main will contain a PackedScene resource.

Print(params object[])

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

Note: Consider using PushError(params object[]) and PushWarning(params object[]) to print error and warning messages instead of Print(params object[]). This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed.

public static void Print(params object[] what)

Parameters

what object[]

Arguments that will be printed.

Examples

var a = new Godot.Collections.Array { 1, 2, 3 };
GD.Print("a", "b", a); // Prints ab[1, 2, 3]

Print(string)

Prints a message to the console.

Note: Consider using PushError(string) and PushWarning(string) to print error and warning messages instead of Print(string). This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed.

public static void Print(string what)

Parameters

what string

Message that will be printed.

PrintErr(params object[])

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

public static void PrintErr(params object[] what)

Parameters

what object[]

Arguments that will be printed.

Examples

GD.PrintErr("prints to stderr");

PrintErr(string)

Prints a message to standard error line.

public static void PrintErr(string what)

Parameters

what string

Message that will be printed.

PrintRaw(params object[])

Prints one or more arguments to strings in the best way possible to the OS terminal. Unlike Print(params object[]), no newline is added at the end.

public static void PrintRaw(params object[] what)

Parameters

what object[]

Arguments that will be printed.

Examples

GD.PrintRaw("A");
GD.PrintRaw("B");
GD.PrintRaw("C");
// Prints ABC to terminal

PrintRaw(string)

Prints a message to the OS terminal. Unlike Print(string), no newline is added at the end.

public static void PrintRaw(string what)

Parameters

what string

Message that will be printed.

PrintRich(params object[])

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. Color tags only support named colors such as red, not hexadecimal color codes. Unsupported tags will be left as-is in standard output. When printing to standard output, the supported subset of BBCode is converted to ANSI escape codes for the terminal emulator to display. Displaying ANSI escape codes is currently only supported on Linux and macOS. Support for ANSI escape codes may vary across terminal emulators, especially for italic and strikethrough.

Note: Consider using PushError(params object[]) and PushWarning(params object[]) to print error and warning messages instead of Print(params object[]) or PrintRich(params object[]). This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed.

public static void PrintRich(params object[] what)

Parameters

what object[]

Arguments that will be printed.

Examples

GD.PrintRich("[code][b]Hello world![/b][/code]"); // Prints out: [b]Hello world![/b]

PrintRich(string)

Prints a message to the console. The following BBCode tags are supported: b, i, u, s, indent, code, url, center, right, color, bgcolor, fgcolor. Color tags only support named colors such as red, not hexadecimal color codes. Unsupported tags will be left as-is in standard output. When printing to standard output, the supported subset of BBCode is converted to ANSI escape codes for the terminal emulator to display. Displaying ANSI escape codes is currently only supported on Linux and macOS. Support for ANSI escape codes may vary across terminal emulators, especially for italic and strikethrough.

Note: Consider using PushError(string) and PushWarning(string) to print error and warning messages instead of Print(string) or PrintRich(string). This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed.

public static void PrintRich(string what)

Parameters

what string

Message that will be printed.

PrintS(params object[])

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

public static void PrintS(params object[] what)

Parameters

what object[]

Arguments that will be printed.

Examples

GD.PrintS("A", "B", "C"); // Prints A B C

PrintT(params object[])

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

public static void PrintT(params object[] what)

Parameters

what object[]

Arguments that will be printed.

Examples

GD.PrintT("A", "B", "C"); // Prints A       B       C

PushError(params object[])

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

Note: Errors printed this way will not pause project execution.

public static void PushError(params object[] what)

Parameters

what object[]

Arguments that form the error message.

Examples

GD.PushError("test_error"); // Prints "test error" to debugger and terminal as error call

PushError(string)

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

Note: Errors printed this way will not pause project execution.

public static void PushError(string message)

Parameters

message string

Error message.

Examples

GD.PushError("test error"); // Prints "test error" to debugger and terminal as error call

PushWarning(params object[])

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

public static void PushWarning(params object[] what)

Parameters

what object[]

Arguments that form the warning message.

Examples

GD.PushWarning("test warning"); // Prints "test warning" to debugger and terminal as warning call

PushWarning(string)

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

public static void PushWarning(string message)

Parameters

message string

Warning message.

Examples

GD.PushWarning("test warning"); // Prints "test warning" to debugger and terminal as warning call

RandFromSeed(ref ulong)

Given a seed, returns a randomized uint value. The seed may be modified. Passing the same seed consistently returns the same value.

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

public static uint RandFromSeed(ref ulong seed)

Parameters

seed ulong

Seed to use to generate the random number. If a different seed is used, its value will be modified.

Returns

uint

A random uint number.

Examples

var a = GD.RandFromSeed(4);

RandRange(double, double)

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

public static double RandRange(double from, double to)

Parameters

from double

to double

Returns

double

A random double number inside the given range.

Examples

GD.RandRange(0.0, 20.5);   // Returns e.g. 7.45315
GD.RandRange(-10.0, 10.0); // Returns e.g. -3.844535

RandRange(int, int)

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

public static int RandRange(int from, int to)

Parameters

from int

to int

Returns

int

A random int number inside the given range.

Examples

GD.RandRange(0, 1);      // Returns either 0 or 1
GD.RandRange(-10, 1000); // Returns random integer between -10 and 1000

Randf()

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

public static float Randf()

Returns

float

A random float number.

Examples

GD.Randf(); // Returns e.g. 0.375671

Randfn(double, double)

Returns a normally-distributed pseudo-random floating point value using Box-Muller transform with the specified and a standard deviation. This is also called Gaussian distribution.

public static double Randfn(double mean, double deviation)

Parameters

mean double

deviation double

Returns

double

A random normally-distributed float number.

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

public static uint Randi()

Returns

uint

A random uint number.

Examples

GD.Randi();           // Returns random integer between 0 and 2^32 - 1
GD.Randi() % 20;      // Returns random integer between 0 and 19
GD.Randi() % 100;     // Returns random integer between 0 and 99
GD.Randi() % 100 + 1; // Returns random integer between 1 and 100

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 method is called automatically when the project is run. If you need to fix the seed to have consistent, reproducible results, use Seed(ulong) to initialize the random number generator.

public static void Randomize()

Range(int)

Returns a IEnumerable<T> that iterates from 0 (inclusive) to end (exclusive) in steps of 1.

public static IEnumerable<int> Range(int end)

Parameters

end int

The last index.

Returns

IEnumerable<int>

Range(int, int)

Returns a IEnumerable<T> that iterates from start (inclusive) to end (exclusive) in steps of 1.

public static IEnumerable<int> Range(int start, int end)

Parameters

start int

The first index.

end int

The last index.

Returns

IEnumerable<int>

Range(int, int, int)

Returns a IEnumerable<T> that iterates from start (inclusive) to end (exclusive) in steps of step. The argument step can be negative, but not 0.

public static IEnumerable<int> Range(int start, int end, int step)

Parameters

start int

The first index.

end int

The last index.

step int

The amount by which to increment the index on each iteration.

Returns

IEnumerable<int>

Exceptions

ArgumentException

step is 0.

Seed(ulong)

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

public static void Seed(ulong seed)

Parameters

seed ulong

Seed that will be used.

Examples

ulong mySeed = (ulong)GD.Hash("Godot Rocks");
GD.Seed(mySeed);
var a = GD.Randf() + GD.Randi();
GD.Seed(mySeed);
var b = GD.Randf() + GD.Randi();
// a and b are now identical

StrToVar(string)

Converts a formatted string that was returned by VarToStr(Variant) to the original value.

public static Variant StrToVar(string str)

Parameters

str string

String that will be converted to Variant.

Returns

Variant

The decoded Variant.

Examples

string a = "{ \"a\": 1, \"b\": 2 }";        // a is a string
var b = GD.StrToVar(a).AsGodotDictionary(); // b is a Dictionary
GD.Print(b["a"]);                           // Prints 1

Stringify(Color[])

Converts this Color array to a string with brackets.

public static string Stringify(this Color[] instance)

Parameters

instance Color[]

The Color array to convert.

Returns

string

A single string with all items.

Stringify(Vector2I[])

Converts this Vector2I array to a string with brackets.

public static string Stringify(this Vector2I[] instance)

Parameters

instance Vector2I[]

The Vector2I array to convert.

Returns

string

A single string with all items.

Stringify(Vector2[])

Converts this Vector2 array to a string with brackets.

public static string Stringify(this Vector2[] instance)

Parameters

instance Vector2[]

The Vector2 array to convert.

Returns

string

A single string with all items.

Stringify(Vector3I[])

Converts this Vector3I array to a string with brackets.

public static string Stringify(this Vector3I[] instance)

Parameters

instance Vector3I[]

The Vector3I array to convert.

Returns

string

A single string with all items.

Stringify(Vector3[])

Converts this Vector3 array to a string with brackets.

public static string Stringify(this Vector3[] instance)

Parameters

instance Vector3[]

The Vector3 array to convert.

Returns

string

A single string with all items.

Stringify(Vector4I[])

Converts this Vector4I array to a string with brackets.

public static string Stringify(this Vector4I[] instance)

Parameters

instance Vector4I[]

The Vector4I array to convert.

Returns

string

A single string with all items.

Stringify(Vector4[])

Converts this Vector4 array to a string with brackets.

public static string Stringify(this Vector4[] instance)

Parameters

instance Vector4[]

The Vector4 array to convert.

Returns

string

A single string with all items.

Stringify(byte[])

Converts this byte array to a string with brackets.

public static string Stringify(this byte[] instance)

Parameters

instance byte[]

The byte array to convert.

Returns

string

A single string with all items.

Stringify(double[])

Converts this double array to a string with brackets.

public static string Stringify(this double[] instance)

Parameters

instance double[]

The double array to convert.

Returns

string

A single string with all items.

Stringify(int[])

Converts this int array to a string with brackets.

public static string Stringify(this int[] instance)

Parameters

instance int[]

The int array to convert.

Returns

string

A single string with all items.

Stringify(long[])

Converts this long array to a string with brackets.

public static string Stringify(this long[] instance)

Parameters

instance long[]

The long array to convert.

Returns

string

A single string with all items.

Stringify(float[])

Converts this float array to a string with brackets.

public static string Stringify(this float[] instance)

Parameters

instance float[]

The float array to convert.

Returns

string

A single string with all items.

Stringify(string[])

Converts this string array to a string with brackets.

public static string Stringify(this string[] instance)

Parameters

instance string[]

The string array to convert.

Returns

string

A single string with all items.

TypeToVariantType(Type)

Get the Variant.Type that corresponds for the given Type.

public static Variant.Type TypeToVariantType(Type type)

Parameters

type Type

Returns

Variant.Type

The Variant.Type for the given type.

VarToBytes(Variant)

Encodes a Variant value to a byte array, without encoding objects. Deserialization can be done with BytesToVar(Span<byte>). Note: If you need object serialization, see VarToBytesWithObjects(Variant).

public static byte[] VarToBytes(Variant var)

Parameters

var Variant

Variant that will be encoded.

Returns

byte[]

The Variant encoded as an array of bytes.

VarToBytesWithObjects(Variant)

Encodes a Variant. Encoding objects is allowed (and can potentially include executable code). Deserialization can be done with BytesToVarWithObjects(Span<byte>).

public static byte[] VarToBytesWithObjects(Variant var)

Parameters

var Variant

Variant that will be encoded.

Returns

byte[]

The Variant encoded as an array of bytes.

VarToStr(Variant)

Converts a Variantvar to a formatted string that can later be parsed using StrToVar(string).

public static string VarToStr(Variant var)

Parameters

var Variant

Variant that will be converted to string.

Returns

string

The Variant encoded as a string.

Examples

var a = new Godot.Collections.Dictionary { ["a"] = 1, ["b"] = 2 };
GD.Print(GD.VarToStr(a));
// Prints:
// {
//     "a": 1,
//     "b": 2
// }