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
engine GitHub page,
and any documentation issues on the
documentation GitHub page.

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
Microsoft C# guide
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
Visual Studio Build Tools
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 Mono Downloads Page.
The Visual Studio channel is an earlier version of Mono and
will not work.

Your Godot version must have Mono support enabled,
so make sure to download the Mono version of Godot.
If you are building Godot from source, make sure to follow the steps to
enable Mono support in your build as outlined in the
Compiling with Mono page.

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

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 C# extension
to enable features like syntax highlighting and IntelliSense.

After you successfully set up C# for Godot, you should see the following option
when selecting Attachscript 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. .mono 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.

For example, if you created a script (e.g. Test.cs) and delete it in Godot,
compilation will fail because the missing file is still expected to be there
by the C# project file. For now, you can simply open up the .csproj file
and look for the ItemGroup, there should be a line included
like the following:

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

usingGodot;usingSystem;publicclassYourCustomClass:Node{// Member variables here, example:privateinta=2;privatestringb="textvar";publicoverridevoid_Ready(){// Called every time the node is added to the scene.// Initialization here.GD.Print("Hello from C# to Godot :)");}publicoverridevoid_Process(floatdelta){// Called every frame. Delta is time since the last frame.// Update game logic here.}}

As you can see, functions normally in global scope in GDScript like Godot’s
print function are available in the GD class which is part of
the Godot namespace. For a list of methods in the GD class, see the
class reference pages for
@GDScript and @GlobalScope.

Note

Keep in mind that the class you wish to attach to your node should be
named 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”

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.

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
(#12917).

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,
#20268#20270#20271).

Attached C# scripts should refer to a class that has a class name
that matches the file name.

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.

NuGet packages can be installed and used with Godot,
as with any C# project. Many IDEs are able to add packages directly.
They can also be added manually by adding the package reference in
the .csproj file located in the project root: