C# API differences to GDScript

Esta é uma lista (incompleta) de diferenças entre as APIs do C# e do GDScript.

General differences

As explained in the Noções básicas de C#, C# generally uses PascalCase instead of the snake_case used in GDScript and C++.

Global scope

Funções globais e algumas constantes tiveram que ser movidas para classes, já que o C# não permite declará-las em namespaces. A maioria das constantes globais foram movidas para seus próprios enums.

Constantes

As constantes globais foram movidas para seus próprios enums. Por exemplo, constantes ERR_* foram movidas para o enum Error.

Special cases:

GDScript

C#

SPKEY

GD.SpKey

TYPE_*

Variant.Type enum

OP_*

Variant.Operator enum

Math functions

Funções matemáticas globais, como abs, acos, asin, atan e atan2 estão localizadas sob Mathf como Abs, Acos, Asin, Atan and Atan2. A constante PI pode ser encontrada como Mathf.Pi.

Random functions

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

Other functions

Many other global functions like print and var2str are located under GD. Example: GD.Print and GD.Var2Str.

Exceções:

GDScript

C#

weakref(obj)

Object.WeakRef(obj)

is_instance_valid(obj)

Object.IsInstanceValid(obj)

Dicas

Às vezes pode ser útil usar a diretiva using static. Esta diretiva permite acessar os membros e tipos aninhados de uma classe sem especificar o nome da classe.

Exemplo:

using static Godot.GD;

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

A palavra-chave Export

Use o atributo [Export] em vez da palavra-chave de GDScript export. Este atributo também pode ser utilizado com parâmetros opcionais PropertyHint e hintString . Os valores padrão podem ser definidos atribuindo um valor.

Exemplo:

using Godot;

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

A palavra-chave Signal

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.

[Signal]
delegate void MySignal(string willSendsAString);

Veja também: C# signals.

onready keyword

GDScript has the ability to defer the initialization of a member variable until the ready function is called with onready (cf. onready keyword). 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 estão disponíveis como classes estáticas em vez de usar o padrão singleton. Isto é para fazer o código menos prolixo que seria com uma propriedade Instanciada.

Exemplo:

Input.IsActionPressed("ui_down")

No entanto, em alguns casos muito raros, isso não é suficiente. Por exemplo, você pode querer acessar um membro da classe base Godot.Object, como Connect. Para tais casos de uso, fornecemos uma propriedade estática chamada Singleton que retorna a instância singleton. O tipo desta instância é Godot.Object.

Exemplo:

Input.Singleton.Connect("joy_connection_changed", this, nameof(Input_JoyConnectionChanged));

String

Use System.String (string). Quase todos os métodos Godot String são fornecidos pela classe StringExtensions como métodos de extensão.

Exemplo:

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

Os seguintes métodos foram convertidos em propriedades com seus respectivos nomes alterados:

GDScript

C#

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

The following methods were converted to a property with a different name:

GDScript

C#

length()

Length

length_squared()

LengthSquared

Vetor

This is temporary. PoolArrays will need their own types to be used the way they are meant to.

GDScript

C#

Array

Godot.Collections.Array

PoolIntArray

int[]

PoolByteArray

byte[]

PoolFloatArray

float[]

PoolStringArray

String[]

PoolColorArray

Color[]

PoolVector2Array

Vector2[]

PoolVector3Array

Vector3[]

Godot.Collections.Array<T> is a type-safe wrapper around Godot.Collections.Array. Use the Godot.Collections.Array<T>(Godot.Collections.Array) constructor to create one.

Dicionário

Use Godot.Collections.Dictionary.

Godot.Collections.Dictionary<T> is a type-safe wrapper around Godot.Collections.Dictionary. Use the Godot.Collections.Dictionary<T>(Godot.Collections.Dictionary) constructor to create one.

Variant

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

Comunicando com outras linguagens de script

Isso é explicado extensivamente em Cross-language scripting.

Yield

Algo semelhante ao yield do GDScript com um único parâmetro pode ser obtido com a palavra-chave `yield <https://docs.microsoft.com/en-US/dotnet/csharp/language-reference/keywords/yield> `_ do C#.

O equivalente a yield em um sinal pode ser obtido com async/await e Godot.Object.ToSignal.

Exemplo:

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

Outras diferenças

pré-carregamento, da forma que funciona no GDScript, não está disponível em C#. Ao invés disso, use GD.Load ou ResourceLoader.Load.

Outras diferenças:

GDScript

C#

Color8

Color.Color8

is_inf

float.IsInfinity

is_nan

float.IsNaN

dict2inst

TODO

inst2dict

TODO