C# API differences to GDScript¶

This is a (incomplete) list of API differences between C# and GDScript.

General differences¶

As explained in the C# basics, C# generally uses PascalCase instead of the snake_case used in GDScript and C++.

Global scope¶

Global functions and some constants had to be moved to classes, since C# does not allow declaring them in namespaces. Most global constants were moved to their own enums.

Constants¶

In C#, only primitive types can be constant. For example, the TAU constant is replaced by the Mathf.Tau constant, but the Vector2.RIGHT constant is replaced by the Vector2.Right read-only property. This behaves similarly to a constant, but can't be used in some contexts like switch statements.

Global enum constants were moved to their own enums. For example, ERR_* constants were moved to the Error enum.

Special cases:

GDScript	C#
`TYPE_*`	`Variant.Type` enum
`OP_*`	`Variant.Operator` enum

Math functions¶

Math global functions, like abs, acos, asin, atan and atan2, are located under Mathf as Abs, Acos, Asin, Atan and Atan2. The PI constant can be found as Mathf.Pi.

C# also provides static System.Math and System.MathF classes that may contain other useful mathematical operations.

Random functions¶

Random global functions, like rand_range and rand_seed, are located under GD. Example: GD.RandRange and GD.RandSeed.

Consider using System.Random or, if you need cryptographically strong randomness, System.Security.Cryptography.RandomNumberGenerator.

Other functions¶

Many other global functions like print and var_to_str are located under GD. Example: GD.Print and GD.VarToStr.

Exceptions:

GDScript	C#
`weakref(obj)`	`GodotObject.WeakRef(obj)`
`instance_from_id(id)`	`GodotObject.InstanceFromId(id)`
`is_instance_id_valid(id)`	`GodotObject.IsInstanceIdValid(id)`
`is_instance_valid(obj)`	`GodotObject.IsInstanceValid(obj)`

Tips¶

Sometimes it can be useful to use the using static directive. This directive allows to access the members and nested types of a class without specifying the class name.

Example:

using static Godot.GD;

public class Test
{
    static Test()
    {
        Print("Hello"); // Instead of GD.Print("Hello");
    }
}

Full list of equivalences¶

List of Godot's global scope functions and their equivalent in C#:

GDScript	C#
abs	Mathf.Abs
absf	Mathf.Abs
absi	Mathf.Abs
acos	Mathf.Acos
asin	Mathf.Asin
atan	Mathf.Atan
atan2	Mathf.Atan2
bezier_derivative	Mathf.BezierDerivative
bezier_interpolate	Mathf.BezierInterpolate
bytes_to_var	GD.BytesToVar
bytes_to_var_with_objects	GD.BytesToVarWithObjects
ceil	Mathf.Ceil
ceilf	Mathf.Ceil
ceili	Mathf.CeilToInt
clamp	Mathf.Clamp
clampf	Mathf.Clamp
clampi	Mathf.Clamp
cos	Mathf.Cos
cosh	Mathf.Cosh
cubic_interpolate	Mathf.CubicInterpolate
cubic_interpoalte_angle	Mathf.CubicInterpolateAngle
cubic_interpolate_angle_in_time	Mathf.CubicInterpolateInTime
cubic_interpolate_in_time	Mathf.CubicInterpolateAngleInTime
db_to_linear	Mathf.DbToLinear
deg_to_rad	Mathf.DegToRad
ease	Mathf.Ease
error_string	Error.ToString
exp	Mathf.Exp
floor	Mathf.Floor
floorf	Mathf.Floor
floori	Mathf.FloorToInt
fmod	operator %
fposmod	Mathf.PosMod
hash	GD.Hash
instance_from_id	GodotObject.InstanceFromId
inverse_lerp	Mathf.InverseLerp
is_equal_approx	Mathf.IsEqualApprox
is_finite	Mathf.IsFinite or float.IsFinite or double.IsFinite
is_inf	Mathf.IsInf or float.IsInfinity or double.IsInfinity
is_instance_id_valid	GodotObject.IsInstanceIdValid
is_instance_valid	GodotObject.IsInstanceValid
is_nan	Mathf.IsNaN or float.IsNaN or double.IsNaN
is_same	operator == or object.ReferenceEquals
is_zero_approx	Mathf.IsZeroApprox
lerp	Mathf.Lerp
lerp_angle	Mathf.LerpAngle
lerpf	Mathf.Lerp
linear_to_db	Mathf.LinearToDb
log	Mathf.Log
max	Mathf.Max
maxf	Mathf.Max
maxi	Mathf.Max
min	Mathf.Min
minf	Mathf.Min
mini	Mathf.Min
move_toward	Mathf.MoveToward
nearest_po2	Mathf.NearestPo2
pingpong	Mathf.PingPong
posmod	Mathf.PosMod
pow	Mathf.Pow
print	GD.Print
print_rich	GD.PrintRich
print_verbose	Use OS.IsStdoutVerbose and GD.Print
printerr	GD.PrintErr
printraw	GD.PrintRaw
prints	GD.PrintS
printt	GD.PrintT
push_error	GD.PushError
push_warning	GD.PushWarning
rad_to_deg	Mathf.RadToDeg
rand_from_seed	GD.RandFromSeed
randf	GD.Randf
randf_range	GD.RandRange
randfn	GD.Randfn
randi	GD.Randi
randi_range	GD.RandRange
randomize	GD.Randomize
remap	Mathf.Remap
rid_allocate_id	N/A
rid_from_int64	N/A
round	Mathf.Round
roundf	Mathf.Round
roundi	Mathf.RoundToInt
seed	GD.Seed
sign	Mathf.Sign
signf	Mathf.Sign
signi	Mathf.Sign
sin	Mathf.Sin
sinh	Mathf.Sinh
smoothstep	Mathf.SmoothStep
snapped	Mathf.Snapped
snappedf	Mathf.Snapped
snappedi	Mathf.Snapped
sqrt	Mathf.Sqrt
step_decimals	Mathf.StepDecimals
str	Use $ string interpolation
str_to_var	GD.StrToVar
tan	Mathf.Tan
tanh	Mathf.Tanh
typeof	Variant.VariantType
var_to_bytes	GD.VarToBytes
var_to_bytes_with_objects	GD.VarToBytesWithObjects
var_to_str	GD.VarToStr
weakref	GodotObject.WeakRef
wrap	Mathf.Wrap
wrapf	Mathf.Wrap
wrapi	Mathf.Wrap

List of GDScript utility functions and their equivalent in C#:

GDScript	C#
assert	System.Diagnostics.Debug.Assert
char	Use explicit conversion: `(char)65`
convert	GD.Convert
dict_to_inst	N/A
get_stack	System.Environment.StackTrace
inst_to_dict	N/A
len	N/A
load	GD.Load
preload	N/A
print_debug	N/A
print_stack	GD.Print(System.Environment.StackTrace)
range	GD.Range or System.Linq.Enumerable.Range
type_exists	ClassDB.ClassExists(type)

preload, as it works in GDScript, is not available in C#. Use GD.Load or ResourceLoader.Load instead.

`@export` annotation¶

Use the [Export] attribute instead of the GDScript @export annotation. This attribute can also be provided with optional PropertyHint and hintString parameters. Default values can be set by assigning a value.

Example:

using Godot;

public partial class MyNode : Node
{
    [Export]
    private NodePath _nodePath;

    [Export]
    private string _name = "default";

    [Export(PropertyHint.Range, "0,100000,1000,or_greater")]
    private int _income;

    [Export(PropertyHint.File, "*.png,*.jpg")]
    private string _icon;
}

`signal` keyword¶

Use the [Signal] attribute to declare a signal instead of the GDScript signal keyword. This attribute should be used on a delegate, whose name signature will be used to define the signal. The delegate must have the EventHandler suffix, an event will be generated in the class with the same name but without the suffix, use that event's name with EmitSignal.

[Signal]
delegate void MySignalEventHandler(string willSendAString);

@onready annotation¶

GDScript has the ability to defer the initialization of a member variable until the ready function is called with @onready (cf. @onready annotation). For example:

@onready var my_label = get_node("MyLabel")

However C# does not have this ability. To achieve the same effect you need to do this.

private Label _myLabel;

public override void _Ready()
{
    _myLabel = GetNode<Label>("MyLabel");
}

Singletons¶

Singletons are available as static classes rather than using the singleton pattern. This is to make code less verbose than it would be with an Instance property.

Example:

Input.IsActionPressed("ui_down")

However, in some very rare cases this is not enough. For example, you may want to access a member from the base class GodotObject, like Connect. For such use cases we provide a static property named Singleton that returns the singleton instance. The type of this instance is GodotObject.

Example:

Input.Singleton.JoyConnectionChanged += Input_JoyConnectionChanged;

String¶

Use System.String (string). Most of Godot's String methods have an equivalent in System.String or are provided by the StringExtensions class as extension methods.

Example:

string text = "Get up!";
string[] bigrams = text.Bigrams(); // ["Ge", "et", "t ", " u", "up", "p!"]

Strings are immutable in .NET, so all methods that manipulate a string don't modify the original string and return a newly created string with the modifications applied. To avoid creating multiple string allocations consider using a StringBuilder.

List of Godot's String methods and their equivalent in C#:

GDScript	C#
begins_with	string.StartsWith
bigrams	StringExtensions.Bigrams
bin_to_int	StringExtensions.BinToInt
c_escape	StringExtensions.CEscape
c_unescape	StringExtensions.CUnescape
capitalize	StringExtensions.Capitalize
casecmp_to	StringExtensions.CasecmpTo or StringExtensions.CompareTo (Consider using string.Equals or string.Compare)
chr	N/A
contains	string.Contains
count	StringExtensions.Count (Consider using RegEx)
countn	StringExtensions.CountN (Consider using RegEx)
dedent	StringExtensions.Dedent
ends_with	string.EndsWith
erase	string.Remove (Consider using StringBuilder to manipulate strings)
find	StringExtensions.Find (Consider using string.IndexOf or string.IndexOfAny)
findn	StringExtensions.FindN (Consider using string.IndexOf or string.IndexOfAny)
format	Use $ string interpolation
get_base_dir	StringExtensions.GetBaseDir
get_basename	StringExtensions.GetBaseName
get_extension	StringExtensions.GetExtension
get_file	StringExtensions.GetFile
get_slice	N/A
get_slice_count	N/A
get_slicec	N/A
hash	StringExtensions.Hash (Consider using object.GetHashCode unless you need to guarantee the same behavior as in GDScript)
hex_decode	StringExtensions.HexDecode (Consider using System.Convert.FromHexString)
hex_to_int	StringExtensions.HexToInt (Consider using int.Parse or long.Parse with System.Globalization.NumberStyles.HexNumber)
humanize_size	N/A
indent	StringExtensions.Indent
insert	string.Insert (Consider using StringBuilder to manipulate strings)
is_absolute_path	StringExtensions.IsAbsolutePath
is_empty	string.IsNullOrEmpty or string.IsNullOrWhiteSpace
is_relative_path	StringExtensions.IsRelativePath
is_subsequence_of	StringExtensions.IsSubsequenceOf
is_subsequence_ofn	StringExtensions.IsSubsequenceOfN
is_valid_filename	StringExtensions.IsValidFileName
is_valid_float	StringExtensions.IsValidFloat (Consider using float.TryParse or double.TryParse)
is_valid_hex_number	StringExtensions.IsValidHexNumber
is_valid_html_color	StringExtensions.IsValidHtmlColor
is_valid_identifier	StringExtensions.IsValidIdentifier
is_valid_int	StringExtensions.IsValidInt (Consider using int.TryParse or long.TryParse)
is_valid_ip_address	StringExtensions.IsValidIPAddress
join	string.Join
json_escape	StringExtensions.JSONEscape
left	StringExtensions.Left (Consider using string.Substring or string.AsSpan)
length	string.Length
lpad	string.PadLeft
lstrip	string.TrimStart
match	StringExtensions.Match (Consider using RegEx)
matchn	StringExtensions.MatchN (Consider using RegEx)
md5_buffer	StringExtensions.Md5Buffer (Consider using System.Security.Cryptography.MD5.HashData)
md5_text	StringExtensions.Md5Text (Consider using System.Security.Cryptography.MD5.HashData with StringExtensions.HexEncode)
naturalnocasecmp_to	N/A (Consider using string.Equals or string.Compare)
nocasecmp_to	StringExtensions.NocasecmpTo or StringExtensions.CompareTo (Consider using string.Equals or string.Compare)
num	float.ToString or double.ToString
num_int64	int.ToString or long.ToString
num_scientific	float.ToString or double.ToString
num_uint64	uint.ToString or ulong.ToString
pad_decimals	StringExtensions.PadDecimals
pad_zeros	StringExtensions.PadZeros
path_join	StringExtensions.PathJoin
repeat	Use string constructor or a StringBuilder
replace	string.Replace or RegEx
replacen	StringExtensions.ReplaceN (Consider using string.Replace or RegEx)
rfind	StringExtensions.RFind (Consider using string.LastIndexOf or string.LastIndexOfAny)
rfindn	StringExtensions.RFindN (Consider using string.LastIndexOf or string.LastIndexOfAny)
right	StringExtensions.Right (Consider using string.Substring or string.AsSpan)
rpad	string.PadRight
rsplit	N/A
rstrip	string.TrimEnd
sha1_buffer	StringExtensions.Sha1Buffer (Consider using System.Security.Cryptography.SHA1.HashData)
sha1_text	StringExtensions.Sha1Text (Consider using System.Security.Cryptography.SHA1.HashData with StringExtensions.HexEncode)
sha256_buffer	StringExtensions.Sha256Buffer (Consider using System.Security.Cryptography.SHA256.HashData)
sha256_text	StringExtensions.Sha256Text (Consider using System.Security.Cryptography.SHA256.HashData with StringExtensions.HexEncode)
similarity	StringExtensions.Similarity
simplify_path	StringExtensions.SimplifyPath
split	StringExtensions.Split (Consider using string.Split)
split_floats	StringExtensions.SplitFloat
strip_edges	StringExtensions.StripEdges (Consider using string.Trim, string.TrimStart or string.TrimEnd)
strip_escapes	StringExtensions.StripEscapes
substr	StringExtensions.Substr (Consider using string.Substring or string.AsSpan)
to_ascii_buffer	StringExtensions.ToAsciiBuffer (Consider using System.Text.Encoding.ASCII.GetBytes)
to_camel_case	StringExtensions.ToCamelCase
to_float	StringExtensions.ToFloat (Consider using float.TryParse or double.TryParse)
to_int	StringExtensions.ToInt (Consider using int.TryParse or long.TryParse)
to_lower	string.ToLower
to_pascal_case	StringExtensions.ToPascalCase
to_snake_case	StringExtensions.ToSnakeCase
to_upper	string.ToUpper
to_utf16_buffer	StringExtensions.ToUtf16Buffer (Consider using System.Text.Encoding.UTF16.GetBytes)
to_utf32_buffer	StringExtensions.ToUtf32Buffer (Consider using System.Text.Encoding.UTF32.GetBytes)
to_utf8_buffer	StringExtensions.ToUtf8Buffer (Consider using System.Text.Encoding.UTF8.GetBytes)
to_wchar_buffer	StringExtensions.ToUtf16Buffer in Windows and StringExtensiont.ToUtf32Buffer in other platforms
trim_prefix	StringExtensions.TrimPrefix
trim_suffix	StringExtensions.TrimSuffix
unicode_at	string[int] indexer
uri_decode	StringExtensions.URIDecode (Consider using System.Uri.UnescapeDataString)
uri_encode	StringExtensions.URIEncode (Consider using System.Uri.EscapeDataString)
validate_node_name	StringExtensions.ValidateNodeName
xml_escape	StringExtensions.XMLEscape
xml_unescape	StringExtensions.XMLUnescape

List of Godot's PackedByteArray methods that create a String and their C# equivalent:

GDScript	C#
get_string_from_ascii	StringExtensions.GetStringFromAscii (Consider using System.Text.Encoding.ASCII.GetString)
get_string_from_utf16	StringExtensions.GetStringFromUtf16 (Consider using System.Text.Encoding.UTF16.GetString)
get_string_from_utf32	StringExtensions.GetStringFromUtf32 (Consider using System.Text.Encoding.UTF32.GetString)
get_string_from_utf8	StringExtensions.GetStringFromUtf8 (Consider using System.Text.Encoding.UTF8.GetString)
hex_encode	StringExtensions.HexEncode (Consider using System.Convert.ToHexString)

.NET contains many path utility methods available under the System.IO.Path class that can be used when not dealing with Godot paths (paths that start with res:// or user://)

NodePath¶

The following method was converted to a property with a different name:

GDScript	C#
`is_empty()`	`IsEmpty`

Signal¶

The following methods were converted to properties with their respective names changed:

GDScript	C#
`get_name()`	`Name`
`get_object()`	`Owner`

The Signal type implements the awaitable pattern which means it can be used with the await keyword. See await keyword.

Instead of using the Signal type, the recommended way to use Godot signals in C# is to use the generated C# events. See C# signals.

Callable¶

The following methods were converted to properties with their respective names changed:

GDScript	C#
`get_object()`	`Target`
`get_method()`	`Method`

Currently C# supports Callable if one of the following holds:

Callable was created using the C# Callable type.
Callable is a basic version of the engine's Callable. Custom Callables are unsupported. A Callable is custom when any of the following holds:
- Callable has bound information (Callables created with bind/unbind are unsupported).
- Callable was created from other languages through the GDExtension API.

Some methods such as bind and unbind are not implemented, use lambdas instead:

string name = "John Doe";
Callable callable = Callable.From(() => SayHello(name));

void SayHello(string name)
{
    GD.Print($"Hello {name}");
}

The lambda captures the name variable so it can be bound to the SayHello method.

RID¶

This type is named Rid in C# to follow the .NET naming convention.

The following methods were converted to properties with their respective names changed:

GDScript	C#
`get_id()`	`Id`
`is_valid()`	`IsValid`

Basis¶

Structs cannot have parameterless constructors in C#. Therefore, new Basis() initializes all primitive members to their default value. Use Basis.Identity for the equivalent of Basis() in GDScript and C++.

The following method was converted to a property with a different name:

GDScript	C#
`get_scale()`	`Scale`

Transform2D¶

Structs cannot have parameterless constructors in C#. Therefore, new Transform2D() initializes all primitive members to their default value. Please use Transform2D.Identity for the equivalent of Transform2D() in GDScript and C++.

The following methods were converted to properties with their respective names changed:

GDScript	C#
`get_rotation()`	`Rotation`
`get_scale()`	`Scale`
`get_skew()`	`Skew`

Transform3D¶

Structs cannot have parameterless constructors in C#. Therefore, new Transform3D() initializes all primitive members to their default value. Please use Transform3D.Identity for the equivalent of Transform3D() in GDScript and C++.

The following methods were converted to properties with their respective names changed:

GDScript	C#
`get_rotation()`	`Rotation`
`get_scale()`	`Scale`

Rect2¶

The following field was converted to a property with a slightly different name:

GDScript	C#
`end`	`End`

The following method was converted to a property with a different name:

GDScript	C#
`get_area()`	`Area`

Rect2i¶

This type is named Rect2I in C# to follow the .NET naming convention.

The following field was converted to a property with a slightly different name:

GDScript	C#
`end`	`End`

The following method was converted to a property with a different name:

GDScript	C#
`get_area()`	`Area`

AABB¶

This type is named Aabb in C# to follow the .NET naming convention.

The following method was converted to a property with a different name:

GDScript	C#
`get_volume()`	`Volume`

Quaternion¶

Structs cannot have parameterless constructors in C#. Therefore, new Quaternion() initializes all primitive members to their default value. Please use Quaternion.Identity for the equivalent of Quaternion() in GDScript and C++.

Projection¶

Structs cannot have parameterless constructors in C#. Therefore, new Projection() initializes all primitive members to their default value. Please use Projection.Identity for the equivalent of Projection() in GDScript and C++.

Color¶

Structs cannot have parameterless constructors in C#. Therefore, new Color() initializes all primitive members to their default value (which represents the transparent black color). Please use Colors.Black for the equivalent of Color() in GDScript and C++.

The global Color8 method to construct a Color from bytes is available as a static method in the Color type.

The Color constants are available in the Colors static class as readonly properties.

The following method was converted to a property with a different name:

GDScript	C#
`get_luminance()`	`Luminance`

The following method was converted to a method with a different name:

GDScript	C#
`html(String)`	`FromHtml(ReadOnlySpan<char>)`

The following methods are available as constructors:

GDScript	C#
`hex(int)`	`Color(uint)`
`hex64(int)`	`Color(ulong)`

Array¶

The equivalent of packed arrays are System.Array.

Dictionary¶

Use Godot.Collections.Dictionary for an untyped Variant dictionary. Godot.Colelctions.Dictionary<TKey, TValue> is a type-safe wrapper around Godot.Collections.Dictionary.

Variant¶

Godot.Variant is used to represent Godot's native Variant type. Any Variant-compatible type can be converted from/to it.

Communicating with other scripting languages¶

This is explained extensively in Cross-language scripting.

`await` keyword¶

Something similar to GDScript's await keyword can be achieved with C#'s await keyword.

The await keyword in C# can be used with any awaitable expression. It's commonly used with operands of the types Task, Task<TResult>, ValueTask, or ValueTask<TResult>.

An expression t is awaitable if one of the following holds:

t is of compile-time type dynamic.
t has an accessible instance or extension method called GetAwaiter with no parameters and no type parameters, and a return type A for which all of the following hold:
- A implements the interface System.Runtime.CompilerServices.INotifyCompletion.
- A has an accessible, readable instance property IsCompleted of type bool.
- A has an accessible instance method GetResult with no parameters and no type parameters.

An equivalent of awaiting a signal in GDScript can be achieved with the await keyword and GodotObject.ToSignal.

Example:

await ToSignal(timer, "timeout");
GD.Print("After timeout");

C# API differences to GDScript¶

General differences¶

Global scope¶

Constants¶

Math functions¶

Random functions¶

Other functions¶

Tips¶

Full list of equivalences¶

@export annotation¶

signal keyword¶

@onready annotation¶

Singletons¶

String¶

NodePath¶

Signal¶

Callable¶

RID¶

Basis¶

Transform2D¶

Transform3D¶

Rect2¶

Rect2i¶

AABB¶

Quaternion¶

Projection¶

Color¶

Array¶

Dictionary¶

Variant¶

Communicating with other scripting languages¶

await keyword¶

`@export` annotation¶

`signal` keyword¶

`await` keyword¶