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

使用 .NET 編譯

系統需求

  • .NET SDK 8.0+

    你可以使用 dotnet --info 來檢查已安裝的 .NET SDK 版本。

啟用 .NET 模組

備註

Godot 的 C# 支援過去一直使用 Mono 執行階段，而非 .NET Runtime，因此在內部許多名稱仍以 mono 命名，而非 dotnet 或其他名稱。

預設情況下，.NET 模組在建置時是關閉的。若要啟用，請在 SCons 命令列加上 module_mono_enabled=yes 選項，其餘步驟請參照一般 Godot 二進位檔的建置說明。

產生 Glue（黏合代碼）

部分託管函式庫的原始碼是由 ClassDB 自動產生。這些檔案在建置託管函式庫前必須先產生。可以使用任何啟用 .NET 的 Godot 編輯器執行檔，搭配 --headless --generate-mono-glue 參數與輸出路徑來產生。該路徑需為 Godot 目錄下的 modules/mono/glue：

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

這個指令會讓 Godot 產生 Godot API 的 C# 繫結於 modules/mono/glue/GodotSharp/GodotSharp/Generated，以及編輯器工具的繫結於 modules/mono/glue/GodotSharp/GodotSharpEditor/Generated。完成後，你就可以針對所有目標平台建置 Godot 的託管函式庫，無須重複產生這些檔案。

<godot_binary> 指的是你用來啟用 .NET 模組編譯出來的 Godot 編輯器執行檔。檔案名稱會依作業系統與設定而異，但通常格式為 bin/godot.<平台>.editor.<架構>.mono，例如 bin/godot.linuxbsd.editor.x86_64.mono 或 bin/godot.windows.editor.x86_32.mono.exe。請特別注意 .mono 字尾！若你先前編譯時未啟用 .NET 支援，也許會有名稱類似但不含 .mono 字尾的執行檔，這些不能用來產生 .NET glue。

備註

每當 ClassDB 註冊的 API 有變動時（例如新增腳本 API 方法或更改參數），都必須重新產生 Glue 原始檔。若 ClassDB 與 Glue 檔案的 API 不一致，Godot 啟動時會出現錯誤訊息。

建置託管函式庫

產生 .NET glue 後，可以使用 build_assemblies.py 腳本來建置託管函式庫：

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

若順利完成，包含託管函式庫的 GodotSharp 目錄應會在 bin 目錄下被建立。

備註

預設情況下，所有開發版都共用同一個版本號，這可能導致 NuGet 套件快取出現問題。可透過設定 GODOT_VERSION_STATUS 為每個建置指定唯一版本，或在每次建置後刪除 GodotNuGetFallbackFolder 以清除套件快取來解決此問題。

與「傳統」Godot 建置不同，啟用 .NET 模組（且依目標平台）時，可能會為編輯器與匯出專案產生資料目錄。這個目錄對 Godot 的正常運作非常重要，必須與 Godot 一同發行。更多細節請參見 資料目錄。

建置平台

請使用 --godot-platform=<platform> 參數來指定要建置哪個平台的函式庫。如不指定，則會針對目前系統建置。

目前，這僅影響是否包含 Visual Studio 作為外部編輯器的支援，其餘函式庫內容則相同。

NuGet 套件

API 組件、原始碼產生器與自訂 MSBuild 專案 SDK 會以 NuGet 套件形式發佈。這些對使用者來說是透明的，但在開發過程中可能會帶來複雜度。

若要讓 Godot 使用這些套件的開發版本，你必須建立一個本機 NuGet 來源，讓 MSBuild 能找到這些套件。

首先，選擇一個作為本機 NuGet 來源的位置。如果沒有偏好，建議於下列其中一個位置建立一個空目錄：

  • 在 Windows 上，C:\Users\<username>\MyLocalNugetSource

  • 在 Linux、*BSD 等系統上，~/MyLocalNugetSource

後續會以 <my_local_source> 代表此路徑。

選定資料夾後，請執行以下 .NET CLI 指令以設定 NuGet 使用你的本機來源：

dotnet nuget add source <my_local_source> --name MyLocalNugetSource

執行 build_assemblies.py 腳本時，請將 <my_local_source> 傳給 --push-nupkgs-local 選項：

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

這個選項會將套件加入指定的本機 NuGet 來源，並移除 NuGet 快取中的衝突版本。建議在開發期間建置 C# 解決方案時一律使用此選項，以避免出錯。

不依賴已淘汰功能的建置（NO_DEPRECATED）

當以 deprecated=no 參數（scons）建置 Godot、排除所有已淘汰的類別與函式時，託管函式庫也需同樣排除這些相依。可於建置時加入 --no-deprecated 參數：

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

雙精度支援 (REAL_T_IS_DOUBLE)

當以 precision=double 參數（scons）建置支援雙精度的 Godot 時，託管函式庫也必須加入 --precision=double 參數以配合：

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

範例

範例（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

範例（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

資料目錄

資料目錄是啟用 .NET 模組編譯的 Godot 二進位檔所需的相依檔案，裡面包含 Godot 正常運作所需的重要檔案。發佈 Godot 執行檔時必須一併發佈此目錄。

編輯器

Godot 編輯器的資料目錄名稱永遠為 GodotSharp。此目錄下有 Api 子目錄（包含 Godot API 組件）與 Tools 子目錄（包含編輯器所需工具，如 GodotTools 組件及其相依檔案）。

在 macOS 上，若 Godot 編輯器以 App Bundle 發佈，則 GodotSharp 目錄會放在 <bundle_name>.app/Contents/Resources/ 目錄內。

匯出樣板

匯出專案時，資料目錄會由編輯器自動產生。其名稱為 data_<APPNAME>_<ARCH>，其中 <APPNAME> 取自專案設定 application/config/name，<ARCH> 則為當前匯出的架構。

若匯出多架構版本，則會產生多個對應的資料目錄。

命令列選項

以下是使用 .NET 模組建置時可用的命令列選項：

  • module_mono_enabled=yes | no

    • 啟用 .NET 模組建置 Godot。