C# 基礎

簡介

警告

C# 是自 Godot 3.0 版起新增的新功能。因此可能還是會遇到一些問題,或是有文件需要改進的地方。請在 Godot 的 GitHub 頁面 上回報與 C# 有關的問題,而文件相關的問題請於 說明文件 GitHub 頁面 回報。

本頁提供了 C# 的簡介,包含 C# 為何以及如何在 Godot 中使用。之後,建議您也閱讀 如何使用特定功能C# 與 GDScript API 的比較 以及 (再次) 閱讀按部就班教學中的 腳本段落

C# 是由 Microsoft 開發的高級程式語言。在 Godot 中的 C# 是基於 Mono 6.x .NET 框架實作的,包含對 C# 8.0 的完整支援。Mono 是基於 C# 與通用語言執行環境的 ECMA 標準實作的開放原始碼版 Microsoft .NET 框架。從 Mono 文件的 相容性 (英文) 頁面開始是一個不錯的選項。

備註

本教學 不是 完整的 C# 語言教學。若您不熟悉 C# 的語法與功能,請參考 Microsoft C# 指南 或尋找其它合適的介紹。

為 Godot 設定 C#

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.

其他注意事項

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 通過 Mono 進行編譯 page.

設定外部編輯器

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

  • Mac 版 Visual Studio

  • JetBrains Rider

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

JetBrains Rider

After reading the "Prerequisites" section, you can download and install 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.

Rider 中:

  • Set MSBuild version to .NET Core.

  • 安裝 Godot support 外掛。

Visual Studio Code

After reading the "Prerequisites" section, you can download and install Visual Studio Code (aka VS Code).

In Godot's Editor → Editor Settings menu:

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

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

Download and install the latest version of Visual Studio. Visual Studio will include the required SDKs if you have the correct workloads selected, so you don't need to manually install the things listed in the "Prerequisites" section.

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.

建立 C# 腳本

成功為 Godot 設定好 C# 後,應該可以在從場景中節點右鍵選單中選擇 [附加腳本] 時看到下列選項:

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

請注意,雖然某些功能不同,但使用 C# 撰寫腳本時大部分概念都一樣。若還不熟悉 Godot,則建議您先閱讀 撰寫腳本 中的教學。雖然文件中的某些部分還沒有 C# 範例,但大部分概念都很容易從 GDScript 轉過來。

專案設定與工作流程

建立第一個 C# 腳本後,Godot 會為目前的 Godot 專案初始化 C# 專案檔。包含產生 C# 解決方案 (.sln) 與專案檔 (.csproj)、以及一些公用檔案與資料夾 (.monoProperties/AssemblyInfo.cs)。這些檔案除了 .mono 之外都很重要,且應該被認可 (Commit) 至版本控制系統中。.mono 可以安全地新增到 VCS 中的忽略列表內,有時候可能會需要刪除 .mono 資料夾並讓 Godot 重新產生。

範例

下列為一個空白的 C# 腳本,包含了一些說明如何運作的註解。

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

就像這樣,在 GDScript 中通常在全域的函式,如 Godot 的 print 函式,都在 Godot 命名空間中的 GD 類別內。要取得 GD 類別中所有方法的列表,請參考類別參照頁面中的 @GDScript@GlobalScope

備註

請記得,要附加到節點上的類別必須與 .cs 檔案的檔名相同。否則會得到下列錯誤且無法執行場景: 「Cannot find class XXX for script res://XXX.cs」

C# 與 GDScript 間的一般差異

C# API 使用 PascalCase 而不是 GDScript/C++ 的 snake_case 。欄位、Getter、Setter 都儘量轉換成屬性。一般來說,C# Godot API 都在合理情況下儘量保持其習慣。

更多資訊請參考 C# API 與 GDScript 的不同 一頁。

警告

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.

接著還需要重新建置專案組建,以套用「工具」腳本中的改動。

目前狀況與已知問題

由於 Godot 中的 C# 支援還很新,所以還有一些需要解決的問題。下表為在 Godot 中使用 C# 需要注意的幾個最重要的問題,另外也請參考一下官方的 Mono 問題追蹤器

  • 雖然還是可以寫編輯器外掛,但目前很複雜。

  • 除了匯出的變數以外,熱重載時狀態不會保存並重新載入。

  • 附加 C# 腳本時參照的類別名稱必須與檔名一致。

  • 有些方法,如 Get()/Set(), Call()/CallDeferred() 與訊號連接方法 Connect() 都還依賴 Godot 的 snake_case API 命名規範。所以使用如 CallDeferred("AddChild") 時,無法正常使用 AddChild ,因為 API 預期使用原本 snake_case 版的 add_child 。但依然可以使用自定屬性與方法而不受此限。

Exporting Mono projects is supported for desktop platforms (Linux, Windows and macOS), Android, HTML5, and iOS. The only platform not supported yet is UWP.

Godot 中的 C# 效能

根據一些初步的 效能評定 ,在一般情況下,Godot 中的 C# 效能比起一些單純的 GDScript 情況還要快上 ~ 4 倍 。C++ 依然稍微快一點。實際情況還是依據使用方式而異。GDScript 一般來說對於普通的程式編寫來說已經夠快了,而 C# 雖然更快,但與 Godot 通訊時則需要耗費許多吃效能的封送處理。

在 Godot 中使用 NuGet 套件

可以在 Godot 中配合任意 C# 專案安裝與使用 NuGet 套件。許多 IDE 都支援直接新增套件,這些套件也可以通過在專案根目錄的 .csproj 檔內加上套件參照來手動新增:

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

對 C# 程式進行程式碼剖析

  • 在 Linux 與 macOS 中可以使用 Mono Log Profiler 。由於 Mono 的更改,目前該工具無法在 Windows 上使用。

  • JetBrains dotTrace 等外部 Mono 剖析器可以按照 這裡 說明的方式使用。