Les bases du C#

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 6.x.NET incluant le support complet pour C# 8.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

Prérequis

Installez la dernière version stable de .NET Core SDK (3.1 au moment de la rédaction).

À partir de Godot 3.2.3, l'installation de Mono SDK n'est plus nécessaire, sauf si vous compilez le moteur vous même à partir du code source.

Godot regroupe les parties de Mono nécessaires pour exécuter des jeux déjà compilés, mais Godot n'inclut pas les outils nécessaires pour construire et compiler des jeux, tels que MSBuild. Ces outils doivent être installés séparément. Les outils requis sont inclus dans le SDK .NET Core. MSBuild est également inclus dans le SDK Mono, mais il ne peut pas construire des projets C# avec le nouveau format csproj, donc le SDK .NET Core est requis pour Godot 3.2.3+.

En résumé, vous devez avoir installé .NET Core SDK et la version de Godot compatible avec Mono.

Informations supplémentaires

Veillez à installer la version 64 bits du ou des SDK(s) si vous utilisez la version 64 bits de Godot.

Si vous construisez Godot à partir des sources, installez la dernière version stable de Mono, et assurez-vous de suivre les étapes pour activer le support de Mono dans votre construction comme indiqué dans la page Compilation avec Mono.

Configuration d'un éditeur externe

Le support du C# dans l'éditeur de script intégré de Godot est minimal. Envisagez 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 sélectionner un éditeur externe dans Godot, cliquez sur Éditeur → Paramètres de l'éditeur et faites défiler vers le bas, jusqu'à Mono. Sous Mono, cliquez sur Éditeur, et choisissez l'éditeur externe de votre choix. Godot supporte actuellement les éditeurs externes suivants :

  • Visual Studio 2019

  • Visual Studio Code

  • MonoDevelop

  • Visual Studio pour Mac

  • JetBrains Rider

Consultez les sections suivantes pour savoir comment configurer un éditeur externe :

JetBrains Rider

Après avoir lu la section "Prérequis", vous pouvez télécharger et installer JetBrains Rider.

Dans le menu Éditeur → Paramètres de l'éditeur de Godot :

  • Définissez Mono -> Editor -> External Editor sur JetBrains Rider.

  • Définissez Mono -> Builds -> Build Tool sur dotnet CLI.

Dans Rider :

  • Définissez MSBuild version sur .NET Core.

  • Installez le plugin Godot support.

Visual Studio Code

Après avoir lu la section "Prérequis", vous pouvez télécharger et installer Visual Studio Code (alias VS Code).

Dans le menu Éditeur → Paramètres de l'éditeur de Godot :

  • Définissez Mono -> Editor -> External Editor sur Visual Studio Code.

Dans Visual Studio Code :

Pour configurer un projet pour le débogage, ouvrez le dossier du projet Godot dans VS Code. Allez dans l'onglet Run et cliquez sur create a launch.json file. Sélectionnez C# Godot dans le menu déroulant. Maintenant, lorsque vous démarrez le débogueur dans VS Code, votre projet Godot s'exécutera.

Visual Studio (Windows uniquement)

Téléchargez et installez la dernière version de Visual Studio. Visual Studio inclura les SDK requis si vous avez sélectionné les charges de travail correctes, donc vous n'avez pas besoin d'installer manuellement les choses listées dans la section "Prérequis".

Lors de l'installation de Visual Studio, sélectionnez ces charges de travail :

  • Développement mobile avec .NET

  • Développement multiplateforme .NET Core

Dans le menu Éditeur → Paramètres de l'éditeur de Godot :

  • Définissez Mono -> Editor -> External Editor sur Visual Studio.

Ensuite, vous devez télécharger l'extension Godot Visual Studio depuis github ici. Double-cliquez sur le fichier téléchargé et suivez le processus d'installation.

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.

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

Gardez à l'esprit que la classe que vous souhaitez attacher à votre nœud doit avoir le même nom que le fichier .cs. Sinon, vous obtiendrez l'erreur suivante et vous ne pourrez pas exécuter la scène : "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 C# par rapport à GDScript.

Avertissement

Vous devez (re)construire les assemblages du projet chaque fois que vous voulez voir les nouvelles variables ou signaux exportés dans l'éditeur. Cette compilation peut être déclenchée manuellement en cliquant sur le mot Build dans le coin supérieur droit de l'éditeur. Vous pouvez également cliquer sur Mono au bas de la fenêtre de l'éditeur pour faire apparaître le panneau Mono, puis cliquer sur le bouton Build Project.

Vous devrez également reconstruire les assemblages de projet pour appliquer les changements dans les scripts "tool".

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.

  • 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 re-chargement à chaud, à l'exception des variables exportées.

  • Les scripts C# joints doivent se référer à une classe dont le nom de classe correspond au nom du fichier.

  • Il existe des méthodes telles que Get()/Set(), Call()/CallDeferred() et la méthode de connexion de signal Connect() qui reposent sur les conventions de nommage API snake_case de Godot. Ainsi, lorsque vous utilisez par exemple CallDeferred("AddChild"), AddChild ne fonctionnera pas car l'API attend la version originale snake_case add_child. Cependant, vous pouvez utiliser n'importe quelles propriétés ou méthodes personnalisées sans cette limitation.

L'exportation de projets Mono est prise en charge pour les plateformes de bureau (Linux, Windows et macOS), Android, HTML5 et iOS. La seule plateforme qui n'est pas encore prise en charge est UWP.

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>

À partir de Godot 3.2.3, Godot télécharge et configure automatiquement les paquets NuGet nouvellement ajoutés lors de la prochaine compilation du projet.

Profilage de votre code C#

  • Mono log profiler est disponible pour Linux et macOS. En raison d'un changement de Mono, il ne fonctionne pas sur Windows actuellement.

  • Un profiler Mono externe comme JetBrains dotTrace peut être utilisé comme décrit ici.