CommunityProgramación y desarrollogithub.com

godot-csharp

Desarrollo en C#/.NET para Godot 4.7 optimizado: configuración de csproj/SDK, clases parciales y generadores de código, [Export]/[Signal]/[GlobalClass]/[Tool], señales y eventos que deben desconectarse (ObjectDisposedException), caché de StringName, marshaling de Variant/colecciones, ToSignal asíncrono, interoperabilidad con GDScript, errores culturales, sin exportación web y errores de dotnet build como JSON. Útil para cualquier archivo .cs.

¿Qué es godot-csharp?

Esta habilidad especializada guía a los desarrolladores en el uso de C#/.NET con Godot 4.7, abordando todas las complejidades prácticas que surgen al trabajar con este motor. Se enfoca en la configuración correcta del proyecto (csproj, SDK, ensamblado), el uso de generadores de código para clases parciales, señales, exportaciones y atributos como `[GlobalClass]` y `[Tool]`. También cubre la gestión del ciclo de vida de las señales para evitar `ObjectDisposedException`, el caché de `StringName` para rendimiento, el marshaling eficiente de `Variant` y colecciones, el patrón `async` con `ToSignal`, y la interoperabilidad bidireccional con GDScript. Incluye advertencias sobre errores culturales en formato de números, limitaciones de exportación web, y cómo interpretar los errores de compilación como JSON para depuración. Es compatible con cualquier archivo .cs en proyectos Godot 4.7 y está diseñada tanto para asistentes de IA como para desarrolladores humanos.

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

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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.z debe 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.godot necesita "C#" en config/features y [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 ser partial.
  • [GlobalClass] registra la clase en el diálogo Crear y como un tipo de Resource exportable, similar a class_name de 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 evento Hit y SignalName.Hit. Emite con EmitSignal(SignalName.Hit, 5) y conecta con enemy.Hit += OnHit;.
  • Usa SignalName.*, MethodName.* y PropertyName.* (objetos StringName generados) donde la API requiera un nombre, para nunca asignar cadenas.
  • Las estructuras se copian: Position.X = 5 no compilará (CS1612). Escribe Position = Position with { X = 5 };.

Ciclo de vida de las señales (reglas oficiales)

Godot desconecta todo cuando uno de los objetos se libera, excepto:

  1. += a una señal personalizada [Signal], cuando el receptor se libera primero, y
  2. lambdas que capturan variables. Godot no puede vincularlas a una instancia, y Callable.From no 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 lanza ObjectDisposedException.

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.Generic para la lógica interna. Usa Godot.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. Prefiere GetNode<T>() una vez en _Ready y guarda el resultado en un campo.
  • Error cultural: $"{1.5f}", float.Parse y ToString() siguen la configuración regional del SO (1,5 en italiano, alemán, …). Usa CultureInfo.InvariantCulture para 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.Print asigna memoria. Elimínalo de las rutas críticas, o ponlo detrás de #if DEBUG o OS.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 con CallDeferred o Callable.From(...).CallDeferred() antes de tocar nodos.
  • Solo usa await dentro de _Ready/_Process a través de un manejador async void, y mantenlo breve. Comprueba IsInstanceValid(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 con gd.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. Devuelve Variant desde métodos que GDScript llama dinámicamente.

Patrones, interoperabilidad y notas del editor/recarga en caliente (recopiladas por las pruebas): references/patterns.md.

Individual skills in this repo

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

Skills relacionados