godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2025-12-31 17:49:03 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
0fe7ff833ea338721f325d1af239153b96f6a8df
godot-docs/tutorials/scripting/c_sharp/c_sharp_differences.rst
Luna 0fe7ff833e Fixed typos in several doc files (#8002) 
* Fixed typos in
- c_sharp_differences.rst
- debugger_panel.rst
- gdextension_cpp_example.rst
- gui_using_fonts.rst
- openxr_hand_tracking.rst
- overview_of_debugging_tools.rst
- setting_up_xr.rst
- shading_language.rst
- the_profiler.rst
- your_second_3d_shader.rst

* Update tutorials/shaders/shader_reference/shading_language.rst

Co-authored-by: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com>

* PR Feedback

---------

Co-authored-by: Luna <2650849-Lunalicious@users.noreply.gitlab.com>
Co-authored-by: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com>
2023-09-25 00:41:33 +02:00

854 lines
41 KiB
ReStructuredText
Raw Blame History

.. _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
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
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
=============================== ==============================================================
.. _$ 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`_)
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`_)
========================= ==============================================================
* .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://``)
.. _$ 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 Variant-compatible type 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
await ToSignal(timer, "timeout");
GD.Print("After timeout");
Reference in New Issue View Git Blame Copy Permalink