Skip to main content

🏁 Godot C# Setup Guide

If you have the .NET SDK installed, Godot 4 provides a pretty good out-of-the-box development experience — but you'll need to follow some additional steps if you want to configure your environment to simplify IDE integration and command-line usage.

Ready to make games with Godot and C#? Let's start by making sure your development environment is ready to go!

If you get stuck on a step or want to inform us about incorrect or outdated documentation, please join us on Discord.

tip

This guide is specific to Godot 4 — all Chickensoft packages have officially migrated to Godot 4.

📦 Installing the .NET SDK​

To use Godot 4, we recommend installing the .NET 8 SDK.

tip

You can install multiple versions of the .NET SDK. C# tooling is (generally) intelligent enough to pick the correct version based on the target framework of the project, the global.json file, and other settings in Godot. If you're running into issues with SDK resolution, feel free to reach out in Discord.

It probably won't hurt to install the .NET 6 SDK and/or .NET 7 SDK, too — having .NET 6, 7, and 8 will allow you to run a variety of C# projects and tools.

info

We often write file paths like ~/folder. The ~ is a shortcut for your home folder. On Windows, ~ expands to something like C:\Users\you. On macOS, ~ expands to /Users/you. On Linux, ~ expands to /home/you. For example, ~/Documents expands to C:\Users\you\Documents on Windows, /Users/you/Documents on macOS, and /home/you/Documents on Linux.

Use the Microsoft provided installer to install the .NET SDK on macOS. For more information about installing the .NET SDK on Mac, see Microsoft's article for Mac.

If you want to install the .NET SDK manually, you can find all available downloads here.

The .NET SDK installers and package managers tend to place it in a standard location on each platform — if you install it manually, make sure you make a note of where you installed it to. We'll need that later.

⏳ Version Control with Git​

You should absolutely be using a version control system to track your game's code and assets: specifically, git.

danger

🔥🔥🔥 Mistakes get made, tools can accidentally clear out files, scene references can get broken — bad stuff happens during the chaos of development.

Git allows you to go back in time and undo unwanted changes, which is invaluable if you'd prefer development not be nightmare-inducing 😱. It also lets you collaborate with others easily and store your code in GitHub, GitLab, and other such git-related services.

While learning git can seem daunting, it is absolutely your responsibility as a game developer to protect your valuable time and work, and using git is a mandatory part of the experience that enables you to do just that. Game development is extremely hard, so don't make it harder on yourself by leaving your work unprotected. 🔥🔥🔥

Be sure to bookmark the Undoing Changes in Git section to prevent panic during your next crisis. Messing up is not a matter of if, it's a matter of when — so be prepared.

Properly learning and using git is a skill that gradually accrues over a lifetime of development, but the basics aren't too hard, and using Visual Studio Code can allow you to do it without ever really having to touch a command-line, for the most part.

info

Even if you're already using git, but you're not entirely comfortable with it, take a look at the aforementioned git beginner guide — this is the best guide, in my opinion, and the one I recommend to junior engineers all the time. You can jump straight into the advanced tips for anything you might be unsure about.

🖥 Shell Environment​

Let's setup the shell environment to contain environment variables that point to the .NET SDK. This will allow you to run dotnet command line tool from anywhere. We will be using it to install GodotEnv to manage ours Godot installation, making Godot game development easier than ever.

info

👩‍💻 Which shell should I use?​

For the sake of consistency, Chickensoft officially recommends using a bash shell on every OS, especially if you are developing your game to be cross-platform on macOS, Windows, and Linux — which is pretty easy to do with Godot, once your environments are setup correctly.

Since a bash shell is not available on Windows by default, you can access one by installing git, which includes the Git Bash for Windows application. You can also configure the Windows Terminal (there's an option to add a Windows Terminal profile in the git installer) and VSCode to use bash by default.

Bash is a bit esoteric, but you can easily learn the basics of bash that you'll need pretty quickly. Or you can dive in and read the whole book on bash.

Once we do this, we'll be able to run Godot from a terminal and create the proper launch configurations for Visual Studio Code.

If ~/.zshrc doesn't exist, you'll need to create it.

tip

To toggle visibility of hidden files in the macOS Finder, press Cmd + Shift + . — it also works in file dialogs!

Add the following to your ~/.zshrc file:

# .NET SDK Configuration
export DOTNET_ROOT="/usr/local/share/dotnet"
export DOTNET_CLI_TELEMETRY_OPTOUT=1 # Disable analytics
export DOTNET_ROLL_FORWARD_TO_PRERELEASE=1

# Add the .NET SDK to the system paths so we can use the `dotnet` tool.
export PATH="$DOTNET_ROOT:$PATH"
export PATH="$DOTNET_ROOT/sdk:$PATH"
export PATH="$HOME/.dotnet/tools:$PATH"

# Run this if you ever run into errors while doing a `dotnet restore`
alias nugetclean="dotnet nuget locals --clear all"
info

Depending on how you install the .NET SDK, you may or may not need to add them to your path in ~/.bashrc (linux) or ~/.zshrc (macOS). You can run which dotnet in a bash shell to see if they're already in your path. If they are, remove the export PATH lines for them added previously. If it is not the case, you should use DOTNET_ROOT to point to your dotnet root directory as showed above.

Make sure the path to the .NET SDK matches where this tool was installed on your particular system, since it might be different if you installed it manually.

🤖 Installing Godot​

You can use Chickensoft's command-line tool, GodotEnv, to manage Godot versions locally on your machine (as well as manage Godot asset library addons in your project).

chickensoft-games/

GodotEnv

Manage Godot versions and addons from the command line on Windows, macOS, and Linux.
252Stars
6Forks
C#
info

Using GodotEnv to install and manage Godot on your system provides a number of advantages:

  • ✅ Automatically download, extract, and install any requested Godot 4.x+ version (with or without .NET support) from the Godot TuxFamily downloads mirror.

  • ✅ Automatically manage symlink on your system that point to the version of Godot you'd like to use. The symlink path never changes — just the version it points to.

    On Windows, maintaining symlinks requires administrator privileges, making it a hassle to manage by hand. GodotEnv integrates with Windows' User Access Control (UAC) to automatically request admin privileges when needed.

  • ✅ Adds a system GODOT environment variable that points to the symlink location, facilitating its usage through scripts.

  • ✅ Adds the GODOT pointed path to the system's PATH. Making initializing the Godot binary a breeze, just run godot to open the version managed by GodotEnv.

  • ✅ Standardizes installation locations across platforms and machines, making it easier to collaborate with other teammates.

  • ✅ Quickly change the system Godot version to any installed version, as well as listing all the installed versions.

To install GodotEnv, run the following:

dotnet tool install --global Chickensoft.GodotEnv

🦾 Installing with GodotEnv​

You can install Godot automatically by specifying a Godot version the way it appears here.

godotenv godot install 4.0.1

😓 Installing Manually​

If you're not convinced, you can always download Godot manually and install it wherever you'd like.

📍 Godot Installation Path​

If you're using GodotEnv, Godot versions will automatically be installed in the following locations:

LocationPath
Symlink/Users/{you}/.config/godotenv/godot/bin
Actual Path/Users/{you}/.config/godotenv/godot/versions/godot_dotnet_{version}/Godot_mono.app/Contents/MacOS/Godot
caution

All Chickensoft templates and VSCode launch configurations rely on an environment variable named GODOT that contains the path to the version of Godot you'd like to use.

GodotEnv will automatically update your environment variables by updating the ~/.zshrc file on macOS or the ~/.bashrc file on Linux to point to its symlink which in turn points to the active version of Godot. On Windows, GodotEnv will automatically attempt to update the environment variable with the relevant command prompt commands with requested admin privileges.

❗️ You will have to logout and login again after environment variables have been updated for all applications to see the updated values.

If you're not using GodotEnv or want to double check that the variable exists, please make sure you've setup the environment variables as follows:

In your ~/.zshrc file, make sure something like the following exists.

# This should be added to your ~/.zshrc file by GodotEnv automatically, but
# you can also add it manually and change the path of Godot to match
# your system.
export GODOT="/Users/{you}/.config/godotenv/godot/bin"

If you're installing manually, consider placing it in one of the following locations:

Move Godot to /Applications/Godot_mono.app. This is where all your other Mac apps are, anyways!

⌨️ Visual Studio Code​

All of Chickensoft's packages and templates are designed to work well with Visual Studio Code (VSCode).

You can download Visual Studio Code here.

🔌 VSCode Extensions​

At the very least, you'll need the ms-dotnettools.csharp extension. Chickensoft also recommends a handful of other extensions that make development easier.

💾 VSCode Settings for Godot and C#​

We need to turn OmniSharp back on — it should have never been turned off by default.

Open your VSCode Settings as a JSON file and add the following settings:

"dotnetAcquisitionExtension.enableTelemetry": false,
// Increases project compatibility with the C# extension.
"dotnet.preferCSharpExtension": true,

Chickensoft also recommends the following additional settings for a pleasant C# development experience:

"csharp.suppressHiddenDiagnostics": false,
// Draw a line between selected brackets so you can see blocks of code easier.
"editor.guides.bracketPairs": "active",

"[csharp]": {
  "editor.codeActionsOnSave": {
    "source.addMissingImports": "explicit",
    "source.fixAll": "explicit",
    "source.organizeImports": "explicit"
  },
  "editor.formatOnPaste": true,
  "editor.formatOnSave": true,
  "editor.formatOnType": true
},

// To make bash the default terminal on Windows, add these:
"terminal.integrated.defaultProfile.windows": "Git Bash",
"terminal.integrated.profiles.windows": {
  "Command Prompt": {
    "icon": "terminal-cmd",
    "path": [
      "${env:windir}\\Sysnative\\cmd.exe",
      "${env:windir}\\System32\\cmd.exe"
    ]
  },
  "Git Bash": {
    "icon": "terminal",
    "source": "Git Bash"
  },
  "PowerShell": {
    "icon": "terminal-powershell",
    "source": "PowerShell"
  }
}

Finally, C#'s semantic highlighting is a bit funky, so you can fix that by adding these color adjustments:

C# Semantic Syntax Highlighting Color Correction Settings
"editor.tokenColorCustomizations": {
  "[*Dark*]": {
    // Themes that include the word "Dark" in them.
    "textMateRules": [
      {
        "scope": "comment.documentation",
        "settings": {
          "foreground": "#608B4E"
        }
      },
      {
        "scope": "comment.documentation.attribute",
        "settings": {
          "foreground": "#C8C8C8"
        }
      },
      {
        "scope": "comment.documentation.cdata",
        "settings": {
          "foreground": "#E9D585"
        }
      },
      {
        "scope": "comment.documentation.delimiter",
        "settings": {
          "foreground": "#808080"
        }
      },
      {
        "scope": "comment.documentation.name",
        "settings": {
          "foreground": "#569CD6"
        }
      }
    ]
  },
  "[*Light*]": {
    // Themes that include the word "Light" in them.
    "textMateRules": [
      {
        "scope": "comment.documentation",
        "settings": {
          "foreground": "#008000"
        }
      },
      {
        "scope": "comment.documentation.attribute",
        "settings": {
          "foreground": "#282828"
        }
      },
      {
        "scope": "comment.documentation.cdata",
        "settings": {
          "foreground": "#808080"
        }
      },
      {
        "scope": "comment.documentation.delimiter",
        "settings": {
          "foreground": "#808080"
        }
      },
      {
        "scope": "comment.documentation.name",
        "settings": {
          "foreground": "#808080"
        }
      }
    ]
  },
  "[*]": {
    // Themes that don't include the word "Dark" or "Light" in them.
    // These are some bold colors that show up well against most dark and
    // light themes.
    //
    // Change them to something that goes well with your preferred theme :)
    "textMateRules": [
      {
        "scope": "comment.documentation",
        "settings": {
          "foreground": "#0091ff"
        }
      },
      {
        "scope": "comment.documentation.attribute",
        "settings": {
          "foreground": "#8480ff"
        }
      },
      {
        "scope": "comment.documentation.cdata",
        "settings": {
          "foreground": "#0091ff"
        }
      },
      {
        "scope": "comment.documentation.delimiter",
        "settings": {
          "foreground": "#aa00ff"
        }
      },
      {
        "scope": "comment.documentation.name",
        "settings": {
          "foreground": "#ef0074"
        }
      }
    ]
  }
},

✨ Creating Godot Projects​

Chickensoft provides a few dotnet new templates to help you quickly create a C# projects for use with Godot 4.

Now that you've configured your environment (and hopefully rebooted since then), you should be able to use the dotnet tool from your terminal to be able to install Chickensoft's development templates.

dotnet new install Chickensoft.GodotGame
dotnet new install Chickensoft.GodotPackage

🎮 Creating a Godot Game​

The GodotGame template allows you to quickly generate a game with debug launch configurations for VSCode, testing (locally and on CI/CD), code coverage, dependency update checks, and spell checking!

chickensoft-games/

GodotGame

C# game template for Godot 4 with debug launch configurations, testing (locally and on CI/CD), code coverage, dependency update checks, and spell check working out-of-the-box!
150Stars
12Forks
Shell

To create a new game, simply run the following commands and open the resulting directory in Godot and VSCode.

dotnet new chickengame --name "MyGameName" --param:author "My Name"

cd MyGameName
dotnet restore

🥳 At last — you're finally ready to make a game!

📦 Creating a Reusable Nuget Package​

If you want to share compiled source code between projects or allow others to use your code in their projects, you can release a Nuget package.

Using the GodotPackage template allows you to setup a package with continuous integration, auto-formatting, debugger profiles for VSCode, and a pre-configured unit test project.

chickensoft-games/

GodotPackage

A .NET template for quickly creating a C# nuget package for use with Godot 4.
25Stars
3Forks
Shell
dotnet new --install Chickensoft.GodotPackage

dotnet new chickenpackage --name "MyPackageName" --param:author "My Name"

cd MyPackageName
/path/to/godot4 --headless --build-solutions --quit
dotnet build

Open the new project in VSCode and use the provided launch configurations to debug your application.

tip

If you need to share code and other resource files like scenes, textures, music, and anything else that isn't a C# source file, you should use a Godot Asset Library package instead. Chickensoft's GodotEnv CLI tool allows you to easily install and manage addons in your project.

chickensoft-games/

GodotEnv

Manage Godot versions and addons from the command line on Windows, macOS, and Linux.
252Stars
6Forks
C#