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_64
或GODOT_32
。依據作業系統,會定義
GODOT_X11
,GODOT_WINDOWS
,GODOT_OSX
,GODOT_ANDROID
,GODOT_IOS
,GODOT_HTML5
或GODOT_SERVER
中其中一個。這些名稱未來可能會更改。這幾個名稱是從 :ref:OS <class_OS>
單例中的get_name()
定義來的,但並非所有該方法回傳的作業系統都是 Godot 與 Mono 能執行的平台。GODOTX
,GODOTX_Y
,GODOTX_Y_Z
,GODOTx_OR_GREATER
,GODOTX_y_OR_GREATER
, andGODOTX_Y_z_OR_GREATER
, whereX
,Y
, andZ
are replaced by the current major, minor and patch version of Godot.x
,y
, andz
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
, orGODOT_WEB
depending on the platform.
若欲檢視範例專案,請參考作業系統示範專案: https://github.com/godotengine/godot-demo-projects/tree/master/misc/os_test