Up to date

This page is up to date for Godot 4.1. If you still find outdated information, please open an issue.

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:

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:

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

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

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;
}

See also: C# exports.

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

See also: C# signals.

@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#:

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

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

Signal

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

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:

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:

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:

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:

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:

Rect2

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

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

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:

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

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:

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:

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

The following methods are available as constructors:

Array

The equivalent of packed arrays are System.Array.

See also PackedArray in C#.

Use Godot.Collections.Array for an untyped Variant array. Godot.Collections.Array<T> is a type-safe wrapper around Godot.Collections.Array.

See also Array in C#.

Dictionary

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

See also Dictionary in C#.

Variant

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

See also: C# Variant.

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");