C# API 與 GDScript 的不同¶
本頁列出了 (不完整的) C# 與 GDScript 間的 API 差異。
一般差異¶
如同在 C# 基礎 中解釋的一樣,C# 一般會使用 PascalCase
而不是 GDScript 與 C++ 所使用的 snake_case
。
全域作用域¶
全域函式與一些常數被移到類別裡了,因為 C# 不允許在命名空間中定義這些函式與常數。大部分全域常數都被移到各自的列舉類型中了。
常數¶
全域常數移至其各自的列舉類型。例如, ERR_*
常數移動到了 Error
列舉類型中。
特例:
GDScript |
C# |
---|---|
|
|
|
|
|
|
數學函式¶
數學全域函式,如 abs
, acos
, asin
, atan
與 atan2
,都放在了 Mathf
下,命名為 Abs
, Acos
, Asin
, Atan
與 Atan2
。 PI
常數則為 Mathf.Pi
。
隨機數函式¶
隨機數全域函式,如 rand_range
與 rand_seed
,都放在 GD
底下。如: GD.RandRange
與 GD.RandSeed
。
其他函式¶
許多其他的全域函式,如 print
與 var2str
都放在 GD
底下。如 GD.Print
與 GD.Var2Str
。
例外:
GDScript |
C# |
---|---|
|
|
|
|
提示¶
有時候,使用 using static
指示詞也很有用。使用這個指示詞就可以存取類別的成員與巢狀型別而無需指定類別名稱。
範例:
using static Godot.GD;
public class Test
{
static Test()
{
Print("Hello"); // Instead of GD.Print("Hello");
}
}
匯出關鍵字¶
使用 [Export]
屬性來取代 GDScript 中的 export
關鍵字。這個屬性也可以加上可選的 PropertyHint 與 hintString
參數。預設值可以通過指派數值來設定。
範例:
using Godot;
public class MyNode : Node
{
[Export]
private NodePath _nodePath;
[Export]
private string _name = "default";
[Export(PropertyHint.Range, "0,100000,1000,or_greater")]
private int _income;
[Export(PropertyHint.File, "*.png,*.jpg")]
private string _icon;
}
訊號關鍵字¶
使用 [Signal]
屬性來取代 GDScript 中的 signal
關鍵字宣告訊號。這個屬性也可以用在 **delegate`` 上,其名稱簽名會用來定義訊號。
[Signal]
delegate void MySignal(string willSendsAString);
參見 c_sharp_signals 。
onready keyword¶
GDScript has the ability to defer the initialization of a member variable until the ready function is called with onready (cf. onready keyword). For example:
onready var my_label = get_node("MyLabel")
However C# does not have this ability. To achieve the same effect you need to do this.
private Label _myLabel;
public override void _Ready()
{
_myLabel = GetNode<Label>("MyLabel");
}
單例¶
單例為靜態類別,而不是使用單例模式。這樣可以讓程式碼比起使用 Instance
屬性來得簡單。
範例:
Input.IsActionPressed("ui_down")
但,在某些罕見情況下,這樣還不夠。如,我們可能需要存取基礎類型 Godot.Object
中的成員,如 Connect
。這種情況下,可以使用一個靜態屬性,名為 Singleton
,這個屬性會回傳單例實體。該實體的型別為 Godot.Object
。
範例:
Input.Singleton.Connect("joy_connection_changed", this, nameof(Input_JoyConnectionChanged));
字串¶
使用 System.String
(string
) 。大多數 Godot 的字串方法都由 StringExtensions
類別作為擴充方法提供。
範例:
string upper = "I LIKE SALAD FORKS";
string lower = upper.ToLower();
雖然有一些不同的地方:
erase
:在 C# 中的字串是不可變的,所以若傳到擴充方法中的字串無法修改。因此,Erase
方法被新增到StringBuilder
中作為擴充方法,而非字串。或者也可使用string.Remove
。IsSubsequenceOf
/IsSubsequenceOfi
:有另一個方法,為一個IsSubsequenceOf
的重載,可以顯示指定區分大小寫:
str.IsSubsequenceOf("ok"); // Case sensitive
str.IsSubsequenceOf("ok", true); // Case sensitive
str.IsSubsequenceOfi("ok"); // Case insensitive
str.IsSubsequenceOf("ok", false); // Case insensitive
Match
/Matchn
/ExprMatch
:除了Match
與Matchn
之外還提供了一個額外的方法,用來明確指定區分大小寫:
str.Match("*.txt"); // Case sensitive
str.ExprMatch("*.txt", true); // Case sensitive
str.Matchn("*.txt"); // Case insensitive
str.ExprMatch("*.txt", false); // Case insensitive
Basis¶
在 C# 中,結構為無參數的建置函式。因此 new Basis()
會初始化所有原始成員並設為預設值。使用 Basis.Identity
與 GDScript 與 C++ 中的 Basis()
等效。
下列方法轉換成了名稱不同的屬性:
GDScript |
C# |
---|---|
|
|
Transform2D¶
在 C# 中,結構為無參數的建置函式。因此,new Transform2D()
會初始化所有原始成員並設為預設值。請使用 Transform2D.Identity
來達成與 GDScript 或 C++ 中 Transform2D()
同等的效果。
下列各個方法皆轉換為屬性並更改其名稱:
GDScript |
C# |
---|---|
|
|
|
|
平面¶
下列方法被轉換成了名稱 稍微 不同的屬性:
GDScript |
C# |
---|---|
|
|
Rect2¶
下列欄位被轉換成了名稱 稍微 不同的屬性:
GDScript |
C# |
---|---|
|
|
下列方法轉換成了名稱不同的屬性:
GDScript |
C# |
---|---|
|
|
Quat¶
在 C# 中,結構為無參數的建置函式。因此,new Quat()
會初始化所有原始成員並設為預設值。請使用 Quat.Identity
來達到與 GDScript 或 C++ 中 Quat()
同等的效果。
下列方法被換成了不同名稱的屬性:
GDScript |
C# |
---|---|
|
|
|
|
陣列¶
本表為暫定。各個 PoolArray 需要定義各自的型別才能以其原定的方式使用。
GDScript |
C# |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Godot.Collections.Array<T>
為類別安全版的 Godot.Collections.Array
封裝。可使用 Godot.Collections.Array<T>(Godot.Collections.Array)
建置函式來建立。
字典¶
使用 Godot.Collections.Dictionary
。
Godot.Collections.Dictionary<T>
是型別安全版的 Godot.Collections.Dictionary
封裝。使用 Godot.Collections.Dictionary<T>(Godot.Collections.Dictionary)
建置函式來建立。
變體¶
使用 System.Object
(object
) 來代替``Variant``.
與其他腳本語言溝通¶
本主題於 跨語言腳本撰寫 中詳細說明。
產生¶
可以使用 C# 的 yield 關鍵字 來達到與在 GDScript 使用有單一參數的 yield
相同的功能。
對訊號的 yield 可以使用 async/await 與 Godot.Object.ToSignal
來達到同等效果。
範例:
await ToSignal(timer, "timeout");
GD.Print("After timeout");
其他差異¶
在 GDScript 中可用的 preload
無法於 C# 中使用。請使用 GD.Load
或 ResourceLoader.Load
代替。
其他差異:
GDScript |
C# |
---|---|
|
|
|
|
|
|
|
TODO 待補 |
|
TODO 待補 |