Fonctionnalités

Cette page donne un aperçu des fonctionnalités couramment utilisées de C# et de Godot, et de la façon dont elles sont utilisées ensemble.

Conversion de type et Casting

C# est un langage à typage statique. Par conséquent, vous ne pouvez pas faire ce qui suit :

var mySprite = GetNode("MySprite");
mySprite.SetFrame(0);

La méthode GetNode() retourne une instance de Node. Vous devez explicitement la convertir dans le type dérive que vous désirez. Dans cet exemple, il s’agit de Sprite.

Pour cela, en C#, vous disposez de plusieurs options.

Casting et vérification de type

Envoie InvalidCastException si le nœud retourné ne peut pas être concertit en Sprite. Utilisez le à la place de l’opérateur « as » si vous êtes presque sûr qu’il n’échouera pas.

Sprite mySprite = (Sprite)GetNode("MySprite");
mySprite.SetFrame(0);

Utilisation de l’opérateur AS

L’opérateur as retourne null si le nœud ne peut pas être convertit en Sprite, et pour cette raison il ne peut pas être utilisé avec les types de valeurs.

Sprite mySprite = GetNode("MySprite") as Sprite;
// Only call SetFrame() if mySprite is not null
mySprite?.SetFrame(0);

Utilisation des méthodes génériques

Des méthodes génériques sont également fournies pour rendre ce type de conversion transparent.

GetNode <T> () lance le nœud avant de le retourner. Il enverra une InvalidCastException si le nœud ne peut pas être converti au type désiré.

Sprite mySprite = GetNode<Sprite>("MySprite");
mySprite.SetFrame(0);

GetNodeOrNull<T>T>()`` utilise l’opérateur as et retourne null si le nœud ne peut pas être converti au type désiré.

Sprite mySprite = GetNodeOrNull<Sprite>("MySprite");
// Only call SetFrame() if mySprite is not null
mySprite?.SetFrame(0);

Vérification du type à l’aide de l’opérateur IS

Pour vérifier si le nœud peut être convertit en Sprite, vous pouvez utiliser l’opérateur is. L’opérateur is retourne false si le nœud ne peut pas être convertit en Sprite, sinon il retourne true.

if (GetNode("MySprite") is Sprite)
{
    // Yup, it's a sprite!
}

Pour un contrôle de type plus avancé, vous pouvez regarder dans Pattern Matching.

Signaux C#

Pour un exemple complet de C#, voir la section Manipuler un signal dans le tutoriel Pas à pas Les scripts.

Déclarer un signal en C# se fait avec l’attribut [Signal] sur un delegate.

[Signal]
delegate void MySignal();

[Signal]
delegate void MySignalWithArguments(string foo, int bar);

Ces signaux peuvent ensuite être connectés soit dans l’éditeur, soit à partir du code avec Connect. Si vous souhaitez connecter un signal dans l’éditeur, vous devez (re)construire les assemblys du projet pour voir le nouveau signal. Cela peut être déclenché manuellement en cliquant sur le bouton « Construire » dans le coin supérieur droit de la fenêtre de l’éditeur.

public void MyCallback()
{
    GD.Print("My callback!");
}

public void MyCallbackWithArguments(string foo, int bar)
{
    GD.Print("My callback with: ", foo, " and ", bar, "!");
}

public void SomeFunction()
{
    instance.Connect("MySignal", this, "MyCallback");
    instance.Connect(nameof(MySignalWithArguments), this, "MyCallbackWithArguments");
}

L’émission de signaux se fait avec la méthode EmitSignal.

public void SomeFunction()
{
    EmitSignal(nameof(MySignal));
    EmitSignal("MySignalWithArguments", "hello there", 28);
}

Notez que vous pouvez toujours faire référence à un nom de signal avec le mot-clé  » nameof  » (appliqué sur le délégué lui-même).

Il est possible de lier des valeurs lors de l’établissement d’une connexion en passant un tableau d’objets.

public int Value { get; private set; } = 0;

private void ModifyValue(int modifier)
{
    Value += modifier;
}

public void SomeFunction()
{
    var plusButton = (Button)GetNode("PlusButton");
    var minusButton = (Button)GetNode("MinusButton");

    plusButton.Connect("pressed", this, "ModifyValue", new object[] { 1 });
    minusButton.Connect("pressed", this, "ModifyValue", new object[] { -1 });
}

Les signaux supportent les paramètres et les valeurs liées de tous les types intégrés et les classes dérivées de Godot.Object. Par conséquent, tout Node ou Reference sera automatiquement compatible mais les objets de données personnalisés devront hériter de Godot.Object ou l’une de ses sous-classes.

public class DataObject : Godot.Object
{
    public string Field1 { get; set; }
    public string Field2 { get; set; }
}

Enfin, les signaux peuvent être créés en appelant AddUserSignal, mais sachez que celui-ci doit être exécuté avant toute utilisation desdits signaux (avec Connect ou EmitSignal).

public void SomeFunction()
{
    AddUserSignal("MyOtherSignal");
    EmitSignal("MyOtherSignal");
}

Preprocessor defines

Godot has a set of defines that allow you to change your C# code depending on the environment you are compiling to.

Note

If you created your project before Godot 3.2, you have to modify or regenerate your csproj file to use this feature (compare <DefineConstants> with a new 3.2+ project).

Exemples

For example, you can change code based on the platform:

    public override void _Ready()
    {
#if GODOT_SERVER
        // Don't try to load meshes or anything, this is a server!
        LaunchServer();
#elif GODOT_32 || GODOT_MOBILE || GODOT_WEB
        // Use simple objects when running on less powerful systems.
        SpawnSimpleObjects();
#else
        SpawnComplexObjects();
#endif
    }

Or you can detect which engine your code is in, useful for making cross-engine libraries:

    public void MyPlatformPrinter()
    {
#if GODOT
        GD.Print("This is Godot.");
#elif UNITY_5_3_OR_NEWER
        print("This is Unity.");
#else
        throw new InvalidWorkflowException("Only Godot and Unity are supported.");
#endif
    }

Full list of defines

  • GODOT is always defined for Godot projects.
  • One of GODOT_64 or GODOT_32 is defined depending on if the architecture is 64-bit or 32-bit.
  • One of GODOT_X11, GODOT_WINDOWS, GODOT_OSX, GODOT_ANDROID, GODOT_HTML5, or GODOT_SERVER depending on the OS. These names may change in the future. These are created from the get_name() method of the :ref:OS <class_OS> singleton, but not every possible OS the method returns is an OS that Godot with Mono runs on.

When exporting, the following may also be defined depending on the export features:

  • One of GODOT_PC, GODOT_MOBILE, or GODOT_WEB depending on the platform type.
  • One of GODOT_ARM64_V8A or GODOT_ARMEABI_V7A on Android only depending on the architecture.
  • One of GODOT_S3TC, GODOT_ETC, or GODOT_ETC2 depending on the texture compression type.
  • Any custom features added in the export menu will be capitalized and prefixed: foo -> GODOT_FOO.