Introduction

Avertissement

Le support du C# est une nouvelle fonctionnalité depuis Godot 3.0. Ainsi, il se peut que vous rencontriez encore des problèmes ou que vous trouviez des endroits où la documentation pourrait être améliorée. Merci de signaler les problèmes avec C# dans Godot sur la page Github du moteur de jeu. Et tout problème de documentation sur la page GitHub de la documentation.

Cette page fournit une brève introduction au C#, à la fois ce qu’il est et comment l’utiliser dans Godot. Après, vous pouvez regarder comment utiliser des fonctionnalités spécifiques à C#, lire les différences entre l’API C# et l’API GDScript et (re)visiter la section sur les scripts du tutoriel pas-à-pas.

C# est un langage de programmation de haut niveau développé par Microsoft. Dans Godot il est implémenté avec le framework Mono 5.x.NET incluant le support complet pour C# 7.0. Mono est une implémentation open source du Framework.NET de Microsoft basé sur les standards ECMA pour C# et le Common Language Runtime. Un bon point de départ pour vérifier ses capacités est la page Compatibilité dans la documentation Mono.

Note

Il ne s’agit pas d’un tutoriel complet sur le langage C# dans son ensemble. Si vous n’êtes pas déjà familier avec sa syntaxe ou ses fonctionnalités, consultez le guide Microsoft C# ou cherchez une introduction appropriée ailleurs.

Configurer C# pour Godot

Windows

Téléchargez et installez la dernière version de Visual Studio (pas Visual Studio Code), qui contient les utilitaires requis pour utiliser C# dans Godot. Si vous ne prévoyez pas d’utiliser l’EDI Visual Studio, vous pouvez télécharger uniquement les outils de création de`Visual Studio Build Tools <https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=15>`_ à la place. Assurez-vous d’avoir au moins le paquet de ciblage .NET Framework 4.5 installé, vous pouvez l’obtenir en utilisant n’importe lequel des installateurs mentionnés ci-dessus dans l’onglet « Composants individuels ».

macOS et Linux

Téléchargez et installez le dernière version de Mono SDK. A partir de Godot 3.1 beta 3, le version n’est plus importante, Godot apportant sa propre installation de Mono 5.18. Nous avons seulement besoin de l’installation de Mono pour NuGet et MSBuild, qui requièrent l’utilisation de C# dans Godot.

Note

Pour télécharger Mono sur macOS, utilisez le lien « Stable Channel » dans la page téléchargements de Mono. Le canal Visual Studio est une version antérieure de Mono et ne fonctionnera pas.

Informations supplémentaires :

Votre version de Godot doit avoir le support Mono activé, alors assurez-vous de télécharger la version Mono de Godot. Si vous compilez Godot à partir des sources, assurez-vous de suivre les étapes pour activer le support Mono dans votre compilation comme indiqué dans la page Compiling with Mono.

En résumé, vous devez avoir installé Visual Studio ou Mono (selon votre système d’exploitation) et la version avec Mono activé de Godot.

Configuration d’un éditeur externe

Bien que Godot ait son propre éditeur de scripts, son support pour C# est minimal, et il est recommandé d’utiliser un IDE ou un éditeur externe, tel que Microsoft Visual Studio Code, ou MonoDevelop. Ceux-ci fournissent l’auto-complétion, le débogage et d’autres fonctionnalités utiles lorsque vous travaillez avec C#. Pour le configurer dans Godot, cliquez sur Éditeur → Paramètres de l’éditeur et faites défiler vers le bas, jusqu’aux réglages Mono. Sous Mono, cliquez sur Éditeur, et sur cette page, choisissez l’éditeur externe de votre choix.

Note

Si vous utilisez Visual Studio Code, assurez-vous bien que vous téléchargiez et installiez l”extension C# pour permettre des fonctionnalités telles que IntelliSense et la surbrillance du code.

Création d’un script C#

Après avoir configuré avec succès C# pour Godot, vous devriez voir l’option suivante lorsque vous sélectionnez Attacher un script dans le menu contextuel d’un nœud de votre scène :

../../../_images/attachcsharpscript.png

Notez que bien que certaines spécificités changent, la plupart des choses fonctionnent de la même façon lorsque vous utilisez C# pour coder. Si vous êtes nouveau sur Godot, vous pouvez consulter les tutoriels sur Les scripts à ce stade. Bien que certains endroits dans la documentation manquent encore d’exemples C#, la plupart des choses peuvent être facilement transposées à partir de GDScript.

Mise en place du projet et flux de travail

Lorsque vous créez le premier script C#, Godot initialise les fichiers de projet C# pour votre projet Godot. Cela inclut la génération d’une solution C# (.sln) et d’un projet (.csproj) ainsi que de certains fichiers et dossiers utilitaires (.mono et Properties/AssemblyInfo.cs). Tous ces fichiers sauf .mono sont importants et doivent être conservés dans votre système de contrôle de version. .mono peut être ajouté en toute sécurité à la liste des ignorés de votre système de contrôle de version. Lors du dépannage, il est parfois utile de supprimer le dossier .mono et de le laisser se régénérer.

Notez qu’il y a actuellement des problèmes où le projet Godot et le projet C# ne restent pas synchronisés ; si vous supprimez, renommez ou déplacez des choses comme des scripts ou des nœuds, il se peut qu’ils ne correspondent plus dans le fichier du projet C#. Dans ce cas, il peut être utile d’éditer manuellement le fichier de projet C#.

Exemple : Si vous avez créé un script (par exemple Test.cs) et que vous le supprimez dans Godot, la compilation échouera parce que le fichier manquant est toujours attendu par le fichier de projet C#. Vous pouvez pour l’instant simplement ouvrir le .csproj et chercher ItemGroup, il devrait y avoir une ligne incluse comme ce qui suit :

<ItemGroup>
    <Compile Include="Test.cs" />
    <Compile Include="AnotherTest.cs" />
</ItemGroup>

Enlevez simplement cette ligne et votre projet devrait à nouveau compiler correctement. De même pour renommer et déplacer des choses, il suffit de les renommer et de les déplacer dans le fichier projet si nécessaire.

Exemple

Voici un script C# vierge avec quelques commentaires pour montrer comment il fonctionne.

using Godot;
using System;

public class YourCustomClass : Node
{
    // Member variables here, example:
    private int a = 2;
    private string b = "textvar";

    public override void _Ready()
    {
        // Called every time the node is added to the scene.
        // Initialization here.
        GD.Print("Hello from C# to Godot :)");
    }

    public override void _Process(float delta)
    {
        // Called every frame. Delta is time since the last frame.
        // Update game logic here.
    }
}

Comme vous pouvez le voir, les fonctions normalement de portée globale dans GDScript comme la fonction print de Godot sont disponibles dans la classe GD qui fait partie de l’espace de nom Godot. Pour une liste de méthodes dans la classe GD, voir les pages de référence des classes pour @GDScript et @GlobalScope.

Note

Keep in mind that the class you wish to attach to your node should have the same name as the .cs file. Otherwise, you will get the following error and won’t be able to run the scene: « Cannot find class XXX for script res://XXX.cs »

Différences générales entre C# et GDScript

L’API C# utilise le PascalCase au lieu du snake_case dans GDScript/C++. Dans la mesure du possible, les champs et les getters/setters ont été convertis en propriétés. En général, l’API Godot C# s’efforce d’être aussi idiomatique que possible.

Pour plus d’informations, voir la page Différences de l’API par rapport à GDScript.

Les pièges courants et les problèmes connus

Comme le support C# est plutôt nouveau pour Godot, il y a des petits problèmes et des choses qui doivent encore être ajustées. Voici une liste des problèmes les plus importants dont vous devriez être conscient lorsque vous vous plongez avec C# dans Godot, mais en cas de doute, jetez également un coup d’œil sur le tracker officiel des problèmes liés à Mono.

  • Comme expliqué ci-dessus, le projet C# n’est pas toujours synchronisé automatiquement lorsque des choses sont supprimées, renommées ou déplacées dans Godot (#12917).
  • L’écriture de plugins éditeur est possible, mais elle est actuellement assez compliquée.
  • L’état n’est actuellement ni sauvegardé, ni restauré lors d’un « hot-reloading », à l’exception des variables exportées.
  • L’exportation de projets Mono n’est prise en charge que pour les plates-formes de bureau (Linux, Windows et macOS). Android, iOS, HTML5 et UWP ne sont pas actuellement supportés (#20267, #20268 #20270 #20271).
  • Les scripts C# joints doivent se référer à une classe dont le nom de classe correspond au nom du fichier.

Performance du C# dans Godot

Selon quelques benchmarks préliminaires, la performance du C# dans Godot - bien que généralement du même ordre de grandeur - est approximativement ~4x celle du GDScript dans certains cas naïfs. Le C++ est encore un peu plus rapide ; les spécificités vont varier en fonction de votre cas d’utilisation. GDScript est probablement assez rapide pour la plupart des charges de travail des script en général. C# est plus rapide, mais nécessite une transformation des objets coûteuse lorsqu’il parle à Godot.

Utilisation des packages Nuget dans Godot

Les packages NuGet peuvent être installés et utilisés avec Godot, comme pour tout projet C#. De nombreux IDE peuvent ajouter des packages directement. Ils peuvent également être ajoutés manuellement en ajoutant la référence du package dans le fichier .csproj situé à la racine du projet :

    <ItemGroup>
        <PackageReference Include="Newtonsoft.Json" Version="11.0.2"/>
    </ItemGroup>
    ...
</Project>

Chaque fois que des packages sont ajoutés ou modifiés, exécutez nuget restore à la racine du répertoire du projet. Afin de vous assurer que les packages NuGet seront disponibles pour msbuild, exécutez :

msbuild /t:restore