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

Compilando com .NET

Requisitos

  • .NET SDK 8.0+

    Você pode usar dotnet --info para verificar quais versões do .NET SDK estão instaladas.

Habilitar o módulo .NET

Nota

O suporte a C# no Godot historicamente usou o runtime do Mono em vez do .NET Runtime e internamente muitas coisas ainda são chamadas de mono em vez de dotnet ou referidas como mono por outros motivos.

Por padrão, o módulo .NET fica desativado ao buildar. Para habilitá-lo, adicione a opção module_mono_enabled=yes à linha de comando do SCons, enquanto segue as instruções normais para buildar os binários desejados do Godot.

Gerar o glue

Partes dos códigos-fonte das bibliotecas gerenciadas são geradas a partir do ClassDB. Esses arquivos de origem devem ser gerados antes de buildar as bibliotecas gerenciadas. Eles podem ser gerados por qualquer binário de editor do Godot habilitado para .NET executando-o com os parâmetros --headless --generate-mono-glue seguidos pelo caminho para um diretório de saída. Esse caminho deve ser modules/mono/glue no diretório do Godot:

<godot_binary> --headless --generate-mono-glue modules/mono/glue

Este comando dirá ao Godot para gerar as vinculações C# para a API do Godot em modules/mono/glue/GodotSharp/GodotSharp/Generated e as vinculações C# para as ferramentas do editor em modules/mono/glue/GodotSharp/GodotSharpEditor/Generated. Uma vez gerados esses arquivos, você pode buildar as bibliotecas gerenciadas do Godot para todos os alvos desejados sem precisar repetir esse processo.

<godot_binary> refere-se ao binário do editor que você compilou com o módulo .NET habilitado. Seu nome exato variará com base no seu sistema e configuração, mas deve ser da forma bin/godot.<platform>.editor.<arch>.mono, ex.: bin/godot.linuxbsd.editor.x86_64.mono ou bin/godot.windows.editor.x86_32.mono.exe. Fique especialmente atento ao sufixo .mono! Se você compilou o Godot anteriormente sem suporte ao .NET, poderá ter binários com nomes semelhantes sem esse sufixo. Esses binários não podem ser usados para gerar o glue do .NET.

Nota

As fontes do glue devem ser regeneradas toda vez que a API registrada no ClassDB mudar. Isso ocorre, por exemplo, quando um novo método é registrado na API de script ou um dos parâmetros de tal método muda. O Godot exibirá um erro na inicialização se houver uma incompatibilidade de API entre o ClassDB e as fontes do glue.

Construindo as bibliotecas gerenciadas

Depois de gerar o glue do .NET, você pode buildar as bibliotecas gerenciadas com o script build_assemblies.py:

./modules/mono/build_scripts/build_assemblies.py --godot-output-dir=./bin

Se tudo correu bem, o diretório GodotSharp, contendo las bibliotecas gerenciadas, deve ter sido criado no diretório bin.

Nota

Por padrão, todos os builds de desenvolvimento compartilham um número de versão, o que pode causar alguns problemas com o cache dos pacotes NuGet. Para resolver esse problema, use GODOT_VERSION_STATUS para dar a cada build uma versão exclusiva ou exclua a pasta GodotNuGetFallbackFolder após cada build para limpar o cache de pacotes.

Ao contrário dos builds "clássicos" do Godot, ao buildar com o módulo .NET habilitado (e dependendo da plataforma de destino), um diretório de dados pode ser criado tanto para o editor quanto para os projetos exportados. Esse diretório é importante para o funcionamento adequado e deve ser distribuído junto com o Godot. Mais detalhes sobre esse diretório em Data directory.

Plataforma de build

Forneça o argumento --godot-platform=<platform> para controlar para qual plataforma específica as bibliotecas são buildadas. Omita este argumento para buildar para o sistema atual.

Atualmente, isso controla apenas a inclusão do suporte para o Visual Studio como um editor externo; caso contrário, as bibliotecas são idênticas.

Pacotes NuGet

Os assemblies da API, geradores de código-fonte e o SDK de projeto MSBuild personalizado são distribuídos como pacotes NuGet. Isso tudo é transparente para o usuário, mas pode tornar as coisas complicadas durante o desenvolvimento.

Para usar o Godot com uma versão de desenvolvimento desses pacotes, uma fonte local do NuGet deve ser criada onde o MSBuild possa encontrá-los.

Primeiro, escolha um local para a fonte local do NuGet. Se você não tiver preferência, crie um diretório vazio em um destes locais recomendados:

  • No Windows, C:\Users\<username>\MyLocalNugetSource

  • No Linux, *BSD, etc., ~/MyLocalNugetSource

Este caminho será referido mais tarde como <my_local_source>.

Depois de escolher um diretório, execute este comando da CLI do .NET para configurar o NuGet para usar sua fonte local:

dotnet nuget add source <my_local_source> --name MyLocalNugetSource

Ao executar o script build_assemblies.py, passe <my_local_source> para a opção --push-nupkgs-local:

./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source>

Esta opção garante que os pacotes serão adicionados à fonte local do NuGet especificada e que as versões conflitantes do pacote sejam removidas do cache do NuGet. Recomenda-se sempre usar essa opção ao buildar as soluções C# durante o desenvolvimento para evitar erros.

Buildando sem depender de recursos obsoletos (NO_DEPRECATED)

Ao buildar o Godot sem classes e funções obsoletas, ou seja, com o argumento deprecated=no para o scons, as bibliotecas gerenciadas também devem ser buildadas sem dependências de código obsoleto. Isso é feito passando o argumento --no-deprecated:

./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --no-deprecated

Suporte a Precisão Dupla (REAL_T_IS_DOUBLE)

Ao buildar o Godot com suporte a precisão dupla, ou seja, com o argumento precision=double para o scons, as bibliotecas gerenciadas devem ser ajustadas para corresponder passando o argumento --precision=double:

./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --precision=double

Exemplos

Exemplos (Windows)

# Build editor binary
scons platform=windows target=editor module_mono_enabled=yes
# Build export templates
scons platform=windows target=template_debug module_mono_enabled=yes
scons platform=windows target=template_release module_mono_enabled=yes

# Generate glue sources
bin/godot.windows.editor.x86_64.mono --headless --generate-mono-glue modules/mono/glue
# Build .NET assemblies
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --godot-platform=windows

Exemplo (Linux, *BSD)

# Build editor binary
scons platform=linuxbsd target=editor module_mono_enabled=yes
# Build export templates
scons platform=linuxbsd target=template_debug module_mono_enabled=yes
scons platform=linuxbsd target=template_release module_mono_enabled=yes

# Generate glue sources
bin/godot.linuxbsd.editor.x86_64.mono --headless --generate-mono-glue modules/mono/glue
# Generate binaries
./modules/mono/build_scripts/build_assemblies.py --godot-output-dir ./bin --push-nupkgs-local <my_local_source> --godot-platform=linuxbsd

Diretório de dados

O diretório de dados é uma dependência para binários do Godot buildados com o módulo .NET habilitado. Ele contém arquivos importantes para o funcionamento correto do Godot. Ele deve ser distribuído junto com o executável do Godot.

Editor

O nome do diretório de dados para o editor do Godot sempre será GodotSharp. Este diretório contém um subdiretório Api com os assemblies da API do Godot e um subdiretório Tools com as ferramentas exigidas pelo editor, como os assemblies GodotTools e suas dependências.

No macOS, se o editor do Godot for distribuído como um bundle, o diretório GodotSharp poderá ser colocado no diretório <bundle_name>.app/Contents/Resources/ dentro do bundle.

Modelos de exportação

O diretório de dados para projetos exportados é gerado pelo editor durante a exportação. Ele é nomeado data_<APPNAME>_<ARCH>, onde <APPNAME> é o nome do aplicativo conforme especificado na configuração do projeto application/config/name e <ARCH> é a arquitetura atual da exportação.

No caso de exportações multiarquitetura, múltiplos diretórios de dados desse tipo serão gerados.

Opções de linha de comando

A seguir está a lista de opções de linha de comando disponíveis ao buildar com o módulo .NET:

  • module_mono_enabled=yes | no

    • Builde o Godot com o módulo .NET habilitado.