Up to date

This page is up to date for Godot 4.2. 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# 程式碼。

備註

若是在 Godot 3.2 版前建立的專案,則需要更改或重新產生 csproj 來使用本功能 (請對照 3.2+ 版專案中的 <DefineConstants> )。

範例

例如,可以依據平台來更改程式碼:

    public override void _Ready()
    {
#if GODOT_SERVER
        // Don't try to load meshes or anything, this is a server!
        LaunchServer();
#elif 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_64GODOT_32

  • 依據作業系統,會定義 GODOT_X11, GODOT_WINDOWS, GODOT_OSX, GODOT_ANDROID, GODOT_IOS, GODOT_HTML5GODOT_SERVER 中其中一個。這些名稱未來可能會更改。這幾個名稱是從 :ref:OS <class_OS> 單例中的 get_name() 定義來的,但並非所有該方法回傳的作業系統都是 Godot 與 Mono 能執行的平台。

  • 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 定義了 GODOT4GODOT4_OR_GREATERGODOT4_0GODOT4_0_OR_GREATERGODOT4_0_5GODOT4_0_4_OR_GREATERGODOT4_0_5_OR_GREATER 。 Godot 4.3.2 定義了 GODOT4GODOT4_OR_GREATERGODOT4_3GODOT4_0_OR_GREATERGODOT4_1_OR_GREATERGODOT4_2_OR_GREATERGODOT4_3_OR_GREATERGODOT4_3_2GODOT4_3_0_OR_GREATERGODOT4_3_1_OR_GREATERGODOT4_3_2_OR_GREATER

匯出 時,根據匯出的功能也有下列定義:

  • 依據平台型別,會定義 GODOT_PC, GODOT_MOBILEGODOT_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