API differences to GDScript

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

General differences

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

Global scope

Available under Godot.GD. Some things were moved to their own classes, like Math and Random. See below.

Global functions like print, var2str and weakref are located under GD in C#.

ERR_* constants were moved to Godot.Error.

Math

Math functions, like abs, acos, asin, atan and atan2, are located under Mathf as Abs, Acos, Asin, Atan and Atan2, instead of in global scope. PI is Mathf.Pi

Random

Random functions, like rand_range and rand_seed, are located under Random, so use Random.RandRange instead of rand_range.

Export keyword

Use the [Export] attribute instead of the GDScript export keyword.

Signal keyword

Use the [Signal] attribute instead of the GDScript signal keyword. This attribute should be used on a delegate, whose name signature will be used to define the signal.

[Signal]
delegate void MySignal(string willSendsAString);

See also: C# signals

Singletons

Singletons provide static methods rather than using the singleton pattern in C#. This is to make code less verbose and similar to GDScript. Example:

Input.IsActionPressed("ui_down")

String

Use System.String (string). All the Godot String methods are provided by the StringExtensions class as extension methods. Example:

string upper = "I LIKE SALAD FORKS";
string lower = upper.ToLower();

There are a few differences, though:

  • erase: Strings are immutable in C#, so we cannot modify the string passed to the extension method. For this reason, Erase was added as an extension method of StringBuilder instead of string. Alternatively, you can use string.Remove.
  • IsSubsequenceOf/IsSubsequenceOfi: An additional method is provided, which is an overload of IsSubsequenceOf, allowing you to explicitly specify case sensitivity:
str.IsSubsequenceOf("ok"); // Case sensitive
str.IsSubsequenceOf("ok", true); // Case sensitive
str.IsSubsequenceOfi("ok"); // Case insensitive
str.IsSubsequenceOf("ok", false); // Case insensitive
  • Match/Matchn/ExprMatch: An additional method is provided besides Match and Matchn, which allows you to explicitly specify case sensitivity:
str.Match("*.txt"); // Case sensitive
str.ExprMatch("*.txt", true); // Case sensitive
str.Matchn("*.txt"); // Case insensitive
str.ExprMatch("*.txt", false); // Case insensitive

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_origin() Origin
get_rotation() Rotation
get_scale() Scale

Plane

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

GDScript C#
center() Center

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

Quat

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

Array

This is temporary. Array is ref-counted, so it will need its own type that wraps the native side. PoolArrays will also need their own type to be used the way they are meant to.

GDScript C#
Array object[]
PoolIntArray int[]
PoolByteArray byte[]
PoolFloatArray float[]
PoolStringArray String[]
PoolColorArray Color[]
PoolVector2Array Vector2[]
PoolVector3Array Vector3[]

In some exceptional cases, a raw array (type[]) may be required instead of a List.

Dictionary

This is temporary. Array is ref-counted, so it will need its own type that wraps the native side.

Use Dictionary<object, object>.

Variant

System.Object (object) is used instead of Variant.

Communicating with other scripting languages

The methods object Object.call(string method, params object[] args), object Object.get(string field) and object Object.set(string field, object value) are provided to communicate with instances of other scripting languages via the Variant API.

Other differences

preload, assert and yield, as they work in GDScript, are currently not available in C#.

Other differences:

GDScript C#
Color8 Color.Color8
is_inf float.IsInfinity
is_nan float.IsNaN
dict2inst ? TODO
inst2dict ? TODO
load GD.load, which is the same as ResourceLoader.load