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 the .NET SDK, previously known as the .NET Core SDK.

À 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 bundles the parts of Mono needed to run already compiled games. However, Godot does not bundle the tools required to build and compile games, such as MSBuild and the C# compiler. These are included in the .NET SDK, which needs to be installed separately.

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

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.
Définissez Mono -> Builds -> Build Tool sur dotnet CLI.

Dans Visual Studio Code :

Installez l'extension C#.
Installez l'extension Mono Debug.
Installez l'extension C# Tools for Godot.

Note

Si vous utilisez Linux vous devez installer le Mono SDK pour que l'extension des outils C# fonctionne.

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 Add Configuration.... Sélectionnez C# Godot dans le menu déroulant. Ouvrez les fichiers tasks.json et launch.json qui ont été créés. Modifiez le paramètre de l'exécutable dans launch.json et les paramètres de la commande dans tasks.json en fonction du chemin de votre exécutable Godot. 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.
Définissez Mono -> Builds -> Build Tool sur dotnet CLI.

Next, you can download the Godot Visual Studio extension from github here. Double click on the downloaded file and follow the installation process.

Note

The option to debug your game in Visual Studio may not appear after installing the extension. To enable debugging, there is a workaround for Visual Studio 2019. There is a separate issue about this problem in Visual Studio 2022.

Note

If you see an error like "Unable to find package Godot.NET.Sdk", your NuGet configuration may be incorrect and need to be fixed.

A simple way to fix the NuGet configuration file is to regenerate it. In a file explorer window, go to %AppData%\NuGet. Rename or delete the NuGet.Config file. When you build your Godot project again, the file will be automatically created with default values.

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 :

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 Langages de script à 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.