Game Csharp Godot

C# in Godot 4.3+

This skill covers C#-specific conventions, API differences from GDScript, project setup, and interop patterns for Godot 4.3+ with the GodotSharp NuGet package. All examples are C# only.

Related skills: csharp-signals for C# signal patterns, godot-project-setup for C# project scaffolding, godot-testing for C# testing with gdUnit4, gdextension for native C++ when C# is not enough, multithreading for C# concurrency.

When to Use

• You are developing a Godot 4.3+ project and want to write gameplay code in C# instead of GDScript.
• You need strong typing, IDE tooling, or want to integrate existing .NET libraries.
• You require performance-critical systems (physics, AI, procedural generation) that benefit from compiled C# code.
• You are hitting GDScript interop boundaries and need marshalling guidance.

Do Not Use

• For quick editor plugins or @tool scripts where hot-reloading and minimal compile time matter more than performance.
• When the target platform does not support the .NET runtime required by GodotSharp (e.g., certain restricted web/mobile environments without .NET support).
• If the team is unfamiliar with C# and the project timeline does not allow a learning curve.
• Warning: Avoid using async void for logic that requires error handling; use async Task to prevent silent crashes.

Prerequisites

• Godot 4.3+ with .NET support enabled (download the .NET version of the Godot editor).
• .NET 8.0 SDK or newer installed on the host machine.
• An IDE with Godot C# support: JetBrains Rider (2023.3+), VS Code (C# Dev Kit + Godot Tools), or Visual Studio (Godot extension, Windows only).
• Windows host is primary (PowerShell). All path examples assume Windows conventions.

Procedure

1. Create the C# Project

1. Open Godot 4.3+ and create or open a project.
2. Create a new C# script via Script > New Script > C#. Godot auto-generates the .csproj and .sln.
3. Do not edit the generated .csproj file structure manually — let the editor manage it. Only edit to add NuGet packages.
4. Open the generated .sln (not just the folder) in your IDE for full solution resolution.

MyProject/
├── MyProject.csproj          # Auto-generated, edit only for NuGet packages
├── MyProject.sln             # Auto-generated solution file
├── project.godot
└── scripts/
    └── Player.cs

2. Configure the .csproj for NuGet and .NET 8

1. Open MyProject.csproj.
2. Ensure TargetFramework is net8.0 or newer.
3. Add any third-party NuGet packages inside <ItemGroup>.

<Project Sdk="Godot.NET.Sdk/4.3.0">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  </ItemGroup>
</Project>

4. Run dotnet restore or let the IDE restore automatically after editing.

3. Write a C# Script — The partial class Requirement

Every class that extends a Godot type must be declared partial. This is not optional. Godot uses C# source generators to emit signal registration, property binding, and RPC code alongside your class. Source generators require partial to inject into the same class declaration.

// CORRECT
public partial class Player : CharacterBody2D { }

// WRONG — will cause source generator errors
public class Player : CharacterBody2D { }

Error when forgotten:

Error CS0260: Missing partial modifier on declaration of type 'Player';
another partial declaration of this type exists.

Or the class compiles but signals and [Export] properties silently fail to register. This applies to every class in the inheritance chain that extends a Godot type, including intermediate base classes.

4. Follow Naming Conventions

Always match GodotSharp property and method names exactly — they are PascalCase translations of the GDScript snake_case names (e.g. is_on_floor() → IsOnFloor()).

5. Declare and Emit Signals

Signals require a delegate declaration with the [Signal] attribute. The delegate name must end with EventHandler.

using Godot;

public partial class Player : CharacterBody2D
{
    [Signal] public delegate void HealthChangedEventHandler(int newHealth);
    [Signal] public delegate void DiedEventHandler();

    private int _health = 100;

    public void TakeDamage(int amount)
    {
        _health -= amount;
        EmitSignal(SignalName.HealthChanged, _health);  // Use SignalName.X, not a string
        if (_health <= 0)
            EmitSignal(SignalName.Died);
    }
}

Connecting and disconnecting:

// Connect with +=
player.HealthChanged += OnHealthChanged;
player.Died += OnPlayerDied;

// Disconnect with -=
player.HealthChanged -= OnHealthChanged;
player.Died -= OnPlayerDied;

private void OnHealthChanged(int newHealth)
{
    GD.Print($"Health changed to {newHealth}");
}

private void OnPlayerDied()
{
    GD.Print("Player has died, triggering game over sequence.");
}

For full signal patterns including one-shot connections, static typed signals, and cross-language signal wiring, load the csharp-signals skill.

6. Use Async / Await

GDScript's await maps to C#'s await ToSignal(...). Godot signals return a SignalAwaiter compatible with C# await.

public async void StartCutscene()
{
    await ToSignal(GetTree().CreateTimer(2.0), Timer.SignalName.Timeout);

    var anim = GetNode<AnimationPlayer>("AnimationPlayer");
    anim.Play("intro");
    await ToSignal(anim, AnimationPlayer.SignalName.AnimationFinished);

    GD.Print("Cutscene complete");
}

For CPU-bound work, use Task.Run — but never touch Godot objects from a non-main thread:

public async Task LoadHeavyData()
{
    // Off main thread: pure C# computation only
    var result = await Task.Run(() => ComputeSomethingExpensive());

    // Back on main thread: safe to use Godot API
    ApplyResult(result);
}

private int ComputeSomethingExpensive()
{
    // No Godot API calls here
    return Enumerable.Range(0, 1_000_000).Sum();
}

GDScript await equivalents:

7. GDScript Interop

Calling GDScript from C#:

GodotObject enemy = GetNode("Enemy");

// Call a GDScript method
enemy.Call("take_damage", 25);

// Get a GDScript property
float health = enemy.Get("health").AsSingle();

// Set a GDScript property
enemy.Set("is_stunned", true);

Calling C# from GDScript — if a C# class is registered as [GlobalClass], GDScript can instantiate and use it directly:

[GlobalClass]
public partial class WeaponData : Resource
{
    [Export] public float Damage { get; set; } = 10f;
    [Export] public float Cooldown { get; set; } = 0.5f;
}

# GDScript — works because WeaponData is a [GlobalClass]
var data := WeaponData.new()
data.damage = 50.0

Non-[GlobalClass] C# types are not visible to GDScript by name but can still be passed as Variant/Object references.

8. C# vs GDScript Syntax Quick Reference

Examples

Variant Marshalling Gotchas

Performance: C# vs GDScript

Guidance:

• Use C# for systems with tight loops: physics solvers, procedural generation, AI decision trees, data processing.
• Use GDScript for editor plugins, @tool scripts, and rapid iteration on gameplay logic.
• Mixing languages in the same project is supported — interop cost is minimal for occasional cross-language calls.
• Avoid Godot.Collections.Array for hot paths; prefer typed arrays (Array<T>) or native C# arrays (T[]) converted at boundaries.
• StringName lookups are O(1) but StringName construction is not — cache them if created frequently.

Pitfalls

Verification

1. Build check: Run dotnet build in the project root. Verify it completes without warnings regarding target framework compatibility.

   dotnet build
   

2. Source generator check: Open the .sln in your IDE and build. Verify no source-generator errors appear (no CS0260 missing partial modifier errors).

3. Runtime registration check: Execute a sample scene that uses a partial class, exported properties, and a custom signal. Confirm:

   • [Export] properties appear in the Godot inspector.
   • Custom signals appear in the node's Signals tab.
   • EmitSignal(SignalName.X) triggers connected handlers.

4. Interop check: If using GDScript interop, verify Call, Get, and Set marshal values correctly by printing received values on both sides.

5. Thread safety check: If using Task.Run, confirm no Godot API calls occur inside the callback — all engine calls must happen on the main thread.

6. Final checklist:

• Every class extending a Godot type is declared partial
• Method names match GodotSharp PascalCase (e.g. _Ready, _PhysicsProcess, IsOnFloor())
• [Export] properties are PascalCase and use property syntax ({ get; set; })
• Signal delegates end with EventHandler and use EmitSignal(SignalName.X)
• Signals connected with += and disconnected with -= when no longer needed
• await ToSignal(...) used for Godot signals — not raw Task.Delay for game timing
• Godot.Collections.Array/Dictionary used at Godot API boundaries, not System.Collections types
• IsInstanceValid(obj) checked before using any potentially freed Godot object
• StringName instances cached if constructed in loops or frequently called methods
• No Godot API calls inside Task.Run(...) callbacks — all engine calls happen on the main thread
• .csproj opened via the .sln file in the IDE for full solution resolution
• C# used for computation-heavy systems; GDScript retained for editor tooling and @tool scripts

Related Skills

• csharp-signals – detailed patterns for typed signals and cross-language wiring. Load when you need one-shot connections, static typed signals, or complex signal routing.
• godot-project-setup – initial project configuration, export presets, and platform targets. Load when scaffolding a new Godot C# project.
• godot-testing – unit and integration testing of C# scripts with gdUnit4. Load when writing tests for C# gameplay code.
• gdextension – when native C++ extensions are required beyond C# capabilities. Load when C# performance is insufficient.
• multithreading – advanced threading models and synchronization in Godot C#. Load when implementing concurrent systems.