godot-csharp
Use C#/.NET in Godot 4.x: partial classes extending nodes, the PascalCase lifecycle (_Ready/_Process/_PhysicsProcess), [Export] fields, [Signal] delegates as C# events, GetNode<T>, and calling between C# and GDScript. Use when writing Godot game code in C# (.cs files, .csproj), needing the Godot .NET build, converting GDScript patterns to C#, or wiring Godot signals as C# events.
- License 许可
- Apache-2.0
- 最近更新
- 2026-07-24
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- godot-csharp
- license
- Apache-2.0
- metadata
- { "engine": "godot", "category": "godot", "difficulty": "intermediate" }
- description
- Use C#/.NET in Godot 4.x: partial classes extending nodes, the PascalCase lifecycle (_Ready/_Process/_PhysicsProcess), [Export] fields, [Signal] delegates as C# events, GetNode<T>, and calling between C# and GDScript. Use when writing Godot game code in C# (.cs files, .csproj), needing the Godot .NET build, converting GDScript patterns to C#, or wiring Godot signals as C# events.
- compatibility
- Godot 4.3+ .NET (C#); .NET 6.0 SDK for 4.3/4.4, .NET 8 for 4.5+
02 资源文件 1
- 参考文档references/csharp-setup-and-interop.md3.8 KB
03 SKILL.md 正文
Godot C# / .NET (4.x)
Write Godot game code in C#: node subclasses, the engine lifecycle, exports, signals as events, and GDScript interop. Targets Godot 4.3+ (.NET / C#); install the .NET SDK that matches your Godot version — .NET 6.0 for 4.3/4.4, .NET 8 for 4.5+.
When to use
- Use when scripting a Godot game in C# (
.cs+.csproj), translating GDScript idioms to C#, exposing[Export]fields, or wiring[Signal]delegates and GetNode<T>.
When not to use: GDScript-specific syntax → godot-gdscript; engine concepts that
are language-neutral (scenes, physics, animation) → the relevant godot-* skill. You need
the Godot .NET build + the .NET SDK installed; the standard build can't run C#.
Core workflow
- Use the Godot .NET editor build and install the matching .NET SDK (.NET 6.0 for
Godot 4.3/4.4, .NET 8 for 4.5+). Creating the first C#
script generates a
.csproj/.sln. Build with the editor ordotnet build. - Every node script is a
partialclass extending a Godot type (the source generator relies onpartial). The file/class name should match the node script. - Override lifecycle methods in PascalCase with
doubledelta:_Ready(),_Process(double delta),_PhysicsProcess(double delta). - Expose tunables with
[Export]; they show in the Inspector like GDScript@export. - Declare signals as
[Signal]delegates namedXxxEventHandler; emit withEmitSignal(SignalName.Xxx, ...)and subscribe with the generated C#event. - Get nodes with
GetNode<T>("Path")(or%Unique), and call into GDScript withCall/Get/Setwhen needed.
Patterns
1. A node script: lifecycle, [Export], GetNode<T>
using Godot;
public partial class Player : CharacterBody2D
{
[Export] public float Speed = 200.0f; // editable in the Inspector
[Export] public float JumpVelocity = -400.0f;
private const float Gravity = 1200.0f;
private AnimatedSprite2D _sprite;
public override void _Ready()
{
_sprite = GetNode<AnimatedSprite2D>("AnimatedSprite2D");
}
public override void _PhysicsProcess(double delta)
{
Vector2 v = Velocity; // Velocity is a property here
if (!IsOnFloor())
v.Y += Gravity * (float)delta; // delta is double; cast for float math
if (Input.IsActionJustPressed("jump") && IsOnFloor())
v.Y = JumpVelocity;
float dir = Input.GetAxis("move_left", "move_right");
v.X = dir != 0 ? dir * Speed : Mathf.MoveToward(v.X, 0, Speed);
Velocity = v;
MoveAndSlide(); // no args, like GDScript 4.x
}
}
2. Signals as C# events
using Godot;
public partial class Health : Node
{
// Delegate name MUST end with "EventHandler"; generator creates the event + SignalName.
[Signal] public delegate void HealthChangedEventHandler(int current, int max);
private int _hp = 100;
public void TakeDamage(int amount)
{
_hp = Mathf.Max(_hp - amount, 0);
EmitSignal(SignalName.HealthChanged, _hp, 100); // type-safe signal name
}
public override void _Ready()
{
HealthChanged += OnHealthChanged; // subscribe like a normal C# event
}
private void OnHealthChanged(int current, int max) => GD.Print($"HP {current}/{max}");
}
3. Instancing a scene in C#
public partial class Spawner : Node2D
{
// Load once; PackedScene is the C# equivalent of preload's result.
private readonly PackedScene _bullet = GD.Load<PackedScene>("res://bullet.tscn");
public void Shoot(Vector2 at)
{
var b = _bullet.Instantiate<Node2D>(); // typed instantiate
b.GlobalPosition = at;
AddChild(b);
}
}
4. Interop with GDScript nodes
public override void _Ready()
{
Node gd = GetNode("GDScriptNode");
// Call a GDScript method and read/write its properties dynamically.
gd.Call("take_damage", 10);
int score = (int)gd.Get("score");
gd.Set("score", score + 5);
// Connect to a GDScript signal by name:
gd.Connect("died", Callable.From(OnDied));
}
private void OnDied() => GD.Print("entity died");
Pitfalls
- Forgetting
partial. Withoutpartial, the Godot source generator can't extend the class and[Export]/[Signal]break with confusing build errors. - Wrong method case/signature. C# overrides are
_Ready,_Process(double),_PhysicsProcess(double)— PascalCase anddoubledelta (GDScript uses snake_case andfloat). A mismatched name just won't be called. [Signal]delegate naming. It must end withEventHandler; the engine exposes the signal as the name without that suffix and generatesSignalName.Xand a C#event.GD.PrintvsConsole.WriteLine. UseGD.Print/GD.PrintErrto reach the Godot output panel;Consoleoutput may not appear.- Value-type structs.
Vector2,Color,Transform2Dare structs — mutate a local copy (var v = Velocity; v.X = ...; Velocity = v;); editingVelocity.Xdirectly won't compile/persist. - Needs the .NET build + SDK. The non-.NET editor can't run C#; mismatched/missing .NET SDK causes build failures. Match the SDK to the Godot version (4.3/4.4 → .NET 6.0, 4.5+ → .NET 8; Android export on 4.5 needs .NET 9).
QueueFree()vsFree()— same rules as GDScript; preferQueueFree(). Disposed objects throwObjectDisposedExceptionif used after freeing.- Export to some platforms differs for .NET (e.g. extra steps for web/mobile); check the .NET export notes for your target.
References
- For export attribute variants (
[ExportGroup], ranges, typed arrays), async withawait ToSignal(...),Godot.Collectionsvs System collections, custom Resources in C#, and project/build setup, readreferences/csharp-setup-and-interop.md.
Related skills
godot-gdscript— the GDScript equivalents of these patterns.godot-signals-groups— signal/event architecture (language-neutral).godot-resources— data resources; the C#[Export]+Resourcepattern.unity-csharp-scripting— C# in Unity, for developers coming from there.
04 同仓库更多 Skills
webapp-testing
Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
web-typography
Select, pair, and implement typefaces for web projects. Use when the user mentions "font pairing", "which typeface", "line height", "responsive typography", "web font loading", or "type hierarchy". Covers readability evaluation, CSS implementation, and performance optimization. For overall UI design systems, see refactoring-ui. For dramatic typographic experiences, see top-design.
web-haptics
Add haptic feedback to web apps using the web-haptics library. Use when building mobile-facing UIs that need tactile feedback on buttons, toggles, forms, pickers, and other interactive elements.
visual-novel
Build a visual novel: a branching script, character and background display, a text box with choices, save/load, backlog, and skip/auto. Use for a VN, dating sim, or branching story game.
ux-heuristics
Evaluate and improve interface usability using heuristic analysis. Use when the user mentions "usability audit", "UX review", "users are confused", "heuristic evaluation", "form usability", or "navigation problems". Covers Nielsen's 10 heuristics, severity ratings, and information architecture. For visual design fixes, see refactoring-ui. For conversion-focused audits, see cro-methodology.
unreal-packaging
Package and ship an Unreal Engine 5 project: the Platforms menu Package Project flow, build configurations (Development vs Shipping), cooking content, packaging settings and the Game Default Map, and command-line builds with RunUAT BuildCookRun. Use when packaging a build, making a shipping build, cooking content, configuring packaging settings, or when the user mentions package Unreal, cook content, shipping build, or BuildCookRun.