Noções básicas de C#

Introdução

Aviso

Suporte a C# é um novo recurso no 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# is a high-level programming language developed by Microsoft. In Godot, it is implemented with the Mono 6.x .NET framework, including full support for C# 8.0. Mono is an open source implementation of Microsoft's .NET Framework based on the ECMA standards for C# and the Common Language Runtime. A good starting point for checking its capabilities is the Compatibility page in the Mono documentation.

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.

Setting up C# for Godot

Prerequisites

Install the latest stable version of .NET Core SDK (3.1 as of writing).

From Godot 3.2.3 onwards, installing Mono SDK is not a requirement anymore, except it is required if you are building the engine from source.

Godot bundles the parts of Mono needed to run already compiled games, however Godot does not include the tools required to build and compile games, such as MSBuild. These tools need to be installed separately. The required tools are included in the .NET Core SDK. MSBuild is also included in the Mono SDK, but it can't build C# projects with the new csproj format, therefore .NET Core SDK is required for Godot 3.2.3+.

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

Additional notes

Be sure to install the 64-bit version of the SDK(s) if you are using the 64-bit version of Godot.

If you are building Godot from source, install the latest stable version of Mono, and make sure to follow the steps to enable Mono support in your build as outlined in the Compiling with Mono page.

Configurando um editor externo

C# support in Godot's built-in script editor is minimal. Consider using an external IDE or editor, such as Visual Studio Code or MonoDevelop. These provide autocompletion, debugging, and other useful features for C#. To select an external editor in Godot, click on Editor → Editor Settings and scroll down to Mono. Under Mono, click on Editor, and select your external editor of choice. Godot currently supports the following external editors:

  • Visual Studio 2019

  • Visual Studio Code

  • MonoDevelop

  • Visual Studio for Mac

  • JetBrains Rider

See the following sections for how to configure an external editor:

JetBrains Rider

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

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to JetBrains Rider.

  • Set Mono -> Builds -> Build Tool to dotnet CLI.

In Rider:

  • Set MSBuild version to .NET Core.

  • Install the Godot support plugin.

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

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to Visual Studio Code.

Visual Studio Code:

To configure a project for debugging open the Godot project folder in VS Code. Go to the Run tab and click on create a launch.json file. Select C# Godot from the dropdown menu. Now, when you start the debugger in VS Code your Godot project will run.

Visual Studio (Windows only)

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

While installing Visual Studio, select these workloads:

  • Mobile development with .NET

  • .NET Core cross-platform development

In Godot's Editor → Editor Settings menu:

  • Set Mono -> Editor -> External Editor to Visual Studio.

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

Criando um script C#

After you successfully set up C# for Godot, you should see the following option when selecting Attach Script in the context menu of a node in your scene:

../../../_images/attachcsharpscript.png

Note that while some specifics change, most concepts work the same when using C# for scripting. If you're new to Godot, you may want to follow the tutorials on Scripting at this point. While some places in the documentation still lack C# examples, most concepts can be transferred easily from GDScript.

Configuração de projeto e fluxo de trabalho

When you create the first C# script, Godot initializes the C# project files for your Godot project. This includes generating a C# solution (.sln) and a project file (.csproj), as well as some utility files and folders (.mono and Properties/AssemblyInfo.cs). All of these but .mono are important and should be committed to your version control system. .mono can be safely added to the ignore list of your VCS. When troubleshooting, it can sometimes help to delete the .mono folder and let it regenerate.

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

As you can see, functions normally in global scope in GDScript like Godot's print function are available in the GD class which is part of the Godot namespace. For a list of methods in the GD class, see the class reference pages for @GDScript and @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.

For more information, see the C# API differences to GDScript page.

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.

You will also need to rebuild the project assemblies to apply changes in "tool" scripts.

Pegadinhas gerais e problemas conhecidos

As C# support is quite new in Godot, there are some growing pains and things that need to be ironed out. Below is a list of the most important issues you should be aware of when diving into C# in Godot, but if in doubt, also take a look over the official issue tracker for Mono issues.

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

Performance do C# no Godot

According to some preliminary benchmarks, the performance of C# in Godot — while generally in the same order of magnitude — is roughly ~4× that of GDScript in some naive cases. C++ is still a little faster; the specifics are going to vary according to your use case. GDScript is likely fast enough for most general scripting workloads. C# is faster, but requires some expensive marshalling when talking to Godot.

Using NuGet packages in Godot

NuGet packages can be installed and used with Godot, as with any C# project. Many IDEs are able to add packages directly. They can also be added manually by adding the package reference in the .csproj file located in the project root:

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

As of Godot 3.2.3, Godot automatically downloads and sets up newly added NuGet packages the next time it builds the project.

Perfilando seu código C#

  • Mono log profiler is available for Linux and macOS. Due to a Mono change, it does not work on Windows currently.

  • Profiler de Mono Externo como JetBrains dotTrace pode ser usado como descrito aqui.