Work in progress
Godot documentation is being updated to reflect the latest changes in version
4.0. Some documentation pages may
still state outdated information. This banner will tell you if you're reading one of such pages.
The contents of this page are up to date. If you can still find outdated information, please open an issue.
Compiling with .NET¶
You can use
dotnet --infoto check which .NET SDK versions are installed.
Enable the .NET module¶
C# support for Godot has historically used the
Mono runtime instead of the
.NET Runtime and internally
many things are still named
mono instead of
otherwise referred to as
By default, the .NET module is disabled when building. To enable it, add the
module_mono_enabled=yes to the SCons command line, while otherwise
following the instructions for building the desired Godot binaries.
Generate the glue¶
Parts of the sources of the managed libraries are generated from the ClassDB.
These source files must be generated before building the managed libraries.
They can be generated by any .NET-enabled Godot editor binary by running it with
--headless --generate-mono-glue followed by the path to an
This path must be
modules/mono/glue in the Godot directory:
<godot_binary> --headless --generate-mono-glue modules/mono/glue
This command will tell Godot to generate the C# bindings for the Godot API at
modules/mono/glue/GodotSharp/GodotSharp/Generated, and the C# bindings for
the editor tools at
Once these files are generated, you can build Godot's managed libraries for all
the desired targets without having to repeat this process.
<godot_binary> refers to the editor binary you compiled with the .NET module
enabled. Its exact name will differ based on your system and configuration, but
should be of the form
bin/godot.windows.editor.x86_32.mono.exe. Be especially aware of the
.mono suffix! If you've previously compiled Godot without .NET support, you
might have similarly named binaries without this suffix. These binaries can't be
used to generate the .NET glue.
The glue sources must be regenerated every time the ClassDB-registered API changes. That is, for example, when a new method is registered to the scripting API or one of the parameters of such a method changes. Godot will print an error at startup if there is an API mismatch between ClassDB and the glue sources.
Building the managed libraries¶
Once you have generated the .NET glue, you can build the managed libraries with
If everything went well, the
GodotSharp directory, containing the managed
libraries, should have been created in the
By default, all development builds share a version number, which can
cause some issues with caching of the NuGet packages. To solve this
issue either use
GODOT_VERSION_STATUS to give every build a unique
version or delete
GodotNuGetFallbackFolder after every build to
clear the package cache.
Unlike "classical" Godot builds, when building with the .NET module enabled (and depending on the target platform), a data directory may be created both for the editor and for exported projects. This directory is important for proper functioning and must be distributed together with Godot. More details about this directory in Data directory.
--godot-platform=<platform> argument to control for which
platform specific the libraries are built. Omit this argument to build for the
This currently only controls the inclusion of the support for Visual Studio as an external editor, the libraries are otherwise identical.
The API assemblies, source generators, and custom MSBuild project SDK are distributed as NuGet packages. This is all transparent to the user, but it can make things complicated during development.
In order to use Godot with a development version of those packages, a local NuGet source must be created where MSBuild can find them. This can be done with the .NET CLI:
dotnet nuget add source ~/MyLocalNugetSource --name MyLocalNugetSource
The Godot NuGet packages must be added to that local source. Additionally, we must make sure there are no other versions of the package in the NuGet cache, as MSBuild may pick one of those instead.
In order to simplify this process, the
build_assemblies.py script provides
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local ~/MyLocalNugetSource
This option ensures the packages will be added to the specified local NuGet source and that conflicting versions of the package are removed from the NuGet cache. It's recommended to always use this option when building the C# solutions during development to avoid mistakes.
Double Precision Support (REAL_T_IS_DOUBLE)¶
When building Godot with double precision support, i.e. the
argument for scons, the managed libraries must be adjusted to match by passing
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local ~/MyLocalNugetSource --precision=double
# Build editor binary scons p=windows target=editor module_mono_enabled=yes # Build export templates scons p=windows target=template_debug module_mono_enabled=yes scons p=windows target=template_release module_mono_enabled=yes # Generate glue sources bin/godot.windows.editor.x86_64.mono --generate-mono-glue modules/mono/glue # Build .NET assemblies ./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin --godot-platform=windows
Example (Linux, *BSD)¶
# Build editor binary scons p=linuxbsd target=editor module_mono_enabled=yes # Build export templates scons p=linuxbsd target=template_debug module_mono_enabled=yes scons p=linuxbsd target=template_release module_mono_enabled=yes # Generate glue sources bin/godot.linuxbsd.editor.x86_64.mono --generate-mono-glue modules/mono/glue # Generate binaries ./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin --godot-platform=linuxbsd