跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

csharp-godot

Use when working with C# in Godot — conventions, GodotSharp API differences from GDScript, project setup, and interop

jame581 · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add jame581/GodotPrompter --skill csharp-godot

技能说明


name: csharp-godot description: Use when working with C# in Godot — conventions, GodotSharp API differences from GDScript, project setup, and interop

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

GDScriptC# EquivalentNotes
var x = 5var 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 = $Labelprivate 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 Nodepublic 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 CharacterBody2Dnode is CharacterBody2DSame keyword, same semantics
node as CharacterBody2Dnode as CharacterBody2DReturns null on failure in both
await signal_nameawait ToSignal(source, SignalName.X);Must use ToSignal() wrapper
ArrayGodot.Collections.ArrayNot System.Collections.Generic.List<T>
DictionaryGodot.Collections.DictionaryNot 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>:

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

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):

<PropertyGroup>
  <EnableGodotDotNetPreview>true</EnableGodotDotNetPreview>
</PropertyGroup>

The preview bindings are experimental — leave the property unset for production projects. See GH-118001.

IDE Setup

IDESetup RequiredNotes
JetBrains RiderInstall Godot plugin (bundled in Rider 2023.3+)Best Godot C# support; debugger works out of the box
VS CodeInstall C# Dev Kit + Godot Tools extensionsRequires launch.json for debugger attachment
Visual StudioInstall Godot Visual Studio extensionWindows 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 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.

Rule

// 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

ElementConventionExample
MethodsPascalCasepublic void TakeDamage(int amount)
PropertiesPascalCasepublic float MaxHealth { get; set; }
Signals (delegate)PascalCase + EventHandler suffixHealthChangedEventHandler
[Export] propertiesPascalCase[Export] public float Speed { get; set; }
Private fields_camelCase with underscore prefixprivate float _currentSpeed;
Local variablescamelCasevar newPosition = ...
ParameterscamelCasevoid SetHealth(int newHealth)
Godot API namesMatch Godot's PascalCase exactlyGlobalPosition not global_position
EnumsPascalCase type, PascalCase member
阅读完整来源 ↗