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.

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 , atanatan2 这样的全局数学函数位于 Mathf 下, 名为 Abs , Acos, Asin , AtanAtan2. 常数 PI 可以通过 Mathf.Pi 获得.

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

随机函数

rand_rangerand_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.LoadResourceLoader.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");