Noções básicas de C#¶

Introdução¶

Aviso

O suporte a C# é um recurso novo disponível desde o Godot 3.0. Por isso, você ainda pode se deparar com alguns problemas, ou encontrar lugares onde a documentação poderia ser melhorada. Por favor relate problemas com C# no Godot na página do motor no Github, e qualquer problema de documentação na página da documentação no Github.

Esta página fornece uma breve introdução ao C#, tanto o que ele é como como usá-lo no Godot. Depois, você pode querer olhar para como utilizar características específicas, leia sobre a diferenças entre o C# e o GDScript API e (re)visite a seção deScript do tutorial passo-a-passo.

C# é uma linguagem de programação de alto nível desenvolvida pela Microsoft. No Godot, ela é implementada com o framework Mono 5.2 .NET, incluindo suporte completo para o C# 8.0. O Mono é uma implementação de código aberto do .NET Framework da Microsoft, baseado nos padrões ECMA para C# e Common Language Runtime. Um bom ponto de partida para verificar seus recursos é a página Compatibility na documentação do Mono.

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.

Configurando o C# para Godot¶

Pré-requisitos¶

Instalar a última versão estável do .NET SDK, anteriormente conhecido como o .NET Core SDK.

A partir do Godot 3.2.3, a instalação do Mono SDK não é mais um requisito, exceto se você estiver compilando o motor a partir do código-fonte.

Godot agrupa as partes do Mono necessárias para executar jogos já compilados. Entretanto, o Godot não reúne as ferramentas necessárias para construir e compilar jogos, como o MSBuild e o compilador C#. Estas estão incluídas no SDK .NET, que precisa ser instalado separadamente.

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

Notas adicionais¶

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 compilando o Godot a partir do código-fonte, instale a versão estável mais recente do Mono, e certifique-se de seguir os passos para habilitar o suporte ao Mono conforme descrito na página Compilando com Mono.

Configurando um editor externo¶

O suporte a C# no editor de scripts embutido do Godot é minimo. Considere usar uma IDE ou editor externos, como por exemplo Visual Studio Code ou MonoDevelop. Estes editores possuem preenchimento automático, ferramentas de depuração e outras funcionalidades úteis para o desenvolvimento em C#. Para selecionar um editor externo no Godot, clique em Editor -> Configurações do Editor e role a página até o Mono. Em Mono, clique em Editor então selecione o editor de sua preferência. Godot atualmente dá suporte aos seguintes editores externos:

Visual Studio 2019
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 Mono -> Editor -> External Editor como JetBrains Rider.
Defina Mono -> Builds -> Build Tool para dotnet CLI.

No Rider:

Defina a versão do MSBuild para .NET Core.
Instale o plugin de suporte do Godot.

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 Mono -> Editor -> External Editor para Visual Studio Code.
Defina Mono -> Builds -> Build Tool para dotnet CLI.

No Visual Studio Code:

Instale a extensão C#.
Instale a extensão Mono Debug.
Instale a extensão C# Tools for Godot.

Nota

Se você está usando Linux, você precisa instalar o Mono SDK <https://www.mono-project.com/download/stable/#download-lin> para que o plugin de ferramentas C# funcione.

Para configurar um projeto de depuração, abra a pasta do projeto Godot no Código VS. Vá até a aba Run e clique em Adicionar configuração.... Selecione C# Godot a partir do menu suspenso. Abra os arquivos tasks.json e launch.json que foram criados. Altere a configuração do executável em launch.json e as configurações de comando em tasks.json para seu caminho do executável Godot. Agora, quando você iniciar o depurador em VS Code, seu projeto 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 estas cargas de trabalho:

Desenvolvimento mobile com .NET
Desenvolvimento de plataforma cruzada do .NET Core

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

Defina Mono -> Editor -> External Editor para Visual Studio.
Defina Mono -> Builds -> Build Tool para dotnet CLI.

A seguir, você pode baixar a extensão Godot Visual Studio do github aqui. Clique duas vezes no arquivo baixado e siga o processo de instalação.

Nota

The option to debug your game in Visual Studio may not appear after installing the extension. To enable debugging, there is a workaround for Visual Studio 2019. There is a separate issue about this problem in Visual Studio 2022.

Nota

If you see an error like "Unable to find package Godot.NET.Sdk", your NuGet configuration may be incorrect and need to be fixed.

A simple way to fix the NuGet configuration file is to regenerate it. In a file explorer window, go to %AppData%\NuGet. Rename or delete the NuGet.Config file. When you build your Godot project again, the file will be automatically created with default values.

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:

Observe que, embora alguns detalhes sejam alterados, a maioria dos conceitos funcionam da mesma maneira quando se usa o C# para criação de scripts. Se você é novo no Godot, você pode querer examinar os tutoriais em Linguagens de script neste ponto. Enquanto alguns lugares na documentação ainda não tenham exemplos de C#, a maioria dos conceitos podem ser facilmente transferidos do GDScript.

Configuração de projeto e fluxo de trabalho¶

Quando você cria o primeiro script C#, o Godot inicializa os arquivos de projeto C# para seu projeto Godot. Isto inclui gerar uma solução C# (.sln) e um arquivo de projeto (.csproj) assim como alguns arquivos e pastas de utilitários (.mono, as vezes Properties/AssemblyInfo.cs). Todos estes, exceto .mono, são importantes e devem ser mantidos em seu sistema de controle de versão. O .mono pode ser adicionado com segurança à lista de ignorados do seu VCS. Para solucionar problemas, às vezes pode ajudar excluir a pasta .mono e deixá-la regenerar.

Exemplo¶

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

using Godot;
using System;

public 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(float delta)
    {
        // Called every frame. Delta is time since the last frame.
        // Update game logic here.
    }
}

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

Nota

Tenha em mente que a classe que você deseja anexar ao seu nó deve ser nomeada como um arquivo .cs. Caso contrário, você receberá o seguinte erro e não poderá executar a cena: "Não é 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 as montagens do projeto sempre que quiser ver novas variáveis ou sinais exportados no editor. Esta construção pode ser acionada manualmente, clicando na palavra Build no canto superior direito do editor. Você também pode clicar em Mono na parte inferior da janela do editor para revelar o painel Mono, depois clique no botão Build Project.

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 novo no Godot, existem alguns sacrifícios e coisas que ainda precisam ser resolvidas. Abaixo segue uma lista das questões mais importantes que você deve estar ciente ao mergulhar em C# no Godot, mas em caso de dúvida, também dê uma olhada no rastreador de problemas para Mono oficial.

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 método de conexão de sinal Connect() que dependem dos padrões de nomeação da API snake_case de Godot. Então, por exemplo ao usar CallDeferred("AddChild"), AddChild não vai funcionar porque a API está esperando a chamada no formato snake_case como add_child. No entanto, você pode usar quaisquer propriedades ou métodos personalizados sem essa limitação.

A exportação de projetos Mono é suportada apenas para plataformas desktop (Linux, Windows e macOS), Android, HTML5 e iOS. A única plataforma ainda não suportada é UWP.

Desempenho do C# no Godot¶

De acordo com alguns benchmarks preliminares, o desempenho do C# no Godot — embora geralmente na mesma ordem de magnitude — é aproximadamente ~ 4x o do GDScript em alguns casos simples. Para o desempenho total, o C++ ainda é um pouco mais rápido; os detalhes vão variar de acordo com o seu caso de uso. O GDScript provavelmente é rápido o suficiente para a maioria das cargas de trabalho de scripts gerais. O C# é mais rápido, mas requer algum treinamento custoso quando falamos do Godot.

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>

A partir da versão 3.2.3, o Godot automaticamente baixa e instala os últimos pacotes NuGet na próxima vez que ele compila o projeto.

Perfilando seu código C#¶

Mono log profiler está disponível para Linux e macOS. Devido a uma mudança do Mono, ele não funciona no Windows atualmente.
Profiler de Mono Externo como JetBrains dotTrace pode ser usado como descrito aqui.