使用 .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。