---
name: csharp-godot
description: Use when working with C# in Godot — conventions, GodotSharp API differences from GDScript, project setup, and interop
title: csharp-godot
canonical_url: https://skilld.dev/gh/jame581/godotprompter/csharp-godot
last_updated: 2026-11-13T22:06:02.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [references/gdscript-interop.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/csharp-godot/references/gdscript-interop.md).
>
> If the user asked to install this Skill, run `npx skilld install jame581/godotprompter/csharp-godot`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/csharp-godot`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/jame581/godotprompter/csharp-godot) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/csharp-godot`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/csharp-godot --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/csharp-godot --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# C# in Godot 4.3+

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

> **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.

---

## 1. C# vs GDScript Syntax Comparison

| GDScript | C# Equivalent | Notes |
|---|---|---|
| `var x = 5` | `var x = 5;` or typed `int x = 5;` | C# `var` infers type at compile time |
| `func MyMethod() -> void:` | `public void MyMethod() { }` | Methods are PascalCase in C# |
| `signal health_changed(amount: int)` | `[Signal] delegate void HealthChangedEventHandler(int amount);` | Must use `EventHandler` suffix |
| `@export var speed: float = 100.0` | `[Export] public float Speed { get; set; } = 100f;` | PascalCase, property syntax |
| `@onready var label = $Label` | `private Label _label;` + `_label = GetNode<Label>("Label");` in `_Ready()` | No `@onready` equivalent; use `_Ready()` |
| `match value:` | `switch (value) { case X: break; }` | C# switch also supports pattern matching |
| `class_name MyClass` | `[GlobalClass] public partial class MyClass : GodotObject { }` | Requires `[GlobalClass]` attribute |
| `extends Node` | `public partial class MyScript : Node { }` | Inheritance via `:` |
| `preload("res://scene.tscn")` | `GD.Load<PackedScene>("res://scene.tscn")` | Loaded at runtime, not compile time |
| `push_error("msg")` | `GD.PushError("msg");` | Prints to Godot error log |
| `print("msg")` | `GD.Print("msg");` | Also: `GD.PrintS()`, `GD.PrintT()` |
| `node is CharacterBody2D` | `node is CharacterBody2D` | Same keyword, same semantics |
| `node as CharacterBody2D` | `node as CharacterBody2D` | Returns `null` on failure in both |
| `await signal_name` | `await ToSignal(source, SignalName.X);` | Must use `ToSignal()` wrapper |
| `Array` | `Godot.Collections.Array` | Not `System.Collections.Generic.List<T>` |
| `Dictionary` | `Godot.Collections.Dictionary` | Not `System.Collections.Generic.Dictionary<K,V>` |

---

## 2. Project Setup

### .csproj and Solution

Godot auto-generates the `.csproj` when you create the first C# script via **Script > New Script > C#**. Do not edit the generated file structure manually — let the editor manage it.

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

### NuGet Packages

Add packages in `MyProject.csproj` inside `<ItemGroup>`:

```xml
<Project Sdk="Godot.NET.Sdk/4.3.0">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
  </PropertyGroup>
  <ItemGroup>
    <!-- Example: add a third-party NuGet package -->
    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
  </ItemGroup>
</Project>
```

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

> **Changed in Godot 4.8:** The minimum target framework is **.NET 10** (`net10.0`). Godot 4.4 to 4.7 generate `net8.0` as above (Android `net9.0` from 4.5; 4.3 used `net6.0`); on 4.8 set `net10.0` and a 4.8 `Godot.NET.Sdk`. The 4.8 editor raises an older `TargetFramework` to `net10.0`. Visual Studio 2022 users need a newer Visual Studio (per the draft 4.8 migration guide; unconfirmed).

### Godot.NET Preview Bindings (Godot 4.7+)

Godot 4.7's `Godot.NET.Sdk` accepts an opt-in MSBuild property that switches the project from the classic GodotSharp bindings to the preview Godot.NET bindings (the `Godot.Bindings` assembly instead of `GodotSharp`):

```xml
<PropertyGroup>
  <EnableGodotDotNetPreview>true</EnableGodotDotNetPreview>
</PropertyGroup>
```

The preview bindings are experimental — leave the property unset for production projects. See [GH-118001](https://github.com/godotengine/godot/pull/118001).

### IDE Setup

| IDE | Setup Required | Notes |
|---|---|---|
| JetBrains Rider | Install Godot plugin (bundled in Rider 2023.3+) | Best Godot C# support; debugger works out of the box |
| VS Code | Install **C# Dev Kit** + **Godot Tools** extensions | Requires `launch.json` for debugger attachment |
| Visual Studio | Install **Godot Visual Studio** extension | Windows only; debugger via `Tools > Attach to Process` |

For all IDEs, open the `.sln` file (not just a folder) to get full solution resolution.

---

## 3. The `partial class` Requirement

Every class that extends a Godot type **must** be declared `partial`. This is not optional.

### Why

Godot uses C# source generators to emit the signal registration, property binding, and RPC code alongside your class. Source generators require `partial` to inject into the same class declaration.

### Error When Forgotten

```
error GD0001: Missing partial modifier on declaration of type 'Player'
that derives from 'Godot.GodotObject'
```

The build fails, so a missing `partial` cannot slip through.

### Rule

```csharp
// CORRECT
public partial class Player : CharacterBody2D { }

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

This applies to every class in the inheritance chain that extends a Godot type, including intermediate base classes.

---

## 4. Naming Conventions

| Element | Convention | Example |
|---|---|---|
| Methods | PascalCase | `public void TakeDamage(int amount)` |
| Properties | PascalCase | `public float MaxHealth { get; set; }` |
| Signals (delegate) | PascalCase + `EventHandler` suffix | `HealthChangedEventHandler` |
| `[Export]` properties | PascalCase | `[Export] public float Speed { get; set; }` |
| Private fields | `_camelCase` with underscore prefix | `private float _currentSpeed;` |
| Local variables | camelCase | `var newPosition = ...` |
| Parameters | camelCase | `void SetHealth(int newHealth)` |
| Godot API names | Match Godot's PascalCase exactly | `GlobalPosition` not `global_position` |
| Enums | PascalCase type, PascalCase members | `enum State { Idle, Running, Dead }` |
| Constants | PascalCase or SCREAMING_SNAKE per team style | `const float MaxSpeed = 200f;` |

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. Signals in C#

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

```csharp
using Godot;

public partial class Player : CharacterBody2D
{
    // Declaration
    [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

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

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

// Handler signatures must match the delegate
private void OnHealthChanged(int newHealth) { ... }
private void OnPlayerDied() { ... }
```

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

---

## 6. Async / Await

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

### Awaiting a Godot Signal

```csharp
public async void StartCutscene()
{
    // Wait for a timer to finish
    await ToSignal(GetTree().CreateTimer(2.0), SceneTreeTimer.SignalName.Timeout);

    // Wait for an animation to finish
    var anim = GetNode<AnimationPlayer>("AnimationPlayer");
    anim.Play("intro");
    await ToSignal(anim, AnimationPlayer.SignalName.AnimationFinished);

    GD.Print("Cutscene complete");
}
```

### Task-Based Patterns

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

```csharp
public async void 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

| GDScript | C# |
|---|---|
| `await get_tree().create_timer(1.0).timeout` | `await ToSignal(GetTree().CreateTimer(1.0), SceneTreeTimer.SignalName.Timeout)` |
| `await animation_player.animation_finished` | `await ToSignal(animPlayer, AnimationPlayer.SignalName.AnimationFinished)` |
| `await signal_name` | `await ToSignal(this, SignalName.YourSignal)` |

---

## 7. GDScript Interop

C# calls into GDScript objects with `Call`, `Get`, and `Set`, and GDScript can use a C# class directly when it is registered as a `[GlobalClass]`. Values cross the boundary as `Variant`, and the reference lists the marshalling gotchas (`null`, `int[]`, `List<T>`).

> See [references/gdscript-interop.md](https://skilld.dev/api/skills-raw/jame581/godotprompter/csharp-godot/references/gdscript-interop.md) for the `Call`/`Get`/`Set` examples, the `[GlobalClass]` pattern, and the `Variant` marshalling table.

---

## 8. Performance

### C# vs GDScript

| Workload | Winner | Reason |
|---|---|---|
| Math-heavy loops (pathfinding, simulation) | C# (significantly faster) | Compiled JIT vs interpreted GDScript |
| Large array/collection processing | C# | Value type arrays avoid boxing |
| Godot API calls (move_and_slide, etc.) | Roughly equal | Both route through the same C++ engine |
| Scene tree operations | Roughly equal | Bottleneck is C++ overhead, not language |
| Rapid prototyping | GDScript | Less boilerplate, hot-reload without recompile |
| Editor tooling (plugins, @tool) | GDScript | C# tool scripts require a full build cycle |

### 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` and `Array<T>` in hot paths — `Array<T>` wraps the same engine array, so every element access still marshals a `Variant`. Use `T[]` or `List<T>` and convert at boundaries.
- `StringName` lookups are O(1) but `StringName` construction is not — cache them if created frequently.

---

## 9. Common Gotchas

| Gotcha | Problem | Fix |
|---|---|---|
| `Variant` to C# type conversion | `(float)v` is the same call as `v.AsSingle()`: neither throws — `int`, `bool` and numeric strings convert, any other type yields `0` | Check `v.VariantType` when the stored type matters |
| `null` vs `default(Variant)` | Godot signals passing no value give `default(Variant)`, not C# `null` | Check `.VariantType == Variant.Type.Nil` |
| `Godot.Collections` vs `System.Collections` | Godot API methods return `Godot.Collections.Array`; a `List<T>` does not convert to `Variant`, so passing one does not compile | Always use `Godot.Collections.Array`/`Dictionary` at Godot API boundaries |
| Disposing native objects | Calling methods on a freed Godot object throws `ObjectDisposedException` | Check `IsInstanceValid(obj)` before use |
| `StringName` construction in hot loops | `new StringName("my_signal")` allocates each call | Cache as `private static readonly StringName _signalName = "my_signal";` |
| Export array types | `[Export] public Array Items;` exports untyped array | Use `[Export] public Godot.Collections.Array<MyResource> Items { get; set; }` |
| Node path strings | `GetNode("../UI/Label")` logs `Node not found` and returns `null` at runtime if the path changes | Use `GetNode<Label>("%Label")` with unique names or typed `[Export]` node references |
| `partial class` forgotten | Build error GD0001 | Every class extending a Godot type must be `partial` |
| `async void` vs `async Task` | `async void` cannot be awaited; an `async Task` nobody awaits hides its exception (Godot logs `async void` exceptions) | Return `Task` and await it; keep `async void` for top-level event handlers that Godot calls |

> ⚠️ **Changed in Godot 4.7:** The 4.7 C# assemblies ship several compatibility breaks. Binary-incompatible only (source still compiles — a rebuild suffices): `OptimizedTranslation.Generate()` now returns `bool` instead of `void` (GH-119563). Binary- **and** source-incompatible (code changes required): `Animation.Length` changed type metadata from `float` to `double` (GH-116394) — the C# property is now `double`, so `float len = anim.Length;` no longer compiles — and `Control.AccessibilityLive` changed enum type from `DisplayServer.AccessibilityLiveMode` to `AccessibilityServer.AccessibilityLiveMode` (GH-116839) — update declarations to the `AccessibilityServer` enum. Source-incompatible (existing binaries still load): `RichTextLabel.ImageUpdateMask.WidthInPercent` was renamed to `WidthUnit` (GH-112617; `UPDATE_WIDTH_IN_PERCENT` → `UPDATE_WIDTH_UNIT` in GDScript), and the `EditorSceneFormatImporter` `IMPORT_*` constants moved into the `ImportFlags` enum (GH-115788). Removed: `AudioEffectSpectrumAnalyzer.TapBackPos` (GH-114355). Rebuild against 4.7 and fix the affected symbols. See the [4.7 migration guide](https://docs.godotengine.org/en/latest/tutorials/migrating/upgrading_to_godot_4.7.html).

---

## 10. 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
