Voltar para o Blog
Quest Log

Como Usar C# na Godot 4: Guia do Zero com Scripts e Sinais

Editor da Godot 4 aberto com um script C# anexado a um nó de personagem na cena 2D

Como usar C# na Godot 4 do zero: instale a versão .NET, crie scripts .cs, herde de CharacterBody2D e use Export, GetNode e sinais em um projeto real.

Ferramenta:GodotC#

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.

Curso de Godot
Quer fazer seu primeiro jogo na Godot?

No curso de Godot da CursoGame.Dev você vai do zero ao primeiro jogo, com um desafio prático em cada level e suporte individual no WhatsApp quando travar.

Conhecer o curso de Godot
Suporte no WhatsAppAcesso vitalícioGarantia de 7 dias

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".

Perguntas frequentes

Preciso da versão .NET da Godot para programar em C#?

Sim. A build padrão da Godot não executa C#. Baixe a versão marcada como ".NET" (antiga Mono) no site oficial e tenha o SDK .NET instalado na máquina.

C# é mais rápido que GDScript na Godot?

Em cálculos pesados de CPU, C# costuma ser mais rápido. Na maior parte dos jogos indie o gargalo é a renderização e a física, então a diferença raramente aparece. Escolha pela linguagem que você domina, não só pela velocidade.

Posso misturar C# e GDScript no mesmo projeto?

Pode. Nós com script GDScript e nós com script C# convivem na mesma cena e conversam por sinais e chamadas de método. Isso é útil para aproveitar plugins em GDScript e escrever a lógica principal em C#.

C# funciona quando eu exportar para o navegador (web)?

O suporte a C# na exportação web amadureceu na linha da Godot 4, mas historicamente foi o alvo mais problemático. Se web é seu foco principal, teste a exportação cedo no projeto para não ter surpresa.

Preciso instalar o Visual Studio para usar C# na Godot?

Não. Basta o SDK do .NET. Para editar o código com autocompletar, o VS Code com a extensão de C# funciona muito bem e é gratuito, mas o Visual Studio e o Rider também são opções.