godot-csharp

Godot 4.7 C#/.NET feito do jeito certo – configuração de csproj/SDK, classes parciais e source generators, [Export]/[Signal]/[GlobalClass]/[Tool], sinais e eventos C# que precisam ser desconectados (ObjectDisposedException), cache de StringName, marshaling de Variant/coleções, ToSignal assíncrono, interop com GDScript, bugs de cultura, sem exportação web, erros de dotnet build como JSON. Use para qualquer arquivo .cs.

O que é godot-csharp?

Esta habilidade fornece um guia completo e prático para desenvolvimento C#/.NET no Godot 4.7, cobrindo desde a configuração inicial do projeto até padrões avançados de desempenho e correção. Ela explica como configurar corretamente o csproj com Godot.NET.Sdk, como usar source generators para [Signal], [Export] e [GlobalClass], e como gerenciar o tempo de vida de sinais para evitar ObjectDisposedException. Também aborda técnicas de performance como cache de StringName, marshaling eficiente de Variant/coleções, uso de async com ToSignal, e como evitar armadilhas como bugs de cultura e alocações desnecessárias em hot paths. A habilidade é compatível com o editor Godot 4.7 e suporta todas as plataformas de desktop, iOS e Android (com net9.0), mas não suporta exportação web para projetos C#. Ideal para desenvolvedores que desejam escrever código C# idiomático e eficiente no Godot, aproveitando os source generators e as melhores práticas da comunidade.

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

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

C# / .NET no Godot 4.7

Compile após cada edição: python scripts/cs_build.py retorna erros como {file, line, code, msg}. Use --doctor para verificar a configuração e --init para criar o csproj e sln exatamente como o editor 4.7 faz. O motor executa o último assembly compilado em .godot/mono/temp/bin/, então compile antes de qualquer teste rápido. Nomes C#: api_lookup.py Node3D.look_at imprime Node3D.LookAt(Vector3, Vector3?, bool). Nomes C# também funcionam como consultas.

Configuração do projeto (template verificado 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>
  • A versão do Godot.NET.Sdk/x.y.z deve ser igual à versão do motor. Atualize-a quando atualizar o Godot. net8.0 é o mínimo; net9.0+ é permitido. <Nullable>enable</Nullable> é recomendado.
  • O project.godot precisa de "C#" em config/features e [dotnet] project/assembly_name. O nome do assembly deve coincidir com o nome do csproj.
  • Pacotes NuGet funcionam normalmente (dotnet add package). Os assemblies devem ser código gerenciado puro, ou fornecer bibliotecas nativas para cada plataforma alvo.
  • Não suportado: exportação web de projetos C# (ainda verdadeiro no 4.7; use GDScript para builds web). Android precisa de net9.0 (o template cuida disso). iOS funciona. Desktop funciona em qualquer lugar.

Regras de script (os source generators dependem delas)

  • public partial class Player : CharacterBody3D. O nome do arquivo deve ser igual ao nome da classe (Player.cs). Namespaces são permitidos. Classes derivadas de Godot devem ser partial.
  • [GlobalClass] registra a classe no diálogo Criar e como um tipo Resource exportável, semelhante ao class_name do GDScript. [Tool] executa a classe no editor.
  • Exports: [Export] public float Speed { get; set; } = 5f; mais [ExportGroup("Movement")], [ExportSubgroup], [ExportCategory], [Export(PropertyHint.Range, "0,100,1")] e [ExportToolButton("Bake")] public Callable BakeButton => Callable.From(Bake);.
  • Signals: [Signal] public delegate void HitEventHandler(int damage);. O sufixo é obrigatório. O gerador cria o evento Hit e SignalName.Hit. Emita com EmitSignal(SignalName.Hit, 5) e conecte com enemy.Hit += OnHit;.
  • Use SignalName.*, MethodName.* e PropertyName.* (gerados como StringName) sempre que a API esperar um nome, para nunca alocar strings.
  • Structs são copiadas: Position.X = 5 não compila (CS1612). Escreva Position = Position with { X = 5 };.

Tempo de vida dos sinais (regras oficiais)

O Godot desconecta tudo quando qualquer objeto é liberado, exceto:

  1. += em um custom [Signal], quando o receptor é liberado primeiro, e
  2. lambdas que capturam variáveis. O Godot não consegue vinculá-las a uma instância, e Callable.From não ajuda. Em ambos os casos, desinscreva-se com -= em _ExitTree (mantenha o delegate em um campo para lambdas). Caso contrário, emitir para um objeto liberado lança ObjectDisposedException.

Performance e correção

  • Faça cache de ações de entrada, grupos e outros nomes como static readonly StringName. Passar "jump" a cada quadro aloca memória.
  • Use System.Collections.Generic para lógica interna. Use Godot.Collections.Array<T>/Dictionary<TK,TV> apenas na fronteira com Godot (exports, signals, chamadas GDScript). Cada cruzamento faz marshaling dos dados.
  • Arrays compactados (Vector3[], byte[]) são copiados em cada chamada de API. Leia um array de mesh uma vez e trabalhe na cópia.
  • Evite LINQ e closures em loops quentes de _Process/_PhysicsProcess. Prefira GetNode<T>() uma vez em _Ready e mantenha o resultado em um campo.
  • Bug de cultura: $"{1.5f}", float.Parse e ToString() seguem a localidade do SO (1,5 em italiano, alemão, …). Use CultureInfo.InvariantCulture para salvamentos, dados de rede, JSON e formatos numéricos de UI. (Observado em uma máquina de teste 4.7.2.)
  • Exceções em callbacks são registradas, não fatais. Observe o painel Output/Debugger, ou run_godot.py smoke para erros.
  • GD.Print aloca memória. Remova-o de caminhos quentes, ou coloque-o atrás de #if DEBUG ou OS.IsDebugBuild().

Async

  • await ToSignal(GetTree().CreateTimer(1.0), SceneTreeTimer.SignalName.Timeout); aguarda um sinal na thread principal.
  • Execute trabalho intensivo de CPU com Task.Run/WorkerThreadPool, depois volte para a thread principal com CallDeferred ou Callable.From(...).CallDeferred() antes de tocar em nós.
  • Aguarde qualquer coisa dentro de _Ready/_Process apenas através de um handler async void, e mantenha-o curto. Verifique IsInstanceValid(this) após awaits.

GDScript ↔ C#

  • Do C#: var gd = GetNode("Inventory"); gd.Call("add_item", "sword", 2); var n = gd.Get("count").AsInt32();. Conecte-se a seus sinais com gd.Connect("changed", Callable.From<int>(OnChanged)).
  • Do GDScript: Membros públicos do C# aparecem com seus nomes C# (node.Speed, node.Damage(5)). Sinais mantêm seus nomes C# (node.Hit.connect(...)).
  • Crie objetos GDScript a partir do C#: GD.Load<GDScript>("res://x.gd").New().AsGodotObject().
  • Variant: Variant.From(x), v.As<T>(), v.AsInt32(), v.VariantType. Retorne Variant de métodos que o GDScript chama dinamicamente.

Padrões, interop e notas do editor/hot-reload (compilados pelos testes): references/patterns.md.

Individual skills in this repo

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

Habilidades Relacionadas