Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

C# API 与 GDScript 的差异

这是C#和GDScript之间API差异的(不完整)列表.

一般差异

如 C# 基础 中所述,C#通常使用 PascalCase 而不是GDScript和C++中使用的 snake_case.

全局作用域

全局函数和某些常量必须移动到类中, 因为C#不允许在命名空间中声明它们. 大多数全局常量都被移动到它们自己的枚举中.

常量

In C#, only primitive types can be constant. For example, the TAU constant is replaced by the Mathf.Tau constant, but the Vector2.RIGHT constant is replaced by the Vector2.Right read-only property. This behaves similarly to a constant, but can't be used in some contexts like switch statements.

Global enum constants were moved to their own enums. For example, ERR_* constants were moved to the Error enum.

特殊情况:

GDScript	C#
TYPE_*	Variant.Type 枚举
OP_*	Variant.Operator 枚举

数学函数

如 abs, acos , asin , atan 和 atan2 这样的全局数学函数位于 Mathf 下, 名为 Abs , Acos, Asin , Atan 和 Atan2. 常数 PI 可以通过 Mathf.Pi 获得.

C# also provides static System.Math and System.MathF classes that may contain other useful mathematical operations.

随机函数

如 rand_range 和 rand_seed 等全局随机函数位于 GD 下. 例如 GD.RandRange 以及 GD.RandSeed.

Consider using System.Random or, if you need cryptographically strong randomness, System.Security.Cryptography.RandomNumberGenerator.

其他函数

Many other global functions like print and var_to_str are located under GD. Example: GD.Print and GD.VarToStr.

例外情况:

GDScript	C#
weakref(obj)	GodotObject.WeakRef(obj)
instance_from_id(id)	GodotObject.InstanceFromId(id)
is_instance_id_valid(id)	GodotObject.IsInstanceIdValid(id)
is_instance_valid(obj)	GodotObject.IsInstanceValid(obj)

提示

有时候, 使用 using static 指令是很有用的. 该指令允许在不指定类名的情况下, 访问类的成员和嵌套类型.

示例：

using static Godot.GD;

public class Test
{
    static Test()
    {
        Print("Hello"); // Instead of GD.Print("Hello");
    }
}

Full list of equivalences

List of Godot's global scope functions and their equivalent in C#:

GDScript	C#
abs	Mathf.Abs
absf	Mathf.Abs
absi	Mathf.Abs
acos	Mathf.Acos
asin	Mathf.Asin
atan	Mathf.Atan
atan2	Mathf.Atan2
bezier_derivative	Mathf.BezierDerivative
bezier_interpolate	Mathf.BezierInterpolate
bytes_to_var	GD.BytesToVar
bytes_to_var_with_objects	GD.BytesToVarWithObjects
ceil	Mathf.Ceil
ceilf	Mathf.Ceil
ceili	Mathf.CeilToInt
clamp	Mathf.Clamp
clampf	Mathf.Clamp
clampi	Mathf.Clamp
cos	Mathf.Cos
cosh	Mathf.Cosh
cubic_interpolate	Mathf.CubicInterpolate
cubic_interpoalte_angle	Mathf.CubicInterpolateAngle
cubic_interpolate_angle_in_time	Mathf.CubicInterpolateInTime
cubic_interpolate_in_time	Mathf.CubicInterpolateAngleInTime
db_to_linear	Mathf.DbToLinear
deg_to_rad	Mathf.DegToRad
ease	Mathf.Ease
error_string	Error.ToString
exp	Mathf.Exp
floor	Mathf.Floor
floorf	Mathf.Floor
floori	Mathf.FloorToInt
fmod	operator %
fposmod	Mathf.PosMod
hash	GD.Hash
instance_from_id	GodotObject.InstanceFromId
inverse_lerp	Mathf.InverseLerp
is_equal_approx	Mathf.IsEqualApprox
is_finite	Mathf.IsFinite or float.IsFinite or double.IsFinite
is_inf	Mathf.IsInf or float.IsInfinity or double.IsInfinity
is_instance_id_valid	GodotObject.IsInstanceIdValid
is_instance_valid	GodotObject.IsInstanceValid
is_nan	Mathf.IsNaN or float.IsNaN or double.IsNaN
is_same	operator == or object.ReferenceEquals
is_zero_approx	Mathf.IsZeroApprox
lerp	Mathf.Lerp
lerp_angle	Mathf.LerpAngle
lerpf	Mathf.Lerp
linear_to_db	Mathf.LinearToDb
log	Mathf.Log
最大值	Mathf.Max
maxf	Mathf.Max
maxi	Mathf.Max
min	Mathf.Min
minf	Mathf.Min
mini	Mathf.Min
move_toward	Mathf.MoveToward
nearest_po2	Mathf.NearestPo2
pingpong	Mathf.PingPong
posmod	Mathf.PosMod
pow	Mathf.Pow
print	GD.Print
print_rich	GD.PrintRich
print_verbose	Use OS.IsStdoutVerbose and GD.Print
printerr	GD.PrintErr
printraw	GD.PrintRaw
prints	GD.PrintS
printt	GD.PrintT
push_error	GD.PushError
push_warning	GD.PushWarning
rad_to_deg	Mathf.RadToDeg
rand_from_seed	GD.RandFromSeed
randf	GD.Randf
randf_range	GD.RandRange
randfn	GD.Randfn
randi	GD.Randi
randi_range	GD.RandRange
randomize	GD.Randomize
remap	Mathf.Remap
rid_allocate_id	N/A
rid_from_int64	N/A
round	Mathf.Round
roundf	Mathf.Round
roundi	Mathf.RoundToInt
seed	GD.Seed
sign	Mathf.Sign
signf	Mathf.Sign
signi	Mathf.Sign
sin	Mathf.Sin
sinh	Mathf.Sinh
smoothstep	Mathf.SmoothStep
snapped	Mathf.Snapped
snappedf	Mathf.Snapped
snappedi	Mathf.Snapped
sqrt	Mathf.Sqrt
step_decimals	Mathf.StepDecimals
str	Use $ string interpolation
str_to_var	GD.StrToVar
tan	Mathf.Tan
tanh	Mathf.Tanh
typeof	Variant.VariantType
var_to_bytes	GD.VarToBytes
var_to_bytes_with_objects	GD.VarToBytesWithObjects
var_to_str	GD.VarToStr
weakref	GodotObject.WeakRef
wrap	Mathf.Wrap
wrapf	Mathf.Wrap
wrapi	Mathf.Wrap

List of GDScript utility functions and their equivalent in C#:

GDScript	C#
assert	System.Diagnostics.Debug.Assert
char	Use explicit conversion: (char)65
convert	GD.Convert
dict_to_inst	N/A
get_stack	System.Environment.StackTrace
inst_to_dict	N/A
len	N/A
load	GD.Load
preload	N/A
print_debug	N/A
print_stack	GD.Print(System.Environment.StackTrace)
range	GD.Range or System.Linq.Enumerable.Range
type_exists	ClassDB.ClassExists(type)

preload 在 GDScript 中可用，在 C# 中不可用。请使用 GD.Load 或 ResourceLoader.Load 替代。

@export annotation

Use the [Export] attribute instead of the GDScript @export annotation. This attribute can also be provided with optional PropertyHint and hintString parameters. Default values can be set by assigning a value.

示例：

using Godot;

public partial 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;
}

See also: C# exports.

signal keyword

Use the [Signal] attribute to declare a signal instead of the GDScript signal keyword. This attribute should be used on a delegate, whose name signature will be used to define the signal. The delegate must have the EventHandler suffix, an event will be generated in the class with the same name but without the suffix, use that event's name with EmitSignal.

[Signal]
delegate void MySignalEventHandler(string willSendAString);

另见: C# 信号 .

@onready annotation

GDScript has the ability to defer the initialization of a member variable until the ready function is called with @onready (cf. @onready annotation). For example:

@onready var my_label = get_node("MyLabel")

然而C#没有这个能力. 为了达到同样的效果, 你需要这样做.

private Label _myLabel;

public override void _Ready()
{
    _myLabel = GetNode<Label>("MyLabel");
}

单例

单例可以作为静态类使用, 而不是使用单例模式. 这是为了使代码不像使用 Instance 属性那样冗长.

示例：

Input.IsActionPressed("ui_down")

However, in some very rare cases this is not enough. For example, you may want to access a member from the base class GodotObject, like Connect. For such use cases we provide a static property named Singleton that returns the singleton instance. The type of this instance is GodotObject.

示例：

Input.Singleton.JoyConnectionChanged += Input_JoyConnectionChanged;

字符串

Use System.String (string). Most of Godot's String methods have an equivalent in System.String or are provided by the StringExtensions class as extension methods.

示例：

string text = "Get up!";
string[] bigrams = text.Bigrams(); // ["Ge", "et", "t ", " u", "up", "p!"]

Strings are immutable in .NET, so all methods that manipulate a string don't modify the original string and return a newly created string with the modifications applied. To avoid creating multiple string allocations consider using a StringBuilder.

List of Godot's String methods and their equivalent in C#:

GDScript	C#
begins_with	string.StartsWith
bigrams	StringExtensions.Bigrams
bin_to_int	StringExtensions.BinToInt
c_escape	StringExtensions.CEscape
c_unescape	StringExtensions.CUnescape
capitalize	StringExtensions.Capitalize
casecmp_to	StringExtensions.CasecmpTo or StringExtensions.CompareTo (Consider using string.Equals or string.Compare)
chr	N/A
contains	string.Contains
count	StringExtensions.Count (Consider using RegEx)
countn	StringExtensions.CountN (Consider using RegEx)
dedent	StringExtensions.Dedent
ends_with	string.EndsWith
erase	string.Remove (Consider using StringBuilder to manipulate strings)
find	StringExtensions.Find (Consider using string.IndexOf or string.IndexOfAny)
findn	StringExtensions.FindN (Consider using string.IndexOf or string.IndexOfAny)
format	Use $ string interpolation
get_base_dir	StringExtensions.GetBaseDir
get_basename	StringExtensions.GetBaseName
get_extension	StringExtensions.GetExtension
get_file	StringExtensions.GetFile
get_slice	N/A
get_slice_count	N/A
get_slicec	N/A
hash	StringExtensions.Hash (Consider using object.GetHashCode unless you need to guarantee the same behavior as in GDScript)
hex_decode	StringExtensions.HexDecode (Consider using System.Convert.FromHexString)
hex_to_int	StringExtensions.HexToInt (Consider using int.Parse or long.Parse with System.Globalization.NumberStyles.HexNumber)
humanize_size	N/A
indent	StringExtensions.Indent
insert	string.Insert (Consider using StringBuilder to manipulate strings)
is_absolute_path	StringExtensions.IsAbsolutePath
is_empty	string.IsNullOrEmpty or string.IsNullOrWhiteSpace
is_relative_path	StringExtensions.IsRelativePath
is_subsequence_of	StringExtensions.IsSubsequenceOf
is_subsequence_ofn	StringExtensions.IsSubsequenceOfN
is_valid_filename	StringExtensions.IsValidFileName
is_valid_float	StringExtensions.IsValidFloat (Consider using float.TryParse or double.TryParse)
is_valid_hex_number	StringExtensions.IsValidHexNumber
is_valid_html_color	StringExtensions.IsValidHtmlColor
is_valid_identifier	StringExtensions.IsValidIdentifier
is_valid_int	StringExtensions.IsValidInt (Consider using int.TryParse or long.TryParse)
is_valid_ip_address	StringExtensions.IsValidIPAddress
join	string.Join
json_escape	StringExtensions.JSONEscape
left	StringExtensions.Left (Consider using string.Substring or string.AsSpan)
length	string.Length
lpad	string.PadLeft
lstrip	string.TrimStart
match	StringExtensions.Match (Consider using RegEx)
matchn	StringExtensions.MatchN (Consider using RegEx)
md5_buffer	StringExtensions.Md5Buffer (Consider using System.Security.Cryptography.MD5.HashData)
md5_text	StringExtensions.Md5Text (Consider using System.Security.Cryptography.MD5.HashData with StringExtensions.HexEncode)
naturalnocasecmp_to	N/A (Consider using string.Equals or string.Compare)
nocasecmp_to	StringExtensions.NocasecmpTo or StringExtensions.CompareTo (Consider using string.Equals or string.Compare)
num	float.ToString or double.ToString
num_int64	int.ToString or long.ToString
num_scientific	float.ToString or double.ToString
num_uint64	uint.ToString or ulong.ToString
pad_decimals	StringExtensions.PadDecimals
pad_zeros	StringExtensions.PadZeros
path_join	StringExtensions.PathJoin
repeat	Use string constructor or a StringBuilder
replace	string.Replace or RegEx
replacen	StringExtensions.ReplaceN (Consider using string.Replace or RegEx)
rfind	StringExtensions.RFind (Consider using string.LastIndexOf or string.LastIndexOfAny)
rfindn	StringExtensions.RFindN (Consider using string.LastIndexOf or string.LastIndexOfAny)
right	StringExtensions.Right (Consider using string.Substring or string.AsSpan)
rpad	string.PadRight
rsplit	N/A
rstrip	string.TrimEnd
sha1_buffer	StringExtensions.Sha1Buffer (Consider using System.Security.Cryptography.SHA1.HashData)
sha1_text	StringExtensions.Sha1Text (Consider using System.Security.Cryptography.SHA1.HashData with StringExtensions.HexEncode)
sha256_buffer	StringExtensions.Sha256Buffer (Consider using System.Security.Cryptography.SHA256.HashData)
sha256_text	StringExtensions.Sha256Text (Consider using System.Security.Cryptography.SHA256.HashData with StringExtensions.HexEncode)
similarity	StringExtensions.Similarity
simplify_path	StringExtensions.SimplifyPath
split	StringExtensions.Split (Consider using string.Split)
split_floats	StringExtensions.SplitFloat
strip_edges	StringExtensions.StripEdges (Consider using string.Trim, string.TrimStart or string.TrimEnd)
strip_escapes	StringExtensions.StripEscapes
substr	StringExtensions.Substr (Consider using string.Substring or string.AsSpan)
to_ascii_buffer	StringExtensions.ToAsciiBuffer (Consider using System.Text.Encoding.ASCII.GetBytes)
to_camel_case	StringExtensions.ToCamelCase
to_float	StringExtensions.ToFloat (Consider using float.TryParse or double.TryParse)
to_int	StringExtensions.ToInt (Consider using int.TryParse or long.TryParse)
to_lower	string.ToLower
to_pascal_case	StringExtensions.ToPascalCase
to_snake_case	StringExtensions.ToSnakeCase
to_upper	string.ToUpper
to_utf16_buffer	StringExtensions.ToUtf16Buffer (Consider using System.Text.Encoding.UTF16.GetBytes)
to_utf32_buffer	StringExtensions.ToUtf32Buffer (Consider using System.Text.Encoding.UTF32.GetBytes)
to_utf8_buffer	StringExtensions.ToUtf8Buffer (Consider using System.Text.Encoding.UTF8.GetBytes)
to_wchar_buffer	StringExtensions.ToUtf16Buffer in Windows and StringExtensiont.ToUtf32Buffer in other platforms
trim_prefix	StringExtensions.TrimPrefix
trim_suffix	StringExtensions.TrimSuffix
unicode_at	string[int] indexer
uri_decode	StringExtensions.URIDecode (Consider using System.Uri.UnescapeDataString)
uri_encode	StringExtensions.URIEncode (Consider using System.Uri.EscapeDataString)
validate_node_name	StringExtensions.ValidateNodeName
xml_escape	StringExtensions.XMLEscape
xml_unescape	StringExtensions.XMLUnescape

List of Godot's PackedByteArray methods that create a String and their C# equivalent:

GDScript	C#
get_string_from_ascii	StringExtensions.GetStringFromAscii (Consider using System.Text.Encoding.ASCII.GetString)
get_string_from_utf16	StringExtensions.GetStringFromUtf16 (Consider using System.Text.Encoding.UTF16.GetString)
get_string_from_utf32	StringExtensions.GetStringFromUtf32 (Consider using System.Text.Encoding.UTF32.GetString)
get_string_from_utf8	StringExtensions.GetStringFromUtf8 (Consider using System.Text.Encoding.UTF8.GetString)
hex_encode	StringExtensions.HexEncode (Consider using System.Convert.ToHexString)

• .NET contains many path utility methods available under the System.IO.Path class that can be used when not dealing with Godot paths (paths that start with res:// or user://)

节点路径

以下方法已转换为具有不同名称的属性：

GDScript	C#
is_empty()	IsEmpty

信号

下列方法已转换为属性, 其各自名称已被更改:

GDScript	C#
get_name()	Name
get_object()	Owner

The Signal type implements the awaitable pattern which means it can be used with the await keyword. See await keyword.

Instead of using the Signal type, the recommended way to use Godot signals in C# is to use the generated C# events. See C# 信号.

Callable

下列方法已转换为属性, 其各自名称已被更改:

GDScript	C#
get_object()	Target
get_method()	Method

Currently C# supports Callable if one of the following holds:

• Callable was created using the C# Callable type.

• Callable is a basic version of the engine's Callable. Custom Callables are unsupported. A Callable is custom when any of the following holds:

  • Callable has bound information (Callables created with bind/unbind are unsupported).

  • Callable was created from other languages through the GDExtension API.

Some methods such as bind and unbind are not implemented, use lambdas instead:

string name = "John Doe";
Callable callable = Callable.From(() => SayHello(name));

void SayHello(string name)
{
    GD.Print($"Hello {name}");
}

The lambda captures the name variable so it can be bound to the SayHello method.

RID

This type is named Rid in C# to follow the .NET naming convention.

下列方法已转换为属性, 其各自名称已被更改:

GDScript	C#
get_id()	Id
is_valid()	IsValid

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
get_skew()	Skew

Transform3D

Structs cannot have parameterless constructors in C#. Therefore, new Transform3D() initializes all primitive members to their default value. Please use Transform3D.Identity for the equivalent of Transform3D() in GDScript and C++.

下列方法已转换为属性, 其各自名称已被更改:

GDScript	C#
get_rotation()	Rotation
get_scale()	Scale

Rect2

以下字段已转换为名称 稍有 不同的属性:

GDScript	C#
end	End

以下方法已转换为具有不同名称的属性：

GDScript	C#
get_area()	Area

Rect2i

This type is named Rect2I in C# to follow the .NET naming convention.

以下字段已转换为名称 稍有 不同的属性:

GDScript	C#
end	End

以下方法已转换为具有不同名称的属性：

GDScript	C#
get_area()	Area

AABB

This type is named Aabb in C# to follow the .NET naming convention.

以下方法已转换为具有不同名称的属性：

GDScript	C#
get_volume()	Volume

Quaternion

Structs cannot have parameterless constructors in C#. Therefore, new Quaternion() initializes all primitive members to their default value. Please use Quaternion.Identity for the equivalent of Quaternion() in GDScript and C++.

Projection

Structs cannot have parameterless constructors in C#. Therefore, new Projection() initializes all primitive members to their default value. Please use Projection.Identity for the equivalent of Projection() in GDScript and C++.

颜色

Structs cannot have parameterless constructors in C#. Therefore, new Color() initializes all primitive members to their default value (which represents the transparent black color). Please use Colors.Black for the equivalent of Color() in GDScript and C++.

The global Color8 method to construct a Color from bytes is available as a static method in the Color type.

The Color constants are available in the Colors static class as readonly properties.

以下方法已转换为具有不同名称的属性：

GDScript	C#
get_luminance()	Luminance

The following method was converted to a method with a different name:

GDScript	C#
html(String)	FromHtml(ReadOnlySpan<char>)

The following methods are available as constructors:

GDScript	C#
hex(int)	Color(uint)
hex64(int)	Color(ulong)

数组

The equivalent of packed arrays are System.Array.

See also PackedArray in C#.

Use Godot.Collections.Array for an untyped Variant array. Godot.Collections.Array<T> is a type-safe wrapper around Godot.Collections.Array.

See also Array in C#.

字典

Use Godot.Collections.Dictionary for an untyped Variant dictionary. Godot.Colelctions.Dictionary<TKey, TValue> is a type-safe wrapper around Godot.Collections.Dictionary.

See also Dictionary in C#.

Variant

Godot.Variant is used to represent Godot's native Variant type. Any Variant-compatible type can be converted from/to it.

See also: C# Variant.

与其他脚本语言通信

在 跨语言脚本 中有详细解释。

await keyword

Something similar to GDScript's await keyword can be achieved with C#'s await keyword.

The await keyword in C# can be used with any awaitable expression. It's commonly used with operands of the types Task, Task<TResult>, ValueTask, or ValueTask<TResult>.

An expression t is awaitable if one of the following holds:

• t is of compile-time type dynamic.

• t has an accessible instance or extension method called GetAwaiter with no parameters and no type parameters, and a return type A for which all of the following hold:

  • A implements the interface System.Runtime.CompilerServices.INotifyCompletion.

  • A has an accessible, readable instance property IsCompleted of type bool.

  • A has an accessible instance method GetResult with no parameters and no type parameters.

An equivalent of awaiting a signal in GDScript can be achieved with the await keyword and GodotObject.ToSignal.

示例：

await ToSignal(timer, "timeout");
GD.Print("After timeout");