Fonctionnalités C#

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> () convertit 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>() 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 en 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");
}

Définition Préprocesseur

Godot a un jeu de "defines" permettant de changer de code C# selon l’environnement pour lequel vous compilez.

Note

Si vous avez créé votre projet avant Godot 3.2, vous devez modifier ou re-générer votre fichier csproj pour utiliser cette fonctionnalité (comparez <DefineConstants> avec un nouveau projet 3.2+).

Exemples

Par exemple, vous pouvez changer de code, selon la plateforme :

    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
    }

Ou vous pouvez détecter quel moteur votre code utilise, utile pour créer des librairies cross-engine :

    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
    }

Liste complète des définitions

  • GODOT est toujours défini dans un project Godot.
  • GODOT_64 ou GODOT_32 est défini selon que l'architecture est 64-bit ou 32-bit.
  • GODOT_X11, GODOT_WINDOWS, GODOT_OSX, GODOT_ANDROID, GODOT_IOS, GODOT_HTML5, ou GODOT_SERVER est défini selon l'OS. Ces noms sont éventuellement amenés à changer dans le futur. Ils sont créer depuis la méthode get_name() du singleton :ref:OS <class_OS>, mais tous les OS potentiellement retournés ne sont pas des OS sur lesquels Godot peut fonctionner avec Mono.

Quand vous exportez, les choses suivantes peuvent également être définies selon les caractéristiques d'exportation :

  • Un des GODOT_PC, GODOT_MOBILE, ou GODOT_WEB selon le type de plateforme.
  • Un des GODOT_ARM64_V8A ou GODOT_ARMEABI_V7A sur Android seulement, selon l'architecture.
  • Un de GODOT_ARM64 ou GODOT_ARMV7 sur iOS uniquement en fonction de l'architecture.
  • N’importe lequel de GODOT_S3TC, GODOT_ETC, et GODOT_ETC2 selon le type de compression des textures.
  • Toute caractéristique ajoutée dans le menu d'exportation sera capitalisée et préfixée : foo -> GODOT_FOO.

Pour voir un projet d’exemple, voyez la démo de système d’exploitation de test : https://github.com/godotengine/godot-demo-projects/tree/master/misc/os_test