C# / .NET en Godot 4.7
Compila después de cada edición: python scripts/cs_build.py devuelve errores como {file, line, code, msg}. Usa --doctor para verificar la configuración y --init para crear el csproj y sln exactamente como lo hace el editor 4.7.
El motor ejecuta el último ensamblado compilado en .godot/mono/temp/bin/, así que compila antes de cualquier prueba rápida.
Nombres en C#: api_lookup.py Node3D.look_at imprime Node3D.LookAt(Vector3, Vector3?, bool). Los nombres en C# también funcionan como consultas.
Configuración del proyecto (plantilla verificada 4.7.2)
<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>
- La versión de
Godot.NET.Sdk/x.y.zdebe coincidir con la versión del motor. Actualízala cuando actualices Godot. net8.0 es el mínimo; se permite net9.0+. Se recomienda<Nullable>enable</Nullable>. project.godotnecesita"C#"enconfig/featuresy[dotnet] project/assembly_name. El nombre del ensamblado debe coincidir con el nombre del csproj.- Los paquetes NuGet funcionan normalmente (
dotnet add package). Los ensamblados deben ser código administrado puro, o incluir bibliotecas nativas para cada plataforma objetivo. - No compatible: exportación web de proyectos C# (aún es cierto en 4.7; usa GDScript para compilaciones web). Android necesita net9.0 (la plantilla lo maneja). iOS funciona. Escritorio funciona en todas partes.
Reglas de script (los generadores de código dependen de ellas)
public partial class Player : CharacterBody3D. El nombre del archivo debe ser igual al nombre de la clase (Player.cs). Los espacios de nombres están bien. Las clases derivadas de Godot deben serpartial.[GlobalClass]registra la clase en el diálogo Crear y como un tipo de Resource exportable, similar aclass_namede GDScript.[Tool]ejecuta la clase en el editor.- Exportaciones:
[Export] public float Speed { get; set; } = 5f;además de[ExportGroup("Movement")],[ExportSubgroup],[ExportCategory],[Export(PropertyHint.Range, "0,100,1")]y[ExportToolButton("Bake")] public Callable BakeButton => Callable.From(Bake);. - Señales:
[Signal] public delegate void HitEventHandler(int damage);. El sufijo es obligatorio. El generador crea el eventoHitySignalName.Hit. Emite conEmitSignal(SignalName.Hit, 5)y conecta conenemy.Hit += OnHit;. - Usa
SignalName.*,MethodName.*yPropertyName.*(objetosStringNamegenerados) donde la API requiera un nombre, para nunca asignar cadenas. - Las estructuras se copian:
Position.X = 5no compilará (CS1612). EscribePosition = Position with { X = 5 };.
Ciclo de vida de las señales (reglas oficiales)
Godot desconecta todo cuando uno de los objetos se libera, excepto:
+=a una señal personalizada[Signal], cuando el receptor se libera primero, y- lambdas que capturan variables. Godot no puede vincularlas a una instancia, y
Callable.Fromno ayuda. En ambos casos, cancela la suscripción con-=en_ExitTree(guarda el delegado en un campo para lambdas). De lo contrario, emitir a un objeto liberado lanzaObjectDisposedException.
Rendimiento y corrección
- Almacena en caché las acciones de entrada, grupos y otros nombres como
static readonly StringName. Pasar"jump"cada fotograma asigna memoria. - Usa
System.Collections.Genericpara la lógica interna. UsaGodot.Collections.Array<T>/Dictionary<TK,TV>solo en el límite con Godot (exportaciones, señales, llamadas GDScript). Cada cruce marshalea los datos. - Los arrays empaquetados (
Vector3[],byte[]) se copian en cada llamada a la API. Lee un array de malla una vez y trabaja sobre la copia. - Evita LINQ y clausuras en los bucles críticos de
_Process/_PhysicsProcess. PrefiereGetNode<T>()una vez en_Readyy guarda el resultado en un campo. - Error cultural:
$"{1.5f}",float.ParseyToString()siguen la configuración regional del SO (1,5en italiano, alemán, …). UsaCultureInfo.InvariantCulturepara guardados, datos de red, JSON y formatos numéricos de UI. (Observado en una máquina de prueba con 4.7.2). - Las excepciones en callbacks se registran, no son fatales. Observa el panel de Salida/Depurador, o los errores de
run_godot.py smoke. GD.Printasigna memoria. Elimínalo de las rutas críticas, o ponlo detrás de#if DEBUGoOS.IsDebugBuild().
Async
await ToSignal(GetTree().CreateTimer(1.0), SceneTreeTimer.SignalName.Timeout);espera una señal en el hilo principal.- Ejecuta trabajo intensivo de CPU con
Task.Run/WorkerThreadPool, luego vuelve al hilo principal conCallDeferredoCallable.From(...).CallDeferred()antes de tocar nodos. - Solo usa
awaitdentro de_Ready/_Processa través de un manejadorasync void, y mantenlo breve. CompruebaIsInstanceValid(this)después de los awaits.
GDScript ↔ C#
- Desde C#:
var gd = GetNode("Inventory"); gd.Call("add_item", "sword", 2); var n = gd.Get("count").AsInt32();. Conéctate a sus señales congd.Connect("changed", Callable.From<int>(OnChanged)). - Desde GDScript: los miembros públicos de C# aparecen con sus nombres en C# (
node.Speed,node.Damage(5)). Las señales mantienen sus nombres en C# (node.Hit.connect(...)). - Crea objetos GDScript desde C#:
GD.Load<GDScript>("res://x.gd").New().AsGodotObject(). Variant:Variant.From(x),v.As<T>(),v.AsInt32(),v.VariantType. DevuelveVariantdesde métodos que GDScript llama dinámicamente.
Patrones, interoperabilidad y notas del editor/recarga en caliente (recopiladas por las pruebas): references/patterns.md.