C# API 與 GDScript 的不同¶

本頁列出了 (不完整的) C# 與 GDScript 間的 API 差異。

一般差異¶

如同在 C# 基礎中解釋的一樣，C# 一般會使用 PascalCase 而不是 GDScript 與 C++ 所使用的 snake_case 。

全域作用域¶

全域函式與一些常數被移到類別裡了，因為 C# 不允許在命名空間中定義這些函式與常數。大部分全域常數都被移到各自的列舉類型中了。

常數¶

全域常數移至其各自的列舉類型。例如， ERR_* 常數移動到了 Error 列舉類型中。

特例：

GDScript	C#
`SPKEY`	`GD.SpKey`
`TYPE_*`	`Variant.Type` 列舉類型
`OP_*`	`Variant.Operator` 列舉類型

數學函式¶

數學全域函式，如 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#
`weakref(obj)`	`Object.WeakRef(obj)`
`is_instance_valid(obj)`	`Object.IsInstanceValid(obj)`

提示¶

有時候，使用 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#
`get_scale()`	`Scale`

Transform2D¶

在 C# 中，結構為無參數的建置函式。因此，new Transform2D() 會初始化所有原始成員並設為預設值。請使用 Transform2D.Identity 來達成與 GDScript 或 C++ 中 Transform2D() 同等的效果。

下列各個方法皆轉換為屬性並更改其名稱：

GDScript	C#
`get_rotation()`	`Rotation`
`get_scale()`	`Scale`

平面¶

下列方法被轉換成了名稱稍微不同的屬性：

GDScript	C#
`center()`	`Center`

Rect2¶

下列欄位被轉換成了名稱稍微不同的屬性：

GDScript	C#
`end`	`End`

下列方法轉換成了名稱不同的屬性：

GDScript	C#
`get_area()`	`Area`

Quat¶

在 C# 中，結構為無參數的建置函式。因此，new Quat() 會初始化所有原始成員並設為預設值。請使用 Quat.Identity 來達到與 GDScript 或 C++ 中 Quat() 同等的效果。

下列方法被換成了不同名稱的屬性：

GDScript	C#
`length()`	`Length`
`length_squared()`	`LengthSquared`

陣列¶

本表為暫定。各個 PoolArray 需要定義各自的型別才能以其原定的方式使用。

GDScript	C#
`Array`	`Godot.Collections.Array`
`PoolIntArray`	`int[]`
`PoolByteArray`	`byte[]`
`PoolFloatArray`	`float[]`
`PoolStringArray`	`String[]`
`PoolColorArray`	`Color[]`
`PoolVector2Array`	`Vector2[]`
`PoolVector3Array`	`Vector3[]`

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#
`Color8`	`Color.Color8`
`is_inf`	`float.IsInfinity`
`is_nan`	`float.IsNaN`
`dict2inst`	TODO 待補
`inst2dict`	TODO 待補