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.zdeve 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.godotprecisa de"C#"emconfig/featurese[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 serpartial.[GlobalClass]registra a classe no diálogo Criar e como um tipo Resource exportável, semelhante aoclass_namedo 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 eventoHiteSignalName.Hit. Emita comEmitSignal(SignalName.Hit, 5)e conecte comenemy.Hit += OnHit;. - Use
SignalName.*,MethodName.*ePropertyName.*(gerados comoStringName) sempre que a API esperar um nome, para nunca alocar strings. - Structs são copiadas:
Position.X = 5não compila (CS1612). EscrevaPosition = Position with { X = 5 };.
Tempo de vida dos sinais (regras oficiais)
O Godot desconecta tudo quando qualquer objeto é liberado, exceto:
+=em um custom[Signal], quando o receptor é liberado primeiro, e- lambdas que capturam variáveis. O Godot não consegue vinculá-las a uma instância, e
Callable.Fromnã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çaObjectDisposedException.
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.Genericpara lógica interna. UseGodot.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. PrefiraGetNode<T>()uma vez em_Readye mantenha o resultado em um campo. - Bug de cultura:
$"{1.5f}",float.ParseeToString()seguem a localidade do SO (1,5em italiano, alemão, …). UseCultureInfo.InvariantCulturepara 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 smokepara erros. GD.Printaloca memória. Remova-o de caminhos quentes, ou coloque-o atrás de#if DEBUGouOS.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 comCallDeferredouCallable.From(...).CallDeferred()antes de tocar em nós. - Aguarde qualquer coisa dentro de
_Ready/_Processapenas através de um handlerasync void, e mantenha-o curto. VerifiqueIsInstanceValid(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 comgd.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. RetorneVariantde métodos que o GDScript chama dinamicamente.
Padrões, interop e notas do editor/hot-reload (compilados pelos testes): references/patterns.md.