Up to date

This page is up to date for Godot 4.3. If you still find outdated information, please open an issue.

C# language features

本頁簡介了 C# 與 Godot 常見的功能，以及該如何互相配合。

型別轉換

C# 是靜態型別語言。所以，無法這麼做：

var mySprite = GetNode("MySprite");
mySprite.SetFrame(0);

GetNode() 方法會回傳 Node 實體。必須要明確將回傳值轉換為所需要的型別，在此例中為 Sprite 。

為此，在 C# 中有各種選項。

型別轉換與型別檢查

使用這種方式時，若回傳的結果無法轉換為 Sprite 的話會拋出 InvalidCastException 。若非常確定不會失敗的話，可以使用這種方式來代替 as 運算子。

Sprite2D mySprite = (Sprite2D)GetNode("MySprite");
mySprite.SetFrame(0);

使用 AS 運算子

as 算子會在節點無法轉換為 Sprite 時回傳 null ，因此，無法與實值型別一起使用。

Sprite2D mySprite = GetNode("MySprite") as Sprite2D;
// Only call SetFrame() if mySprite is not null
mySprite?.SetFrame(0);

使用泛型方法

也可以使用泛型方法來透明轉換型別。

GetNode<T>() 可以在執行前就轉換節點型別。當節點無法轉換為需要的型別是，會拋出 InvalidCastException 。

Sprite2D mySprite = GetNode<Sprite2D>("MySprite");
mySprite.SetFrame(0);

GetNodeOrNull<T>() 會使用 as 運算子，且會在節點無法轉換為需要的型別時回傳 null 。

Sprite2D mySprite = GetNodeOrNull<Sprite2D>("MySprite");
// Only call SetFrame() if mySprite is not null
mySprite?.SetFrame(0);

使用 IS 運算子來進行型別檢查

若要檢查節點是否可被轉換為 Sprite，可以使用 is 運算子。is 運算子會在無法將節點轉換為 Sprite 時回傳 false，否則將回傳 true。

if (GetNode("MySprite") is Sprite2D)
{
    // Yup, it's a Sprite2D!
}

if (null is Sprite2D)
{
    // This block can never happen.
}

如果 is 運算子返回 true ，你可以宣告一個新變數來按條件儲存轉換的結果。

if (GetNode("MySprite") is Sprite2D mySprite)
{
    // The mySprite variable only exists inside this block, and it's never null.
    mySprite.SetFrame(0);
}

有關更多型別檢查，請參考模式比對。

定義前置處理器

Godot 中有一系列的定義，可以用來依據編譯環境來更改 C# 程式碼。

範例

例如，可以依據平台來更改程式碼：

    public override void _Ready()
    {
#if (GODOT_32 || GODOT_MOBILE || GODOT_WEB)
        // Use simple objects when running on less powerful systems.
        SpawnSimpleObjects();
#else
        SpawnComplexObjects();
#endif
    }

或者也可以依據程式碼所在引擎來偵測，對於跨引擎函式庫來說很實用：

    public void MyPlatformPrinter()
    {
#if GODOT
        GD.Print("This is Godot.");
#elif UNITY_5_3_OR_NEWER
        print("This is Unity.");
#else
        throw new NotSupportedException("Only Godot and Unity are supported.");
#endif
    }

Or you can write scripts that target multiple Godot versions and take advantage of features that are only available on some of those versions:

    public void UseCoolFeature()
    {
#if GODOT4_3_OR_GREATER || GODOT4_2_2_OR_GREATER
        // Use CoolFeature, that was added to Godot in 4.3 and cherry-picked into 4.2.2, here.
#else
        // Use a workaround for the absence of CoolFeature here.
#endif
    }

完整的定義列表

在 Godot 中，永遠都有定義 GODOT 。
定義 TOOLS ，可在 Debug 環境（編輯器和通過編輯器運作）建構時使用。
將 GodotFloat64 屬性設定為 true 時，將定義 GODOT_REAL_T_IS_DOUBLE 。
依據目前架構是 64 位元還是 32 位元，會有定義 GODOT_64 或 GODOT_32 。
One of GODOT_LINUXBSD, GODOT_WINDOWS, GODOT_OSX, GODOT_ANDROID, GODOT_IOS, GODOT_WEB depending on the OS. These names may change in the future. These are created from the get_name() method of the OS singleton, but not every possible OS the method returns is an OS that Godot with .NET runs on.
GODOTX, GODOTX_Y, GODOTX_Y_Z, GODOTx_OR_GREATER, GODOTX_y_OR_GREATER, and GODOTX_Y_z_OR_GREATER, where X, Y, and Z are replaced by the current major, minor and patch version of Godot. x, y, and z are replaced by all values from 0 to the current version number for that component.

備註

這些定義最早是在 Godot 4.0.4 和 4.1 中新增的。無論目前的 Godot 版本是什麼，之前版本的定義都不存在。

例如: Godot 4.0.5 定義了 GODOT4 、 GODOT4_OR_GREATER 、 GODOT4_0 、 GODOT4_0_OR_GREATER 、 GODOT4_0_5 、 GODOT4_0_4_OR_GREATER 和 GODOT4_0_5_OR_GREATER 。 Godot 4.3.2 定義了 GODOT4 、 GODOT4_OR_GREATER 、 GODOT4_3 、 GODOT4_0_OR_GREATER 、 GODOT4_1_OR_GREATER 、 GODOT4_2_OR_GREATER 、 GODOT4_3_OR_GREATER 、 GODOT4_3_2 、 GODOT4_3_0_OR_GREATER 、 GODOT4_3_1_OR_GREATER 和 GODOT4_3_2_OR_GREATER 。

匯出時，根據匯出的功能也有下列定義：

依據平台型別，會定義 GODOT_PC, GODOT_MOBILE 或 GODOT_WEB 其中一個。
One of GODOT_WINDOWS, GODOT_LINUXBSD, GODOT_MACOS, GODOT_ANDROID, GODOT_IOS, or GODOT_WEB depending on the platform.

若欲檢視範例專案，請參考作業系統示範專案： https://github.com/godotengine/godot-demo-projects/tree/master/misc/os_test