--- name: game-csharp-godot version: 1.1.1 description: "Authors Godot 4.3+ gameplay in C# with GodotSharp: partial classes, [Export] properties, [Signal] EventHandler delegates, ToSignal awaits, Variant marshalling, and GDScript Call/Get/Set at language boundaries. Use when the project needs .NET libraries, compiled hot loops, or C# and GDScript interop. Not for GDScript style guides, @tool editor plugins, or GDExtension C++. Do not use where the export target has no .NET runtime." risk: safe source: openrouter-deepsearch date_added: 2026-06-16 --- # 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 ``. ```xml net8.0 enable true enable ``` 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. ```csharp // 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 | 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. Declare and Emit Signals Signals require a delegate declaration with the `[Signal]` attribute. The delegate name **must** end with `EventHandler`. ```csharp 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:** ```csharp // 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`. ```csharp public async void StartCutscene() { await ToSignal(GetTree().CreateTimer(2.0), Timer.SignalName.Timeout); var anim = GetNode("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: ```csharp 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:** | GDScript | C# | |---|---| | `await get_tree().create_timer(1.0).timeout` | `await ToSignal(GetTree().CreateTimer(1.0), Timer.SignalName.Timeout)` | | `await animation_player.animation_finished` | `await ToSignal(animPlayer, AnimationPlayer.SignalName.AnimationFinished)` | | `await signal_name` | `await ToSignal(this, SignalName.YourSignal)` | ### 7. GDScript Interop **Calling GDScript from C#:** ```csharp 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: ```csharp [GlobalClass] public partial class WeaponData : Resource { [Export] public float Damage { get; set; } = 10f; [Export] public float Cooldown { get; set; } = 0.5f; } ``` ```gdscript # 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 | 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] public 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