CommunityCodierung & Entwicklunggithub.com

godot-csharp

Godot 4.7 C#/.NET richtig gemacht – csproj/SDK-Setup, partielle Klassen und Source Generatoren, [Export]/[Signal]/[GlobalClass]/[Tool], C#-Signale und Events, die getrennt werden müssen (ObjectDisposedException), StringName-Caching, Variant/Collections-Marshalling, async ToSignal, GDScript-Interop, Kultur-Bugs, kein Web-Export, dotnet build-Fehler als JSON. Für jede .cs-Datei verwenden.

Was ist godot-csharp?

Dieses Skill konfiguriert und nutzt C#/.NET in Godot 4.7 (einschließlich 4.7.2). Es deckt die korrekte Projektkonfiguration ab (`Godot.NET.Sdk/4.7.2`, `net8.0`/`net9.0`, `EnableDynamicLoading`), die Verwendung von Source Generatoren (partielle Klassen, `[Signal]`, `[Export]`, `[GlobalClass]`, `[Tool]`) und Performance-Optimierungen (StringName-Caching, Vermeidung von Allokationen in heißen Schleifen, Marshalling von Godot.Collections im Grenzbereich). Es ist speziell für Entwickler gedacht, die C# in Godot einsetzen und dabei typische Fallstricke wie `ObjectDisposedException` bei Signalen, Kulturfehler bei Zahlenformatierung, das Fehlen des Web-Exports und das asynchrone Programmieren mit `ToSignal` vermeiden möchten. Das Skill bietet Build- und Analyse-Tools (`cs_build.py`, `run_godot.py`) und verweist auf eine ausführliche Referenzdatei für Muster und Editor-/Hot-Reload-Hinweise.

Funktioniert mit~Claude Code~Codex CLI~Cursor
Part ofMobile
npx skills add https://github.com/EL4CTEO/godot-skills/tree/main/skills/godot-csharp

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

C# / .NET in Godot 4.7

Nach jeder Bearbeitung bauen: python scripts/cs_build.py gibt Fehler als {file, line, code, msg} zurück. Verwende --doctor, um das Setup zu überprüfen, und --init, um die csproj und sln genau wie der 4.7-Editor zu erstellen. Die Engine führt die zuletzt erstellte Assembly in .godot/mono/temp/bin/ aus, also baue vor jedem Testlauf. C#-Namen: api_lookup.py Node3D.look_at gibt Node3D.LookAt(Vector3, Vector3?, bool) aus. C#-Namen funktionieren auch als Abfragen.

Projekt-Setup (getestet mit 4.7.2-Vorlage)

<Project Sdk="Godot.NET.Sdk/4.7.2">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <TargetFramework Condition=" '$(GodotTargetPlatform)' == 'android' ">net9.0</TargetFramework>
    <EnableDynamicLoading>true</EnableDynamicLoading>
  </PropertyGroup>
</Project>
  • Die Version von Godot.NET.Sdk/x.y.z muss mit der Engine-Version übereinstimmen. Aktualisiere sie, wenn du Godot upgradest. net8.0 ist das Minimum; net9.0+ ist erlaubt. <Nullable>enable</Nullable> wird empfohlen.
  • project.godot benötigt "C#" in config/features und [dotnet] project/assembly_name. Der Assembly-Name muss mit dem csproj-Namen übereinstimmen.
  • NuGet-Pakete funktionieren normal (dotnet add package). Assemblies müssen reiner Managed Code sein oder native Bibliotheken für jede Zielplattform mitliefern.
  • Nicht unterstützt: Web-Export von C#-Projekten (gilt auch in 4.7; für Web-Builds GDScript verwenden). Android benötigt net9.0 (die Vorlage übernimmt das). iOS funktioniert. Desktop funktioniert überall.

Skript-Regeln (die Source Generatoren hängen davon ab)

  • public partial class Player : CharacterBody3D. Der Dateiname muss dem Klassennamen entsprechen (Player.cs). Namespaces sind in Ordnung. Von Godot abgeleitete Klassen müssen partial sein.
  • [GlobalClass] registriert die Klasse im Erstellungsdialog und als exportierbaren Resource-Typ, ähnlich wie GDScript class_name. [Tool] führt die Klasse im Editor aus.
  • Exports: [Export] public float Speed { get; set; } = 5f; plus [ExportGroup("Movement")], [ExportSubgroup], [ExportCategory], [Export(PropertyHint.Range, "0,100,1")] und [ExportToolButton("Bake")] public Callable BakeButton => Callable.From(Bake);.
  • Signale: [Signal] public delegate void HitEventHandler(int damage);. Das Suffix ist erforderlich. Der Generator erstellt das Event Hit und SignalName.Hit. Senden mit EmitSignal(SignalName.Hit, 5) und verbinden mit enemy.Hit += OnHit;.
  • Verwende SignalName.*, MethodName.* und PropertyName.* (generierte StringNames) überall dort, wo die API einen Namen erwartet, damit du nie Strings allokierst.
  • Strukturen werden kopiert: Position.X = 5 lässt sich nicht kompilieren (CS1612). Schreibe Position = Position with { X = 5 };.

Signal-Lebensdauer (offizielle Regeln)

Godot trennt alles, wenn eines der Objekte freigegeben wird, außer:

  1. += auf ein benutzerdefiniertes [Signal], wenn der Empfänger zuerst freigegeben wird, und
  2. Lambdas, die Variablen einfangen. Godot kann sie keiner Instanz zuordnen, und Callable.From hilft nicht. In beiden Fällen abmelden mit -= in _ExitTree (das Delegate für Lambdas in einem Feld behalten). Andernfalls löst das Senden an ein freigegebenes Objekt ObjectDisposedException aus.

Leistung und Korrektheit

  • Cache Eingabe-Aktionen, Gruppen und andere Namen als static readonly StringName. Jedes Mal "jump" zu übergeben, alloziert.
  • Verwende System.Collections.Generic für interne Logik. Verwende Godot.Collections.Array<T>/Dictionary<TK,TV> nur an der Godot-Grenze (Exports, Signale, GDScript-Aufrufe). Jede Grenzüberschreitung marschallt die Daten.
  • Gepackte Arrays (Vector3[], byte[]) werden bei jedem API-Aufruf kopiert. Lies ein Mesh-Array einmal aus und arbeite mit der Kopie.
  • Vermeide LINQ und Closures in _Process/_PhysicsProcess-Hot-Loops. Bevorzuge GetNode<T>() einmal in _Ready und behalte das Ergebnis in einem Feld.
  • Kultur-Bug: $"{1.5f}", float.Parse und ToString() folgen dem OS-Gebietsschema (1,5 auf Italienisch, Deutsch …). Verwende CultureInfo.InvariantCulture für Spielstände, Netzwerkdaten, JSON und UI-Zahlenformate. (Beobachtet auf einem 4.7.2-Testrechner.)
  • Ausnahmen in Callbacks werden protokolliert, sind aber nicht fatal. Behalte das Output/Debugger-Panel im Auge, oder run_godot.py smoke-Fehler.
  • GD.Print alloziert. Entferne es aus heißen Pfaden oder setze es hinter #if DEBUG oder OS.IsDebugBuild().

Async

  • await ToSignal(GetTree().CreateTimer(1.0), SceneTreeTimer.SignalName.Timeout); wartet auf ein Signal im Hauptthread.
  • Führe CPU-Arbeit auf Task.Run/WorkerThreadPool aus und kehre dann mit CallDeferred oder Callable.From(...).CallDeferred() in den Hauptthread zurück, bevor du Nodes berührst.
  • Erwarte in _Ready/_Process nur über einen async void-Handler etwas und halte es kurz. Überprüfe nach await mit IsInstanceValid(this).

GDScript ↔ C#

  • Von C# aus: var gd = GetNode("Inventory"); gd.Call("add_item", "sword", 2); var n = gd.Get("count").AsInt32();. Verbinde zu seinen Signalen mit gd.Connect("changed", Callable.From<int>(OnChanged)).
  • Von GDScript aus: C#-öffentliche Member erscheinen mit ihren C#-Namen (node.Speed, node.Damage(5)). Signale behalten ihre C#-Namen (node.Hit.connect(...)).
  • GDScript-Objekte von C# aus erstellen: GD.Load<GDScript>("res://x.gd").New().AsGodotObject().
  • Variant: Variant.From(x), v.As<T>(), v.AsInt32(), v.VariantType. Gib Variant von Methoden zurück, die GDScript dynamisch aufruft.

Muster, Interop und Editor-/Hot-Reload-Hinweise (zusammengestellt durch die Tests): references/patterns.md.

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

Verwandte Skills