mirror of
https://github.com/godotengine/godot-docs.git
synced 2026-01-01 21:48:57 +03:00
865 lines
41 KiB
ReStructuredText
865 lines
41 KiB
ReStructuredText
.. _doc_c_sharp_differences:
|
|
|
|
C# API differences to GDScript
|
|
==============================
|
|
|
|
This is a (incomplete) list of API differences between C# and GDScript.
|
|
|
|
General differences
|
|
-------------------
|
|
|
|
As explained in the :ref:`doc_c_sharp`, C# generally uses ``PascalCase`` instead
|
|
of the ``snake_case`` used in GDScript and C++.
|
|
|
|
Global scope
|
|
------------
|
|
|
|
Global functions and some constants had to be moved to classes, since C#
|
|
does not allow declaring them in namespaces.
|
|
Most global constants were moved to their own enums.
|
|
|
|
Constants
|
|
^^^^^^^^^
|
|
|
|
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.
|
|
|
|
Special cases:
|
|
|
|
======================= ===========================================================
|
|
GDScript C#
|
|
======================= ===========================================================
|
|
``TYPE_*`` ``Variant.Type`` enum
|
|
``OP_*`` ``Variant.Operator`` enum
|
|
======================= ===========================================================
|
|
|
|
Math functions
|
|
^^^^^^^^^^^^^^
|
|
|
|
Math global functions, like ``abs``, ``acos``, ``asin``, ``atan`` and ``atan2``, are
|
|
located under ``Mathf`` as ``Abs``, ``Acos``, ``Asin``, ``Atan`` and ``Atan2``.
|
|
The ``PI`` constant can be found as ``Mathf.Pi``.
|
|
|
|
C# also provides static `System.Math`_ and `System.MathF`_ classes that may
|
|
contain other useful mathematical operations.
|
|
|
|
.. _System.Math: https://learn.microsoft.com/en-us/dotnet/api/system.math
|
|
.. _System.MathF: https://learn.microsoft.com/en-us/dotnet/api/system.mathf
|
|
|
|
Random functions
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
Random global functions, like ``rand_range`` and ``rand_seed``, are located under ``GD``.
|
|
Example: ``GD.RandRange`` and ``GD.RandSeed``.
|
|
|
|
Consider using `System.Random`_ or, if you need cryptographically strong randomness,
|
|
`System.Security.Cryptography.RandomNumberGenerator`_.
|
|
|
|
.. _System.Random: https://learn.microsoft.com/en-us/dotnet/api/system.random
|
|
.. _System.Security.Cryptography.RandomNumberGenerator: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.randomnumbergenerator
|
|
|
|
Other functions
|
|
^^^^^^^^^^^^^^^
|
|
|
|
Many other global functions like ``print`` and ``var_to_str`` are located under ``GD``.
|
|
Example: ``GD.Print`` and ``GD.VarToStr``.
|
|
|
|
Exceptions:
|
|
|
|
============================ =======================================================
|
|
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)``
|
|
============================ =======================================================
|
|
|
|
Tips
|
|
^^^^
|
|
|
|
Sometimes it can be useful to use the ``using static`` directive. This directive allows
|
|
to access the members and nested types of a class without specifying the class name.
|
|
|
|
Example:
|
|
|
|
.. code-block:: csharp
|
|
|
|
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
|
|
acosh Mathf.Acosh
|
|
angle_difference Mathf.AngleDifference
|
|
asin Mathf.Asin
|
|
asinh Mathf.Asinh
|
|
atan Mathf.Atan
|
|
atan2 Mathf.Atan2
|
|
atanh Mathf.Atanh
|
|
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_interpolate_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
|
|
max 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
|
|
rotate_toward Mathf.RotateToward
|
|
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
|
|
type_convert Variant.As<T> or GD.Convert
|
|
type_string Variant.Type.ToString
|
|
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
|
|
=============================== ==============================================================
|
|
|
|
.. _$ string interpolation: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/tokens/interpolated
|
|
.. _double.IsFinite: https://learn.microsoft.com/en-us/dotnet/api/system.double.isfinite
|
|
.. _double.IsInfinity: https://learn.microsoft.com/en-us/dotnet/api/system.double.isinfinity
|
|
.. _double.IsNaN: https://learn.microsoft.com/en-us/dotnet/api/system.double.isnan
|
|
.. _float.IsFinite: https://learn.microsoft.com/en-us/dotnet/api/system.single.isfinite
|
|
.. _float.IsInfinity: https://learn.microsoft.com/en-us/dotnet/api/system.single.isinfinity
|
|
.. _float.IsNaN: https://learn.microsoft.com/en-us/dotnet/api/system.single.isnan
|
|
.. _object.ReferenceEquals: https://learn.microsoft.com/en-us/dotnet/api/system.object.referenceequals
|
|
|
|
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)
|
|
======================= ==============================================================
|
|
|
|
.. _System.Diagnostics.Debug.Assert: https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.debug.assert
|
|
.. _System.Environment.StackTrace: https://learn.microsoft.com/en-us/dotnet/api/system.environment.stacktrace
|
|
.. _System.Linq.Enumerable.Range: https://learn.microsoft.com/en-us/dotnet/api/system.linq.enumerable.range
|
|
|
|
``preload``, as it works in GDScript, is not available in C#.
|
|
Use ``GD.Load`` or ``ResourceLoader.Load`` instead.
|
|
|
|
``@export`` annotation
|
|
----------------------
|
|
|
|
Use the ``[Export]`` attribute instead of the GDScript ``@export`` annotation.
|
|
This attribute can also be provided with optional :ref:`PropertyHint<enum_@GlobalScope_PropertyHint>` and ``hintString`` parameters.
|
|
Default values can be set by assigning a value.
|
|
|
|
Example:
|
|
|
|
.. code-block:: csharp
|
|
|
|
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: :ref:`doc_c_sharp_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``.
|
|
|
|
.. code-block:: csharp
|
|
|
|
[Signal]
|
|
delegate void MySignalEventHandler(string willSendAString);
|
|
|
|
See also: :ref:`doc_c_sharp_signals`.
|
|
|
|
`@onready` annotation
|
|
---------------------
|
|
|
|
GDScript has the ability to defer the initialization of a member variable until the ready function
|
|
is called with `@onready` (cf. :ref:`doc_gdscript_onready_annotation`).
|
|
For example:
|
|
|
|
.. code-block:: gdscript
|
|
|
|
@onready var my_label = get_node("MyLabel")
|
|
|
|
However C# does not have this ability. To achieve the same effect you need to do this.
|
|
|
|
.. code-block:: csharp
|
|
|
|
private Label _myLabel;
|
|
|
|
public override void _Ready()
|
|
{
|
|
_myLabel = GetNode<Label>("MyLabel");
|
|
}
|
|
|
|
Singletons
|
|
----------
|
|
|
|
Singletons are available as static classes rather than using the singleton pattern.
|
|
This is to make code less verbose than it would be with an ``Instance`` property.
|
|
|
|
Example:
|
|
|
|
.. code-block:: csharp
|
|
|
|
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``.
|
|
|
|
Example:
|
|
|
|
.. code-block:: csharp
|
|
|
|
Input.Singleton.JoyConnectionChanged += Input_JoyConnectionChanged;
|
|
|
|
String
|
|
------
|
|
|
|
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.
|
|
|
|
Example:
|
|
|
|
.. code-block:: csharp
|
|
|
|
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`_)
|
|
reverse N/A
|
|
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 StringExtensions.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`_)
|
|
========================= ==============================================================
|
|
|
|
.. note::
|
|
|
|
.NET provides path utility methods under the
|
|
`System.IO.Path`_
|
|
class. They can only be used with native OS paths, not Godot paths
|
|
(paths that start with ``res://`` or ``user://``).
|
|
See :ref:`doc_data_paths`.
|
|
|
|
.. _$ string interpolation: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/tokens/interpolated
|
|
.. _double.ToString: https://learn.microsoft.com/en-us/dotnet/api/system.double.tostring
|
|
.. _double.TryParse: https://learn.microsoft.com/en-us/dotnet/api/system.double.tryparse
|
|
.. _float.ToString: https://learn.microsoft.com/en-us/dotnet/api/system.single.tostring
|
|
.. _float.TryParse: https://learn.microsoft.com/en-us/dotnet/api/system.single.tryparse
|
|
.. _int.Parse: https://learn.microsoft.com/en-us/dotnet/api/system.int32.parse
|
|
.. _int.ToString: https://learn.microsoft.com/en-us/dotnet/api/system.int32.tostring
|
|
.. _int.TryParse: https://learn.microsoft.com/en-us/dotnet/api/system.int32.tryparse
|
|
.. _long.Parse: https://learn.microsoft.com/en-us/dotnet/api/system.int64.parse
|
|
.. _long.ToString: https://learn.microsoft.com/en-us/dotnet/api/system.int64.tostring
|
|
.. _long.TryParse: https://learn.microsoft.com/en-us/dotnet/api/system.int64.tryparse
|
|
.. _uint.ToString: https://learn.microsoft.com/en-us/dotnet/api/system.uint32.tostring
|
|
.. _ulong.ToString: https://learn.microsoft.com/en-us/dotnet/api/system.uint64.tostring
|
|
.. _object.GetHashCode: https://learn.microsoft.com/en-us/dotnet/api/system.object.gethashcode
|
|
.. _RegEx: https://learn.microsoft.com/en-us/dotnet/standard/base-types/regular-expressions
|
|
.. _string constructor: https://learn.microsoft.com/en-us/dotnet/api/system.string.-ctor
|
|
.. _string[int]: https://learn.microsoft.com/en-us/dotnet/api/system.string.chars
|
|
.. _string.AsSpan: https://learn.microsoft.com/en-us/dotnet/api/system.memoryextensions.asspan
|
|
.. _string.Compare: https://learn.microsoft.com/en-us/dotnet/api/system.string.compare
|
|
.. _string.Contains: https://learn.microsoft.com/en-us/dotnet/api/system.string.contains
|
|
.. _string.EndsWith: https://learn.microsoft.com/en-us/dotnet/api/system.string.endswith
|
|
.. _string.Equals: https://learn.microsoft.com/en-us/dotnet/api/system.string.equals
|
|
.. _string.IndexOf: https://learn.microsoft.com/en-us/dotnet/api/system.string.indexof
|
|
.. _string.IndexOfAny: https://learn.microsoft.com/en-us/dotnet/api/system.string.indexofany
|
|
.. _string.Insert: https://learn.microsoft.com/en-us/dotnet/api/system.string.insert
|
|
.. _string.IsNullOrEmpty: https://learn.microsoft.com/en-us/dotnet/api/system.string.isnullorempty
|
|
.. _string.IsNullOrWhiteSpace: https://learn.microsoft.com/en-us/dotnet/api/system.string.isnullorwhitespace
|
|
.. _string.Join: https://learn.microsoft.com/en-us/dotnet/api/system.string.join
|
|
.. _string.LastIndexOf: https://learn.microsoft.com/en-us/dotnet/api/system.string.lastindexof
|
|
.. _string.LastIndexOfAny: https://learn.microsoft.com/en-us/dotnet/api/system.string.lastindexofany
|
|
.. _string.Length: https://learn.microsoft.com/en-us/dotnet/api/system.string.length
|
|
.. _string.PadLeft: https://learn.microsoft.com/en-us/dotnet/api/system.string.padleft
|
|
.. _string.PadRight: https://learn.microsoft.com/en-us/dotnet/api/system.string.padright
|
|
.. _string.Remove: https://learn.microsoft.com/en-us/dotnet/api/system.string.remove
|
|
.. _string.Replace: https://learn.microsoft.com/en-us/dotnet/api/system.string.replace
|
|
.. _string.Split: https://learn.microsoft.com/en-us/dotnet/api/system.string.split
|
|
.. _string.StartsWith: https://learn.microsoft.com/en-us/dotnet/api/system.string.startswith
|
|
.. _string.Substring: https://learn.microsoft.com/en-us/dotnet/api/system.string.substring
|
|
.. _string.Trim: https://learn.microsoft.com/en-us/dotnet/api/system.string.trim
|
|
.. _string.TrimEnd: https://learn.microsoft.com/en-us/dotnet/api/system.string.trimend
|
|
.. _string.TrimStart: https://learn.microsoft.com/en-us/dotnet/api/system.string.trimstart
|
|
.. _string.ToLower: https://learn.microsoft.com/en-us/dotnet/api/system.string.tolower
|
|
.. _string.ToUpper: https://learn.microsoft.com/en-us/dotnet/api/system.string.toupper
|
|
.. _StringBuilder: https://learn.microsoft.com/en-us/dotnet/api/system.text.stringbuilder
|
|
.. _System.Convert.FromHexString: https://learn.microsoft.com/en-us/dotnet/api/system.convert.fromhexstring
|
|
.. _System.Convert.ToHexString: https://learn.microsoft.com/en-us/dotnet/api/system.convert.tohexstring
|
|
.. _System.Globalization.NumberStyles.HexNumber: https://learn.microsoft.com/en-us/dotnet/api/system.globalization.numberstyles#system-globalization-numberstyles-hexnumber
|
|
.. _System.IO.Path: https://learn.microsoft.com/en-us/dotnet/api/system.io.path
|
|
.. _System.Security.Cryptography.MD5.HashData: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.md5.hashdata
|
|
.. _System.Security.Cryptography.SHA1.HashData: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.sha1.hashdata
|
|
.. _System.Security.Cryptography.SHA256.HashData: https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.sha256.hashdata
|
|
.. _System.Text.Encoding.ASCII.GetBytes: https://learn.microsoft.com/en-us/dotnet/api/system.text.asciiencoding.getbytes
|
|
.. _System.Text.Encoding.ASCII.GetString: https://learn.microsoft.com/en-us/dotnet/api/system.text.asciiencoding.getstring
|
|
.. _System.Text.Encoding.UTF16.GetBytes: https://learn.microsoft.com/en-us/dotnet/api/system.text.unicodeencoding.getbytes
|
|
.. _System.Text.Encoding.UTF16.GetString: https://learn.microsoft.com/en-us/dotnet/api/system.text.unicodeencoding.getstring
|
|
.. _System.Text.Encoding.UTF32.GetBytes: https://learn.microsoft.com/en-us/dotnet/api/system.text.utf32encoding.getbytes
|
|
.. _System.Text.Encoding.UTF32.GetString: https://learn.microsoft.com/en-us/dotnet/api/system.text.utf32encoding.getstring
|
|
.. _System.Text.Encoding.UTF8.GetBytes: https://learn.microsoft.com/en-us/dotnet/api/system.text.utf8encoding.getbytes
|
|
.. _System.Text.Encoding.UTF8.GetString: https://learn.microsoft.com/en-us/dotnet/api/system.text.utf8encoding.getstring
|
|
.. _System.Uri.EscapeDataString: https://learn.microsoft.com/en-us/dotnet/api/system.uri.escapedatastring
|
|
.. _System.Uri.UnescapeDataString: https://learn.microsoft.com/en-us/dotnet/api/system.uri.unescapedatastring
|
|
|
|
NodePath
|
|
--------
|
|
|
|
The following method was converted to a property with a different name:
|
|
|
|
==================== ==============================================================
|
|
GDScript C#
|
|
==================== ==============================================================
|
|
``is_empty()`` ``IsEmpty``
|
|
==================== ==============================================================
|
|
|
|
Signal
|
|
------
|
|
|
|
The following methods were converted to properties with their respective names changed:
|
|
|
|
==================== ==============================================================
|
|
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 :ref:`doc_c_sharp_differences_await`.
|
|
|
|
Instead of using the ``Signal`` type, the recommended way to use Godot signals in C# is
|
|
to use the generated C# events. See :ref:`doc_c_sharp_signals`.
|
|
|
|
Callable
|
|
--------
|
|
|
|
The following methods were converted to properties with their respective names changed:
|
|
|
|
==================== ==============================================================
|
|
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 ``Callable``\ s
|
|
are unsupported. A ``Callable`` is custom when any of the following holds:
|
|
|
|
* ``Callable`` has bound information (``Callable``\ s 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:
|
|
|
|
.. code-block:: csharp
|
|
|
|
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.
|
|
|
|
The following methods were converted to properties with their respective names changed:
|
|
|
|
==================== ==============================================================
|
|
GDScript C#
|
|
==================== ==============================================================
|
|
``get_id()`` ``Id``
|
|
``is_valid()`` ``IsValid``
|
|
==================== ==============================================================
|
|
|
|
Basis
|
|
-----
|
|
|
|
Structs cannot have parameterless constructors in C#. Therefore, ``new Basis()``
|
|
initializes all primitive members to their default value. Use ``Basis.Identity``
|
|
for the equivalent of ``Basis()`` in GDScript and C++.
|
|
|
|
The following method was converted to a property with a different name:
|
|
|
|
==================== ==============================================================
|
|
GDScript C#
|
|
==================== ==============================================================
|
|
``get_scale()`` ``Scale``
|
|
==================== ==============================================================
|
|
|
|
Transform2D
|
|
-----------
|
|
|
|
Structs cannot have parameterless constructors in C#. Therefore, ``new Transform2D()``
|
|
initializes all primitive members to their default value.
|
|
Please use ``Transform2D.Identity`` for the equivalent of ``Transform2D()`` in GDScript and C++.
|
|
|
|
The following methods were converted to properties with their respective names changed:
|
|
|
|
==================== ==============================================================
|
|
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++.
|
|
|
|
The following methods were converted to properties with their respective names changed:
|
|
|
|
==================== ==============================================================
|
|
GDScript C#
|
|
==================== ==============================================================
|
|
``get_rotation()`` ``Rotation``
|
|
``get_scale()`` ``Scale``
|
|
==================== ==============================================================
|
|
|
|
Rect2
|
|
-----
|
|
|
|
The following field was converted to a property with a *slightly* different name:
|
|
|
|
================ ==================================================================
|
|
GDScript C#
|
|
================ ==================================================================
|
|
``end`` ``End``
|
|
================ ==================================================================
|
|
|
|
The following method was converted to a property with a different name:
|
|
|
|
================ ==================================================================
|
|
GDScript C#
|
|
================ ==================================================================
|
|
``get_area()`` ``Area``
|
|
================ ==================================================================
|
|
|
|
Rect2i
|
|
------
|
|
|
|
This type is named ``Rect2I`` in C# to follow the .NET naming convention.
|
|
|
|
The following field was converted to a property with a *slightly* different name:
|
|
|
|
================ ==================================================================
|
|
GDScript C#
|
|
================ ==================================================================
|
|
``end`` ``End``
|
|
================ ==================================================================
|
|
|
|
The following method was converted to a property with a different name:
|
|
|
|
================ ==================================================================
|
|
GDScript C#
|
|
================ ==================================================================
|
|
``get_area()`` ``Area``
|
|
================ ==================================================================
|
|
|
|
AABB
|
|
----
|
|
|
|
This type is named ``Aabb`` in C# to follow the .NET naming convention.
|
|
|
|
The following method was converted to a property with a different name:
|
|
|
|
================ ==================================================================
|
|
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++.
|
|
|
|
Color
|
|
-----
|
|
|
|
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.
|
|
|
|
The following method was converted to a property with a different name:
|
|
|
|
==================== ==============================================================
|
|
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)``
|
|
==================== ==============================================================
|
|
|
|
Array
|
|
-----
|
|
|
|
The equivalent of packed arrays are ``System.Array``.
|
|
|
|
See also :ref:`PackedArray in C# <doc_c_sharp_collections_packedarray>`.
|
|
|
|
Use ``Godot.Collections.Array`` for an untyped ``Variant`` array.
|
|
``Godot.Collections.Array<T>`` is a type-safe wrapper around ``Godot.Collections.Array``.
|
|
|
|
See also :ref:`Array in C# <doc_c_sharp_collections_array>`.
|
|
|
|
Dictionary
|
|
----------
|
|
|
|
Use ``Godot.Collections.Dictionary`` for an untyped ``Variant`` dictionary.
|
|
``Godot.Collections.Dictionary<TKey, TValue>`` is a type-safe wrapper around ``Godot.Collections.Dictionary``.
|
|
|
|
See also :ref:`Dictionary in C# <doc_c_sharp_collections_dictionary>`.
|
|
|
|
Variant
|
|
-------
|
|
|
|
``Godot.Variant`` is used to represent Godot's native :ref:`Variant <class_Variant>` type.
|
|
Any :ref:`Variant-compatible type <c_sharp_variant_compatible_types>` can be converted from/to it.
|
|
|
|
See also: :ref:`doc_c_sharp_variant`.
|
|
|
|
Communicating with other scripting languages
|
|
--------------------------------------------
|
|
|
|
This is explained extensively in :ref:`doc_cross_language_scripting`.
|
|
|
|
.. _doc_c_sharp_differences_await:
|
|
|
|
``await`` keyword
|
|
-----------------
|
|
|
|
Something similar to GDScript's ``await`` keyword can be achieved with C#'s
|
|
`await keyword <https://docs.microsoft.com/en-US/dotnet/csharp/language-reference/keywords/await>`_.
|
|
|
|
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.
|
|
|
|
.. _Task: https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.task
|
|
.. _Task<TResult>: https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.task-1
|
|
.. _ValueTask: https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.valuetask
|
|
.. _ValueTask<TResult>: https://learn.microsoft.com/en-us/dotnet/api/system.threading.tasks.valuetask-1
|
|
|
|
An equivalent of awaiting a signal in GDScript can be achieved with the ``await`` keyword and
|
|
``GodotObject.ToSignal``.
|
|
|
|
Example:
|
|
|
|
.. code-block:: csharp
|
|
|
|
public async Task SomeFunction()
|
|
{
|
|
await ToSignal(timer, Timer.SignalName.Timeout);
|
|
GD.Print("After timeout");
|
|
}
|