Como Usar C# na Godot 4: Guia Prático do Zero

Se você já sabe C# e olha para a Godot pensando "será que dá para usar o que eu já conheço em vez de aprender GDScript?", a resposta é sim. Dá para usar C# na Godot 4 de ponta a ponta: física, sinais, cenas, tudo. Mas tem um detalhe que derruba muita gente logo no começo: a versão que você baixa por padrão no site oficial NÃO executa C#. Neste guia a gente vai do download certo até um personagem 2D se movendo com código C# real da Godot 4, sem enrolação.

O foco aqui é prático. Assumo que você já viu C# em algum lugar (um curso de .NET, uma API, um jogo em Unity) e quer transferir esse conhecimento. Se você nunca escreveu uma linha de código, vale considerar começar por GDScript, que é mais simples de iterar, e voltar para cá depois.

Por que usar C# na Godot 4 (e quando não vale a pena)

Vou ser direto sobre o trade-off, porque isso importa mais do que qualquer tutorial.

C# brilha quando: você já domina a linguagem, quer reaproveitar bibliotecas do ecossistema .NET (NuGet), gosta de tipagem forte com um bom IDE, ou pretende compartilhar código de lógica entre um jogo e uma ferramenta de backend. Para quem vem de anos de C#, escrever GDScript pode parecer um retrocesso de conforto.

GDScript ainda ganha quando: você está começando na Godot, quer iterar rápido sem passo de compilação, ou depende muito da documentação e dos tutoriais da comunidade, que em maioria esmagadora usam GDScript. A integração de GDScript com o editor é mais colada: menos fricção para plugar coisas, hot reload mais suave, e menos configuração de ambiente.

Não existe resposta universal. A escolha depende do seu perfil. Se você quer se aprofundar nessa decisão com calma, eu montei uma comparação lado a lado em C# vs GDScript na Godot: qual escolher, que entra em detalhes de performance, ferramentas e curva de aprendizado. E se a sua dúvida é ainda mais lá atrás, sobre qual motor adotar, vale ler a comparação completa entre Godot e Unity antes de investir tempo.

Passo 1: baixar a versão .NET da Godot

Aqui está o erro número um de quem vem do C#. No site oficial da Godot existem, para cada versão, dois downloads:

• Godot Engine: a build padrão. Roda apenas GDScript. Se você anexar um script .cs, ela simplesmente não vai compilar.
• Godot Engine .NET: a build com suporte a C# (era chamada de "Mono" na linha 3.x). É essa que você precisa.

Baixe a versão com .NET no nome. É um pacote separado, um pouco maior, e é o único que consegue executar seus scripts C#.

Passo 2: instalar o SDK do .NET

A build .NET da Godot não traz o compilador embutido. Ela depende do SDK do .NET instalado na sua máquina. Sem ele, o projeto abre mas não compila o C#.

Instale o SDK do .NET (a versão LTS mais recente costuma ser a aposta segura) pelo site da Microsoft. Depois de instalar, confirme no terminal:

dotnet --version

Se aparecer um número de versão, está tudo certo. Se o comando não for reconhecido, reinstale ou verifique se o SDK entrou no PATH. Repito porque é comum: você precisa do SDK, não apenas do runtime. O runtime só executa programas prontos; o SDK compila.

Passo 3: criar o projeto e o primeiro script C#

Abra a Godot .NET, crie um projeto novo e monte uma cena simples. Para o exemplo, adicione um nó CharacterBody2D como raiz e, dentro dele, um Sprite2D com qualquer textura e um CollisionShape2D.

Com o nó CharacterBody2D selecionado, clique no ícone de anexar script. Na janela que abre, troque a linguagem de GDScript para C#. A Godot vai criar um arquivo .cs e, na primeira vez, gerar os arquivos de solução (.sln e .csproj) do projeto automaticamente.

O script inicial se parece com isto:

using Godot;

public partial class Jogador : CharacterBody2D
{
    public override void _Ready()
    {
    }

    public override void _Process(double delta)
    {
    }
}

Repare em três coisas que já denunciam a API da Godot 4:

1. public partial class: o partial é obrigatório. A Godot gera código complementar da sua classe nos bastidores, e sem partial o build quebra.
2. A classe herda de CharacterBody2D: o script vira o comportamento do nó ao qual está anexado. Toda a hierarquia da Godot (Node, Node2D, CharacterBody2D) está disponível como classe base.
3. _Ready e _Process são override e usam PascalCase. Na Godot 4 com C#, os métodos virtuais começam com underline e maiúscula: _Ready(), _Process(double delta), _PhysicsProcess(double delta). Isso é diferente do GDScript, que usa _ready e _process em snake_case.

O _Ready() roda uma vez, quando o nó entra na árvore da cena. O _Process(double delta) roda todo frame, e delta é o tempo em segundos desde o frame anterior. Use delta para deixar o movimento independente do FPS.

Passo 4: exportar variáveis com Export

Uma das coisas mais úteis da Godot é ajustar valores direto no Inspetor, sem recompilar mentalmente. Em C# isso é feito com o atributo [Export]:

using Godot;

public partial class Jogador : CharacterBody2D
{
    [Export]
    public float Velocidade = 300.0f;

    [Export]
    public float Gravidade = 980.0f;

    public override void _Ready()
    {
        GD.Print("Jogador pronto na cena!");
    }
}

Qualquer campo public marcado com [Export] aparece no painel Inspetor do editor. Aí você troca Velocidade de 300 para 450 e testa na hora, sem mexer no código. Note também o GD.Print(...): esse é o print da Godot em C#, o equivalente ao print() do GDScript. Ele escreve na aba de saída do editor.

Passo 5: mover o personagem com Velocity e MoveAndSlide

Agora o pulo do gato. Um CharacterBody2D na Godot 4 tem uma propriedade Velocity (um Vector2) e o método MoveAndSlide(), que move o corpo respeitando colisões e escorregando por paredes. O padrão é: você define Velocity, chama MoveAndSlide(), e a Godot cuida do resto.

Veja um controle de plataforma 2D básico, com movimento horizontal, gravidade e pulo:

using Godot;

public partial class Jogador : CharacterBody2D
{
    [Export]
    public float Velocidade = 300.0f;

    [Export]
    public float ForcaPulo = -450.0f;

    [Export]
    public float Gravidade = 980.0f;

    public override void _PhysicsProcess(double delta)
    {
        Vector2 velocidade = Velocity;

        // Aplica gravidade quando está no ar
        if (!IsOnFloor())
        {
            velocidade.Y += Gravidade * (float)delta;
        }

        // Pulo apenas se estiver no chão
        if (Input.IsActionJustPressed("ui_accept") && IsOnFloor())
        {
            velocidade.Y = ForcaPulo;
        }

        // Movimento horizontal com as setas
        float direcao = Input.GetAxis("ui_left", "ui_right");
        velocidade.X = direcao * Velocidade;

        Velocity = velocidade;
        MoveAndSlide();
    }
}

Alguns pontos que valem ouro para quem está transferindo conhecimento:

• Uso _PhysicsProcess em vez de _Process para movimento com física. Ele roda em passo fixo, ideal para colisões consistentes.
• (float)delta: o delta chega como double, e as operações de Vector2 esperam float. Esse cast explícito é comum e evita erro de compilação.
• IsOnFloor(), Input.IsActionJustPressed(...) e Input.GetAxis(...) são a API real da Godot 4. As ações "ui_left", "ui_right" e "ui_accept" já vêm mapeadas por padrão em projetos novos.
• Velocity e MoveAndSlide() em PascalCase, sem argumentos. Na Godot 3 o move_and_slide recebia a velocidade como parâmetro. Na Godot 4 ele lê a propriedade Velocity do nó. Se você achar tutorial mandando passar a velocidade no método, é código antigo.

Passo 6: pegar outros nós com GetNode()

Cedo ou tarde seu script vai precisar conversar com outro nó: uma barra de vida, um som, uma animação. Em C# você busca nós com o genérico GetNode<T>(), que já devolve o tipo certo:

using Godot;

public partial class Jogador : CharacterBody2D
{
    private AnimatedSprite2D _sprite;
    private Timer _tiroCooldown;

    public override void _Ready()
    {
        _sprite = GetNode<AnimatedSprite2D>("AnimatedSprite2D");
        _tiroCooldown = GetNode<Timer>("TiroCooldown");
    }

    public override void _PhysicsProcess(double delta)
    {
        if (Velocity.X != 0)
        {
            _sprite.Play("correr");
            _sprite.FlipH = Velocity.X < 0;
        }
        else
        {
            _sprite.Play("parado");
        }
    }
}

O caminho passado para GetNode<T>("...") é relativo ao nó atual e usa os nomes que aparecem na árvore da cena. Como GetNode<AnimatedSprite2D> já retorna o tipo tipado, você tem autocompletar completo de _sprite: Play, FlipH, Frame, tudo. Guardar a referência num campo dentro de _Ready() é o padrão recomendado, para não ficar buscando o nó toda hora.

Passo 7: conectar um sinal

Sinais são o sistema de eventos da Godot, o jeito idiomático de reagir a "algo aconteceu". Em C#, cada sinal vira um evento que você conecta com += a um método. Um exemplo comum: um inimigo que reage quando algo entra na sua área de detecção.

using Godot;

public partial class Inimigo : Area2D
{
    public override void _Ready()
    {
        // Conecta o sinal BodyEntered a um método local
        BodyEntered += AoEntrarCorpo;
    }

    private void AoEntrarCorpo(Node2D corpo)
    {
        if (corpo is Jogador jogador)
        {
            GD.Print("O jogador encostou no inimigo!");
            // aqui você aplicaria dano, por exemplo
        }
    }
}

Repare no corpo is Jogador jogador: é o pattern matching do C#, que checa o tipo e já cria a variável tipada de uma vez. Esse é exatamente o tipo de conforto que faz gente de .NET se sentir em casa. Você também pode conectar sinais pela interface do editor, arrastando na aba Node, mas conectar no código deixa a lógica explícita e versionável.

Para declarar seu próprio sinal, use o atributo [Signal] num delegate:

[Signal]
public delegate void VidaMudouEventHandler(int novaVida);

E dispara com EmitSignal(SignalName.VidaMudou, vidaAtual);. O sufixo EventHandler no nome do delegate é uma convenção obrigatória da Godot 4: o sinal em si se chama VidaMudou.

Fechando: qual caminho seguir

Você acabou de ver o essencial de usar C# na Godot 4: baixar a build .NET, ter o SDK instalado, escrever uma classe partial que herda de um nó, usar _Ready, _Process e _PhysicsProcess, exportar variáveis para o Inspetor, buscar nós com GetNode<T>() e conectar sinais. Com essa base você já constrói um jogo 2D inteiro sem tocar em GDScript.

Sendo honesto até o fim: se você já pensa em C#, esse caminho vai te dar velocidade e conforto reais. Se você está começando do zero na programação, ainda recomendo experimentar o GDScript do zero em paralelo, porque a comunidade e a documentação da Godot respiram GDScript, e no começo isso desbloqueia muita coisa. O mais maduro é conhecer as duas e escolher por tarefa.

Se você quer ir além de snippets soltos e construir um jogo completo com método, do primeiro nó até a publicação, é exatamente isso que a gente ensina no CursoGame.Dev. A ideia é te tirar do "colei código e funcionou" para o "eu entendo por que funciona".