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

Install the latest stable version of .NET Core SDK (3.1 as of writing).

From Godot 3.2.3 onwards, installing Mono SDK is not a requirement anymore, except it is required if you are building the engine from source.

Godot bundles the parts of Mono needed to run already compiled games, however Godot does not include the tools required to build and compile games, such as MSBuild. These tools need to be installed separately. The required tools are included in the .NET Core SDK. MSBuild is also included in the Mono SDK, but it can't build C# projects with the new csproj format, therefore .NET Core SDK is required for Godot 3.2.3+.

In summary, you must have installed .NET Core SDK and the Mono-enabled version of Godot.

Informations supplémentaires

Be sure to install the 64-bit version of the SDK(s) if you are using the 64-bit version of Godot.

If you are building Godot from source, install the latest stable version of Mono, and make sure to follow the steps to enable Mono support in your build as outlined in the Compilation avec Mono page.

Configuration d'un éditeur externe

C# support in Godot's built-in script editor is minimal. Consider using an external IDE or editor, such as Visual Studio Code or MonoDevelop. These provide autocompletion, debugging, and other useful features for C#. To select an external editor in Godot, click on Editor → Editor Settings and scroll down to Mono. Under Mono, click on Editor, and select your external editor of choice. Godot currently supports the following external editors:

  • Visual Studio 2019

  • Visual Studio Code

  • MonoDevelop

  • Visual Studio pour Mac

  • JetBrains Rider

See the following sections for how to configure an external editor:

JetBrains Rider

After reading the "Prerequisites" section, you can download and install JetBrains Rider.

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to JetBrains Rider.

  • Set Mono -> Builds -> Build Tool to dotnet CLI.

Dans Rider :

  • Set MSBuild version to .NET Core.

  • Installez le plugin Godot support.

Visual Studio Code

After reading the "Prerequisites" section, you can download and install Visual Studio Code (aka VS Code).

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to Visual Studio Code.

In Visual Studio Code:

Next, follow the instructions found in the Configuration de Visual Studio Code pour le débogage section below.

Visual Studio (Windows only)

Download and install the latest version of Visual Studio. Visual Studio will include the required SDKs if you have the correct workloads selected, so you don't need to manually install the things listed in the "Prerequisites" section.

While installing Visual Studio, select these workloads:

  • Mobile development with .NET

  • .NET Core cross-platform development

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to Visual Studio.

Next, follow the instructions found in the Configuration de VS 2019 pour le débogage section below.

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

Si vous utilisez C#, vous devez (re)compiler les assemblages du projet chaque fois que vous voulez voir de nouvelles variables d'exportation ou des nouveaux signaux dans l'éditeur. Cette compilation peut être déclenchée manuellement en cliquant sur le mot Mono au bas de la fenêtre de l'éditeur pour afficher le panneau Mono, puis en cliquant 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.

Exporting Mono projects is supported for desktop platforms (Linux, Windows and macOS), Android, HTML5, and iOS. The only platform not supported yet is 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

Pour configurer le débogage, ouvrez Visual Studio Code et téléchargez l'extension Mono Debug de Microsoft et l'extension Godot d'Ignacio. Ensuite, ouvrez le dossier du projet Godot dans VS Code. Allez dans l'onglet Exécuter et cliquez sur créer un fichier launch.json. 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écute.