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

Windows (Visual Studio)

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 à 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".

Windows (JetBrains Rider)

JetBrains Rider est livré avec MSBuild, aucune autre dépendance n'est requise. Assurez-vous de définir les préférences suivantes de cette manière :

  • Dans Godot :

    • Éditeur externe Mono pour JetBrains Rider
    • Outils de compilation Mono pour JetBrains Mono.
  • Dans Rider :

    • Définissez MSBuild version pour qu'elle soit fournie avec Rider ou .NET Core.
    • Installez le plugin Godot support.

macOS et Linux

Téléchargez et installez le dernière version de Mono SDK. A partir de Godot 3.1 beta 3, la 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 sont requit pour utiliser 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 channel 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 Compilation avec 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

Le support du C# dans l'éditeur de script 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'aux réglages Mono. Sous Mono, cliquez sur Éditeur, et sur cette page, 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

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.

Note

Si vous utilisez Visual Studio 2019, vous devez suivre les instructions figurant dans la section "Configurez VS2019 for Debugging" ci-dessous.

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.

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.

Depuis Godot 3.2.2, l'exportation de projets Mono est prise en charge pour les plateformes de bureau (Linux, Windows et macOS), Android, HTML5 et iOS. La seule plate-forme non 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</Version>
        </PackageReference>
    </ItemGroup>
    ...
</Project>

Note

Par défaut, les outils tel que NuGet ajoutent un attribut Version au nœud `PackageReference`. Vous devez manuellement créer une Version de nœud, comme montré ci-dessus. La version de MSBuild utilisée le requiert. (Cela sera corrigé dans Godot 4.0.)

Chaque fois que des packages sont ajoutés ou modifiés, exécutez nuget restore (pas dotnet 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

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.

Configuration de VS 2019 pour le débogage

Note

Godot a un support intégré pour les flux de travail impliquant plusieurs IDE C# populaires. La prise en charge intégrée de Visual Studio sera incluse dans les prochaines versions, mais en attendant, les étapes ci-dessous peuvent vous permettre de configurer VS 2019 pour une utilisation avec les projets Godot C#.

  1. Installez VS 2019 avec .NET desktop development et Desktop development with C++ sélectionnées.
  2. Assurez-vous que Xamarin n'est pas installé Ne choisissez pas le Mobile development with .NET. Xamarin modifie les DLL utilisées par MonoDebugger, ce qui interrompt le débogage.
  3. Installez l'extension VSMonoDebugger.
  4. Dans VS 2019 --> Extensions --> Mono --> Settings :
    • Sélectionnez Debug/Deploy to local Windows.
    • Laissez Local Deploy Path vide.
    • Définissez le Mono Debug Port sur le port dans Godot --> Project --> Project Settings --> Mono --> Debugger Agent.
    • Sélectionnez également Wait for Debugger dans les options de Mono Godot. Cet addon Godot peut être utile.
  5. Exécutez le jeu dans Godot. Il devrait se bloquer sur l'écran de démarrage Godot pendant qu'il attend que votre débogueur se connecte.
  6. Dans VS 2019, ouvrez votre projet et choisissez Extensions --> Mono --> Attach to Mono Debugger.

Configuration de Visual Studio Code pour le débogage

To configure debugging, open Visual Studio Code and download the Mono Debug extension from Microsoft and the Godot extension by Ignacio. Then open the Godot project folder in VS Code. Go to the Run tab and click on create a launch.json file. Select C# Godot from the dropdown menu. Now, when you start the debugger in VS Code your Godot project will run.