Introduction

    C# support is a new feature available since Godot 3.0. As such, you may still run into some issues, or find spots where the documentation could be improved. Please report issues with C# in Godot on the , and any documentation issues on the documentation GitHub page.

    This page provides a brief introduction to C#, both what it is and how to use it in Godot. Afterwards, you may want to look at , read about the differences between the C# and the GDScript API and (re)visit the of the step-by-step tutorial.

    C# is a high-level programming language developed by Microsoft. In Godot, it is implemented with the Mono 5.x .NET framework, including full support for C# 7.0. Mono is an open source implementation of Microsoft’s .NET Framework based on the ECMA standards for C# and the Common Language Runtime. A good starting point for checking its capabilities is the Compatibility page in the Mono documentation.

    Note

    This is not a full-scale tutorial on the C# language as a whole. If you aren’t already familiar with its syntax or features, see the or look for a suitable introduction elsewhere.

    Download and install the latest version of Visual Studio (not Visual Studio Code), which contains utilities required to use C# in Godot. If you don’t plan on using the Visual Studio IDE, you can download just the instead. Make sure you at least have the .NET Framework 4.5 targeting pack installed, you can get it using any of the installers mentioned above inside the “Individual components” tab.

    Download and install the latest version of the Mono SDK. As of Godot 3.1 beta 3, the version number doesn’t matter since Godot bundles its own Mono 5.18 installation. We only need the Mono installation for NuGet and MSBuild which are required to use C# in Godot.

    Note

    To download Mono on macOS, use the “Stable Channel” link from the . The Visual Studio channel is an earlier version of Mono and will not work.

    In summary, you must have installed Visual Studio or Mono (depending on your operating system) and the Mono-enabled version of Godot.

    Configuring an external editor

    C# support in Godot’s 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.

    Note

    If you are using Visual Studio Code, ensure you download and install the to enable features like syntax highlighting and IntelliSense.

    Creating a C# script

    After you successfully set up C# for Godot, you should see the following option when selecting in the context menu of a node in your scene:

    Note that while some specifics change, most concepts work the same when using C# for scripting. If you’re new to Godot, you may want to follow the tutorials on Scripting at this point. While some places in the documentation still lack C# examples, most concepts can be transferred easily from GDScript.

    When you create the first C# script, Godot initializes the C# project files for your Godot project. This includes generating a C# solution (.sln) and a project file (.csproj), as well as some utility files and folders (.mono and Properties/AssemblyInfo.cs). All of these but .mono are important and should be committed to your version control system. can be safely added to the ignore list of your VCS. When troubleshooting, it can sometimes help to delete the .mono folder and let it regenerate.

    Note that currently, there are some issues where Godot and the C# project don’t stay in sync; if you delete, rename or move a C# script, the change may not be reflected in the C# project file. In cases like this, you will have to edit the C# project file manually.

    Simply remove that line and your project should build correctly again. Same for renaming and moving things, simply rename and move them in the project file if needed.

    Example

    Here’s a blank C# script with some comments to demonstrate how it works.

    As you can see, functions normally in global scope in GDScript like Godot’s print function are available in the class which is part of the Godot namespace. For a list of methods in the GD class, see the class reference pages for and @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”

    General differences between C# and GDScript

    The C# API uses PascalCase instead of snake_case in GDScript/C++. Where possible, fields and getters/setters have been converted to properties. In general, the C# Godot API strives to be as idiomatic as is reasonably possible.

    For more information, see the page.

    As C# support is quite new in Godot, there are some growing pains and things that need to be ironed out. Below is a list of the most important issues you should be aware of when diving into C# in Godot, but if in doubt, also take a look over the official issue tracker for Mono issues.

    • As explained above, the C# project isn’t always kept in sync automatically when things are deleted, renamed or moved in Godot ().
    • Writing editor plugins is possible, but it is currently quite convoluted.
    • State is currently not saved and restored when hot-reloading, with the exception of exported variables.
    • Exporting Mono projects is only supported for desktop platforms (Linux, Windows and macOS). Android, iOS, HTML5 and UWP are not currently supported (#20267, #20270 ).
    • Attached C# scripts should refer to a class that has a class name that matches the file name.

    Performance of C# in Godot

    According to some preliminary benchmarks, the performance of C# in Godot — while generally in the same order of magnitude — is roughly ~4× that of GDScript in some naive cases. C++ is still a little faster; the specifics are going to vary according to your use case. GDScript is likely fast enough for most general scripting workloads. C# is faster, but requires some expensive marshalling when talking to Godot.

    Using NuGet packages in Godot

    Whenever packages are added or modified, run nuget restore in the root of the project directory. To ensure that NuGet packages will be available for msbuild to use, run: