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.zmuss 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.godotbenötigt"C#"inconfig/featuresund[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üssenpartialsein.[GlobalClass]registriert die Klasse im Erstellungsdialog und als exportierbaren Resource-Typ, ähnlich wie GDScriptclass_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 EventHitundSignalName.Hit. Senden mitEmitSignal(SignalName.Hit, 5)und verbinden mitenemy.Hit += OnHit;. - Verwende
SignalName.*,MethodName.*undPropertyName.*(generierteStringNames) überall dort, wo die API einen Namen erwartet, damit du nie Strings allokierst. - Strukturen werden kopiert:
Position.X = 5lässt sich nicht kompilieren (CS1612). SchreibePosition = Position with { X = 5 };.
Signal-Lebensdauer (offizielle Regeln)
Godot trennt alles, wenn eines der Objekte freigegeben wird, außer:
+=auf ein benutzerdefiniertes[Signal], wenn der Empfänger zuerst freigegeben wird, und- Lambdas, die Variablen einfangen. Godot kann sie keiner Instanz zuordnen, und
Callable.Fromhilft 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 ObjektObjectDisposedExceptionaus.
Leistung und Korrektheit
- Cache Eingabe-Aktionen, Gruppen und andere Namen als
static readonly StringName. Jedes Mal"jump"zu übergeben, alloziert. - Verwende
System.Collections.Genericfür interne Logik. VerwendeGodot.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. BevorzugeGetNode<T>()einmal in_Readyund behalte das Ergebnis in einem Feld. - Kultur-Bug:
$"{1.5f}",float.ParseundToString()folgen dem OS-Gebietsschema (1,5auf Italienisch, Deutsch …). VerwendeCultureInfo.InvariantCulturefü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.Printalloziert. Entferne es aus heißen Pfaden oder setze es hinter#if DEBUGoderOS.IsDebugBuild().
Async
await ToSignal(GetTree().CreateTimer(1.0), SceneTreeTimer.SignalName.Timeout);wartet auf ein Signal im Hauptthread.- Führe CPU-Arbeit auf
Task.Run/WorkerThreadPoolaus und kehre dann mitCallDeferredoderCallable.From(...).CallDeferred()in den Hauptthread zurück, bevor du Nodes berührst. - Erwarte in
_Ready/_Processnur über einenasync void-Handler etwas und halte es kurz. Überprüfe nachawaitmitIsInstanceValid(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 mitgd.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. GibVariantvon Methoden zurück, die GDScript dynamisch aufruft.
Muster, Interop und Editor-/Hot-Reload-Hinweise (zusammengestellt durch die Tests): references/patterns.md.