Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Noções básicas de C#

Introdução

Esta página fornece uma breve introdução ao C#, tanto o que ele é quanto como usá-lo no Godot. Depois disso, você pode querer dar uma olhada em como usar recursos específicos, ler sobre as diferenças entre a API do C# e do GDScript, e (re)visitar a seção de Scripting do tutorial passo a passo.

C# é uma linguagem de programação de alto nível desenvolvida pela Microsoft. No Godot, ela é implementada com o ambiente de execução moderno do .NET.

Atenção

Os projetos escritos em C# usando o Godot 4 atualmente não podem ser exportados para a plataforma web. Para usar C# na plataforma web, considere usar o Godot 3. O suporte para as plataformas Android e iOS está disponível a partir do Godot 4.2, mas é experimental e algumas limitações se aplicam.

Nota

Esse não é um tutorial completo e abrangente sobre a linguagem C#. Se você ainda não estiver familiarizado com sua sintaxe ou recursos, consulte o guia C# da Microsoft ou procure uma introdução adequada em outro lugar.

Pré-requisitos

O Godot agrupa as partes do .NET necessárias para executar jogos já compilados. No entanto, o Godot não agrupa as ferramentas exigidas para construir e compilar jogos, como o MSBuild e o compilador de C#. Estas ferramentas estão incluídas no .NET SDK e precisam ser instaladas separadamente.

Em resumo, você deve ter instalado o .NET SDK e a versão do Godot habilitada para .NET.

Baixe e instale a versão estável mais recente do SDK a partir da .NET download page. O Godot 4.5 exige o .NET 8 ou posterior, mas a exportação para Android exige o .NET 9 ou posterior.

Importante

Certifique-se de instalar a versão de 64 bits do(s) SDK(s) se estiver usando a versão de 64 bits do Godot.

Se você estiver construindo o Godot a partir do código-fonte, certifique-se de seguir os passos para habilitar o suporte ao .NET na sua build, conforme descrito na página Compilando com .NET.

Configurando um editor externo

O suporte ao C# no editor de script integrado do Godot é mínimo. Considere usar uma IDE ou editor externo, como o Visual Studio Code ou o Visual Studio. Eles fornecem autocompletar, depuração e outros recursos úteis para o C#. Para selecionar um editor externo no Godot, clique em Editor → Editor Settings e role a tela para baixo até Dotnet. Sob Dotnet, clique em Editor e selecione o editor externo de sua preferência. O Godot atualmente suporta os seguintes editores externos:

Visual Studio 2022
Visual Studio Code
MonoDevelop
Visual Studio para Mac
JetBrains Rider

Veja as seções a seguir sobre como configurar um editor externo:

JetBrains Rider

Após ler a seção "Pré-requisitos", você pode baixar e instalar o JetBrains Rider.

No menu Editor → Configurações do Editor do Godot:

Defina Dotnet -> Editor -> External Editor para JetBrains Rider.

No Rider:

Defina a versão do MSBuild para .NET Core.
Se você estiver usando uma versão do Rider anterior à 2024.2, instale o plugin Godot support. Essa funcionalidade agora é integrada ao Rider.

Visual Studio Code

Após ler a seção "Pré-requisitos", você pode baixar e instalar o Visual Studio Code (também conhecido como VS Code).

No menu Editor → Configurações do Editor do Godot:

Defina Dotnet -> Editor -> External Editor para Visual Studio Code.

No Visual Studio Code:

Instale a extensão C#.

Para configurar um projeto para depuração, você precisa de um arquivo tasks.json e launch.json na pasta .vscode com a configuração necessária.

Aqui está um exemplo de launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Play",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "build",
            "program": "${env:GODOT4}",
            "args": [],
            "cwd": "${workspaceFolder}",
            "stopAtEntry": false,
        }
    ]
}

Para que essa configuração de inicialização funcione, você precisa configurar uma variável de ambiente GODOT4 que aponte para o executável do Godot ou substituir o parâmetro program pelo caminho do executável do Godot.

Aqui está um exemplo de tasks.json:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "build",
            "command": "dotnet",
            "type": "process",
            "args": [
                "build"
            ],
            "problemMatcher": "$msCompile"
        }
    ]
}

Agora, quando você iniciar o depurador no Visual Studio Code, seu projeto do Godot será executado.

Visual Studio (somente Windows)

Baixe e instale a última versão do Visual Studio. O Visual Studio incluirá os SDKs necessários se você tiver as cargas de trabalho corretas selecionadas, para que você não precise instalar manualmente as coisas listadas na seção "Pré-requisitos".

Ao instalar o Visual Studio, selecione esta carga de trabalho (workload):

Desenvolvimento para desktop com .NET

No menu Editor → Configurações do Editor do Godot:

Defina Dotnet -> Editor -> External Editor para Visual Studio.

Nota

Se você vir um erro como "Unable to find package Godot.NET.Sdk", sua configuração do NuGet pode estar incorreta e precisa ser corrigida.

Uma maneira simples de corrigir o arquivo de configuração do NuGet é regenerá-lo. Em uma janela do explorador de arquivos, vá para %AppData%\NuGet. Renomeie ou exclua o arquivo NuGet.Config. Quando você compilar seu projeto do Godot novamente, o arquivo será criado automaticamente com os valores padrão.

Para depurar seus scripts em C# usando o Visual Studio, abra o arquivo .sln que é gerado após abrir o primeiro script em C# no editor. No menu Debug (Depuração), vá até a opção Debug Properties (Propriedades de Depuração) do seu projeto. Clique no botão Create a new profile (Criar um novo perfil) e escolha Executable (Executável). No campo Executable (Executável), navegue até o caminho da versão C# do editor Godot, ou digite %GODOT4% se você tiver criado uma variável de ambiente para o caminho do executável da Godot. Deve ser o caminho para o executável principal do Godot, não a versão 'console'. Para Working Directory, digite um único ponto, ., que significa o diretório atual. Também marque a checkbox Enable native code debugging (Habilitar depuração de código nativo). Agora você pode fechar esta janela, clicar na seta para baixo no seletor de perfil de debug e selecionar seu novo perfil de execução. Clique no botão verde de iniciar, e seu jogo começará a rodar em modo de depuração.

Criando um script C#

Depois de configurar com sucesso o C# para Godot, você deverá ver a seguinte opção ao selecionar Attach Script no menu de contexto de um nó em sua cena:

../../../_images/attachcsharpscript.webp

Note que, embora alguns detalhes específicos mudem, a maioria dos conceitos funciona da mesma forma ao usar C# para script. Se você é novo no Godot, pode querer seguir os tutoriais em Linguagens de script neste momento. Embora algumas páginas de documentação ainda careçam de exemplos em C#, a maioria das noções pode ser transferida a partir do GDScript.

Configuração de projeto e fluxo de trabalho

Quando você cria o primeiro script em C#, o Godot inicializa os arquivos de projeto C# para o seu projeto Godot. Isso inclui a geração de uma solução C# (.sln) e de um arquivo de projeto (.csproj), bem como alguns arquivos e pastas utilitários (.godot/mono). Todos estes, exceto .godot/mono, são importantes e devem ser commitados no seu sistema de controle de versão (VCS). Tudo o que estiver sob .godot pode ser adicionado com segurança à lista de ignorados do seu VCS. Ao solucionar problemas, às vezes pode ajudar deletar a pasta .godot/mono e deixá-la regenerar.

Exemplo

Aqui está um script C# em branco com alguns comentários para demonstrar como funciona.

using Godot;

public partial class YourCustomClass : Node
{
    // Member variables here, example:
    private int _a = 2;
    private string _b = "textvar";

    public override void _Ready()
    {
        // Called every time the node is added to the scene.
        // Initialization here.
        GD.Print("Hello from C# to Godot :)");
    }

    public override void _Process(double delta)
    {
        // Called every frame. Delta is time since the last frame.
        // Update game logic here.
    }
}

Como você pode ver, funções que normalmente estão no escopo global no GDScript, como a função print do Godot, estão disponíveis na classe estática GD, que faz parte do namespace Godot. Para uma lista completa de métodos na classe GD, veja as páginas de referência de classe para @GDScript e @GlobalScope.

Nota

Lembre-se de que a classe que você deseja anexar ao seu nó deve ter o mesmo nome do arquivo .cs. Caso contrário, você receberá o seguinte erro:

"Não foi possível encontrar a classe XXX para o script res://XXX.cs"

Diferenças gerais entre o C# e o GDScript

A API do C# usa o PascalCase em vez do snake_case no GDScript/C++. Sempre que possível, fields e getters/setters foram convertidos em propriedades. Em geral, a API C# Godot se esforça para ser tão idiomática quanto for razoavelmente possível.

Para mais informações, veja a página Diferenças da API C# para GDScript.

Aviso

Você precisa (re)construir (build) os assemblies do projeto sempre que quiser ver novas variáveis exportadas ou sinais no editor. Essa build pode ser acionada manualmente clicando no botão Build no canto superior direito do editor.

Você também precisará reconstruir os assemblies do projeto para aplicar alterações nos scripts de "ferramenta".

Pegadas gerais e problemas conhecidos

Como o suporte ao C# é bastante recente no Godot, existem algumas dores de crescimento e coisas que precisam ser resolvidas. Abaixo está uma lista dos problemas mais importantes que você deve estar ciente ao mergulhar no C# no Godot, mas em caso de dúvida, dê também uma olhada no rastreador oficial de problemas para .NET.

Escrever plugins para o editor é possível, mas atualmente é bastante complicado.
Atualmente o estado não é salvo e restaurado durante o "hot-reloading", com exceção das variáveis exportadas.
Os scripts C# anexados devem se referir a uma classe que tenha um nome de classe que corresponda ao nome do arquivo.
Existem alguns métodos como Get()/Set(), Call()/CallDeferred() e o método de conexão de sinal Connect() que dependem das convenções de nomenclatura da API em snake_case do Godot. Portanto, ao usar, por exemplo, CallDeferred("AddChild"), AddChild não funcionará porque a API está esperando a versão original em snake_case: add_child. No entanto, você pode usar quaisquer propriedades ou métodos personalizados sem essa limitação. Prefira usar o StringName exposto em PropertyName, MethodName e SignalName para evitar alocações extras de StringName e preocupações com a nomenclatura em snake_case.

A partir do Godot 4.0, a exportação de projetos .NET é suportada para plataformas desktop (Linux, Windows e macOS). Outras plataformas ganharão suporte em lançamentos futuros da versão 4.x.

Armadilhas comuns

Você pode encontrar o seguinte erro ao tentar modificar alguns valores em objetos do Godot, por exemplo, ao tentar alterar a coordenada X de um Node2D:

public partial class MyNode2D : Node2D
{
    public override void _Ready()
    {
        Position.X = 100.0f;
        // CS1612: Cannot modify the return value of 'Node2D.Position' because
        // it is not a variable.
    }
}

Isso é perfeitamente normal. Structs (neste exemplo, um Vector2) em C# são copiadas na atribuição, o que significa que quando você recupera tal objeto de uma propriedade ou de um indexador, você obtém uma cópia dele, não o objeto em si. Modificar essa cópia sem reatribuí-la depois não resultará em nada.

A solução alternativa é simples: recupere a struct inteira, modifique o valor que deseja alterar e reatribua a propriedade.

var newPosition = Position;
newPosition.X = 100.0f;
Position = newPosition;

Desde o C# 10, também é possível usar expressões with em structs, permitindo que você faça a mesma coisa em uma única linha.

Position = Position with { X = 100.0f };

Você pode ler mais sobre esse erro na referência da linguagem C#.

Desempenho do C# no Godot

Ver também

Para uma comparação de desempenho das linguagens que o Godot suporta, veja Qual linguagem de programação é mais rápida?.

A maioria das propriedades de objetos C# do Godot que são baseados em GodotObject (por exemplo, qualquer Node como Control ou Node3D como Camera3D) requer chamadas nativas (interop), pois elas se comunicam com o núcleo em C++ do Godot. Considere atribuir os valores dessas propriedades a uma variável local se precisar modificá-los ou lê-los várias vezes em um único local do código:

using Godot;

public partial class YourCustomClass : Node3D
{
    private void ExpensiveReposition()
    {
        for (var i = 0; i < 10; i++)
        {
            // Position is read and set 10 times which incurs native interop.
            // Furthermore the object is repositioned 10 times in 3D space which
            // takes additional time.
            Position += new Vector3(i, i);
        }
    }

    private void Reposition()
    {
        // A variable is used to avoid native interop for Position on every loop.
        var newPosition = Position;
        for (var i = 0; i < 10; i++)
        {
            newPosition += new Vector3(i, i);
        }
        // Setting Position only once avoids native interop and repositioning in 3D space.
        Position = newPosition;
    }
}

Passar arrays brutos (como byte[]) ou string para a API C# do Godot requer marshalling, o que é comparativamente caro.

A conversão implícita de string para NodePath ou StringName acarreta custos de interop nativa e de marshalling, pois a string precisa passar pelo marshalling e ser enviada para o respectivo construtor nativo.

Usando pacotes NuGet no Godot

Pacotes NuGet podem ser instalados e usados com o Godot, como qualquer projeto. Muitas IDEs podem adicionar pacotes diretamente. Eles também podem ser adicionados manualmente adicionando a referência do pacote no arquivo .csproj localizado na pasta principal do projeto:

    <ItemGroup>
        <PackageReference Include="Newtonsoft.Json" Version="11.0.2" />
    </ItemGroup>
    ...
</Project>

O Godot baixa e configura automaticamente os pacotes NuGet recém-adicionados na próxima vez que construir o projeto.

Perfilando seu código C#

As seguintes ferramentas podem ser usadas para perfilamento de desempenho e de memória do seu código gerenciado:

JetBrains Rider com o plugin dotTrace/dotMemory.
JetBrains dotTrace/dotMemory autônomo.
Visual Studio.

O perfilamento de código gerenciado e não gerenciado ao mesmo tempo é possível com as ferramentas da JetBrains e com o Visual Studio, mas é limitado ao Windows.