C# basics

Introduction

Warning

.NET support has been heavily modified between Godot 3 and 4. 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.

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 how to use specific features, read about the differences between the C# and the GDScript API, and (re)visit the Scripting section of the step-by-step tutorial.

C# is a high-level programming language developed by Microsoft. In Godot, it is implemented with .NET 6.0.

Attention

Projects written in C# using Godot 4.x currently cannot be exported to Android, iOS and web platforms. To use C# on those platforms, use Godot 3 instead.

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.

Prerequisites

Godot bundles the parts of .NET 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, and need to be installed separately.

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

Download and install the latest stable version of the SDK from the .NET download page.

Important

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, make sure to follow the steps to enable .NET support in your build as outlined in the Compiling with .NET page.

Configuring an external editor

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 Dotnet. Under Dotnet, click on Editor, and select your external editor of choice. Godot currently supports the following external editors:

  • Visual Studio 2019

  • Visual Studio 2022

  • Visual Studio Code

  • MonoDevelop

  • Visual Studio for 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 Dotnet -> Editor -> External Editor to JetBrains Rider.

In Rider:

  • Set MSBuild version to .NET Core.

  • Install the Godot support plugin.

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 Dotnet -> Editor -> External Editor to Visual Studio Code.

In Visual Studio Code:

  • Install the C# extension.

Note

If you are using Linux you need to install the Mono SDK for the C# tools plugin to work.

To configure a project for debugging, you need a tasks.json and launch.json file in the .vscode folder with the necessary configuration. An example configuration can be found here . In the launch.json file, make sure the program parameter in the relevant configuration points to your Godot executable, either by changing it to the path of the executable or by defining a GODOT4 environment variable that points to the executable. Now, when you start the debugger in Visual Studio Code, your Godot project will run.

Note

There is also a C# Tools for Godot Visual Studio Code extension, that is meant to make this setup easier and to provide further useful tools. But it is not yet updated to work with Godot 4.

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 this workload:

  • .NET desktop development

In Godot's Editor → Editor Settings menu:

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

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.

Creating a C# script

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

../../../_images/attachcsharpscript.webp

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 languages at this point. While some documentation pages still lack C# examples, most notions can be transferred from GDScript.

Project setup and workflow

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 (.godot/mono). All of these but .godot/mono are important and should be committed to your version control system. Everything under .godot can be safely added to the ignore list of your VCS. When troubleshooting, it can sometimes help to delete the .godot/mono folder and let it regenerate.

Example

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

using Godot;

public partial 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(double delta)
    {
        // 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 static class which is part of the Godot namespace. For a full list of methods