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.

This page provides a brief introduction to C#, both what it is and how to use it in Godot. Afterwards, you may want to look at how to use specific features, read about the differences between the C# and the GDScript API and (re)visit the Scripting section of the step-by-step tutorial.

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¶

Install the latest stable version of the .NET SDK, previously known as the .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 bundles the parts of Mono needed to run already compiled games. However, Godot does not bundle the tools required to build and compile games, such as MSBuild and the C# compiler. These are included in the .NET SDK, which needs to be installed separately.

In summary, you must have installed the .NET SDK and the Mono-enabled version of Godot.

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 Compiling with 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.

To configure a project for debugging open the Godot project folder in VS Code. Go to the Run tab and click on Add Configuration.... Select C# Godot from the dropdown menu. Open the tasks.json and launch.json files that were created. Change the executable setting in launch.json and command settings in tasks.json to your Godot executable path. Now, when you start the debugger in VS Code, your Godot project will run.

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.

Next, you can download the Godot Visual Studio extension from github here. Double click on the downloaded file and follow the installation process.

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 Scripting languages 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 C# API differences to GDScript.

Aviso

You need to (re)build the project assemblies whenever you want to see new exported variables or signals in the editor. This build can be manually triggered by clicking the word Build in the top right corner of the editor. You can also click Mono at the bottom of the editor window to reveal the Mono panel, then click the Build Project button.

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.