c_sharp_differences.rst 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343
  1. .. _doc_c_sharp_differences:
  2. C# API differences to GDScript
  3. ==============================
  4. This is a (incomplete) list of API differences between C# and GDScript.
  5. General differences
  6. -------------------
  7. As explained in the :ref:`doc_c_sharp`, C# generally uses ``PascalCase`` instead
  8. of the ``snake_case`` used in GDScript and C++.
  9. Global scope
  10. ------------
  11. Global functions and some constants had to be moved to classes, since C#
  12. does not allow declaring them in namespaces.
  13. Most global constants were moved to their own enums.
  14. Constants
  15. ^^^^^^^^^
  16. In C#, only primitive types can be constant. For example, the ``TAU`` constant
  17. is replaced by the ``Mathf.Tau`` constant, but the ``Vector2.RIGHT`` constant
  18. is replaced by the ``Vector2.Right`` read-only property. This behaves similarly
  19. to a constant, but can't be used in some contexts like ``switch`` statements.
  20. Global enum constants were moved to their own enums.
  21. For example, ``ERR_*`` constants were moved to the ``Error`` enum.
  22. Special cases:
  23. ======================= ===========================================================
  24. GDScript C#
  25. ======================= ===========================================================
  26. ``SPKEY`` ``GD.SpKey``
  27. ``TYPE_*`` ``Variant.Type`` enum
  28. ``OP_*`` ``Variant.Operator`` enum
  29. ======================= ===========================================================
  30. Math functions
  31. ^^^^^^^^^^^^^^
  32. Math global functions, like ``abs``, ``acos``, ``asin``, ``atan`` and ``atan2``, are
  33. located under ``Mathf`` as ``Abs``, ``Acos``, ``Asin``, ``Atan`` and ``Atan2``.
  34. The ``PI`` constant can be found as ``Mathf.Pi``.
  35. Random functions
  36. ^^^^^^^^^^^^^^^^
  37. Random global functions, like ``rand_range`` and ``rand_seed``, are located under ``GD``.
  38. Example: ``GD.RandRange`` and ``GD.RandSeed``.
  39. Other functions
  40. ^^^^^^^^^^^^^^^
  41. Many other global functions like ``print`` and ``var2str`` are located under ``GD``.
  42. Example: ``GD.Print`` and ``GD.Var2Str``.
  43. Exceptions:
  44. =========================== =======================================================
  45. GDScript C#
  46. =========================== =======================================================
  47. ``weakref(obj)`` ``Object.WeakRef(obj)``
  48. ``is_instance_valid(obj)`` ``Object.IsInstanceValid(obj)``
  49. =========================== =======================================================
  50. Tips
  51. ^^^^
  52. Sometimes it can be useful to use the ``using static`` directive. This directive allows
  53. to access the members and nested types of a class without specifying the class name.
  54. Example:
  55. .. code-block:: csharp
  56. using static Godot.GD;
  57. public class Test
  58. {
  59. static Test()
  60. {
  61. Print("Hello"); // Instead of GD.Print("Hello");
  62. }
  63. }
  64. Export keyword
  65. --------------
  66. Use the ``[Export]`` attribute instead of the GDScript ``export`` keyword.
  67. This attribute can also be provided with optional :ref:`PropertyHint<enum_@GlobalScope_PropertyHint>` and ``hintString`` parameters.
  68. Default values can be set by assigning a value.
  69. Example:
  70. .. code-block:: csharp
  71. using Godot;
  72. public class MyNode : Node
  73. {
  74. [Export]
  75. private NodePath _nodePath;
  76. [Export]
  77. private string _name = "default";
  78. [Export(PropertyHint.Range, "0,100000,1000,or_greater")]
  79. private int _income;
  80. [Export(PropertyHint.File, "*.png,*.jpg")]
  81. private string _icon;
  82. }
  83. Signal keyword
  84. --------------
  85. Use the ``[Signal]`` attribute to declare a signal instead of the GDScript ``signal`` keyword.
  86. This attribute should be used on a `delegate`, whose name signature will be used to define the signal.
  87. .. code-block:: csharp
  88. [Signal]
  89. delegate void MySignal(string willSendsAString);
  90. See also: :ref:`doc_c_sharp_signals`.
  91. Singletons
  92. ----------
  93. Singletons are available as static classes rather than using the singleton pattern.
  94. This is to make code less verbose than it would be with an ``Instance`` property.
  95. Example:
  96. .. code-block:: csharp
  97. Input.IsActionPressed("ui_down")
  98. However, in some very rare cases this is not enough. For example, you may want
  99. to access a member from the base class ``Godot.Object``, like ``Connect``.
  100. For such use cases we provide a static property named ``Singleton`` that returns
  101. the singleton instance. The type of this instance is ``Godot.Object``.
  102. Example:
  103. .. code-block:: csharp
  104. Input.Singleton.Connect("joy_connection_changed", this, nameof(Input_JoyConnectionChanged));
  105. String
  106. ------
  107. Use ``System.String`` (``string``). Most of Godot's String methods are
  108. provided by the ``StringExtensions`` class as extension methods.
  109. Example:
  110. .. code-block:: csharp
  111. string upper = "I LIKE SALAD FORKS";
  112. string lower = upper.ToLower();
  113. There are a few differences, though:
  114. * ``erase``: Strings are immutable in C#, so we cannot modify the string
  115. passed to the extension method. For this reason, ``Erase`` was added as an
  116. extension method of ``StringBuilder`` instead of string.
  117. Alternatively, you can use ``string.Remove``.
  118. * ``IsSubsequenceOf``/``IsSubsequenceOfi``: An additional method is provided,
  119. which is an overload of ``IsSubsequenceOf``, allowing you to explicitly specify
  120. case sensitivity:
  121. .. code-block:: csharp
  122. str.IsSubsequenceOf("ok"); // Case sensitive
  123. str.IsSubsequenceOf("ok", true); // Case sensitive
  124. str.IsSubsequenceOfi("ok"); // Case insensitive
  125. str.IsSubsequenceOf("ok", false); // Case insensitive
  126. * ``Match``/``Matchn``/``ExprMatch``: An additional method is provided besides
  127. ``Match`` and ``Matchn``, which allows you to explicitly specify case sensitivity:
  128. .. code-block:: csharp
  129. str.Match("*.txt"); // Case sensitive
  130. str.ExprMatch("*.txt", true); // Case sensitive
  131. str.Matchn("*.txt"); // Case insensitive
  132. str.ExprMatch("*.txt", false); // Case insensitive
  133. Basis
  134. -----
  135. Structs cannot have parameterless constructors in C#. Therefore, ``new Basis()``
  136. initializes all primitive members to their default value. Use ``Basis.Identity``
  137. for the equivalent of ``Basis()`` in GDScript and C++.
  138. The following method was converted to a property with a different name:
  139. ==================== ==============================================================
  140. GDScript C#
  141. ==================== ==============================================================
  142. ``get_scale()`` ``Scale``
  143. ==================== ==============================================================
  144. Transform2D
  145. -----------
  146. Structs cannot have parameterless constructors in C#. Therefore, ``new Transform2D()``
  147. initializes all primitive members to their default value.
  148. Please use ``Transform2D.Identity`` for the equivalent of ``Transform2D()`` in GDScript and C++.
  149. The following methods were converted to properties with their respective names changed:
  150. ==================== ==============================================================
  151. GDScript C#
  152. ==================== ==============================================================
  153. ``get_rotation()`` ``Rotation``
  154. ``get_scale()`` ``Scale``
  155. ==================== ==============================================================
  156. Plane
  157. -----
  158. The following method was converted to a property with a *slightly* different name:
  159. ================ ==================================================================
  160. GDScript C#
  161. ================ ==================================================================
  162. ``center()`` ``Center``
  163. ================ ==================================================================
  164. Rect2
  165. -----
  166. The following field was converted to a property with a *slightly* different name:
  167. ================ ==================================================================
  168. GDScript C#
  169. ================ ==================================================================
  170. ``end`` ``End``
  171. ================ ==================================================================
  172. The following method was converted to a property with a different name:
  173. ================ ==================================================================
  174. GDScript C#
  175. ================ ==================================================================
  176. ``get_area()`` ``Area``
  177. ================ ==================================================================
  178. Quat
  179. ----
  180. Structs cannot have parameterless constructors in C#. Therefore, ``new Quat()``
  181. initializes all primitive members to their default value.
  182. Please use ``Quat.Identity`` for the equivalent of ``Quat()`` in GDScript and C++.
  183. The following methods were converted to a property with a different name:
  184. ===================== =============================================================
  185. GDScript C#
  186. ===================== =============================================================
  187. ``length()`` ``Length``
  188. ``length_squared()`` ``LengthSquared``
  189. ===================== =============================================================
  190. Array
  191. -----
  192. *This is temporary. PackedArrays will need their own types to be used the way they are meant to.*
  193. ====================== ==============================================================
  194. GDScript C#
  195. ====================== ==============================================================
  196. ``Array`` ``Godot.Collections.Array``
  197. ``PackedInt32Array`` ``int[]``
  198. ``PackedInt64Array`` ``long[]``
  199. ``PackedByteArray`` ``byte[]``
  200. ``PackedFloat32Array`` ``float[]``
  201. ``PackedFloat64Array`` ``double[]``
  202. ``PackedStringArray`` ``String[]``
  203. ``PackedColorArray`` ``Color[]``
  204. ``PackedVector2Array`` ``Vector2[]``
  205. ``PackedVector3Array`` ``Vector3[]``
  206. ====================== ==============================================================
  207. ``Godot.Collections.Array<T>`` is a type-safe wrapper around ``Godot.Collections.Array``.
  208. Use the ``Godot.Collections.Array<T>(Godot.Collections.Array)`` constructor to create one.
  209. Dictionary
  210. ----------
  211. Use ``Godot.Collections.Dictionary``.
  212. ``Godot.Collections.Dictionary<T>`` is a type-safe wrapper around ``Godot.Collections.Dictionary``.
  213. Use the ``Godot.Collections.Dictionary<T>(Godot.Collections.Dictionary)`` constructor to create one.
  214. Variant
  215. -------
  216. ``System.Object`` (``object``) is used instead of ``Variant``.
  217. Communicating with other scripting languages
  218. --------------------------------------------
  219. This is explained extensively in :ref:`doc_cross_language_scripting`.
  220. Yield
  221. -----
  222. Something similar to GDScript's ``yield`` with a single parameter can be achieved with
  223. C#'s `yield keyword <https://docs.microsoft.com/en-US/dotnet/csharp/language-reference/keywords/yield>`_.
  224. The equivalent of yield on signal can be achieved with async/await and ``Godot.Object.ToSignal``.
  225. Example:
  226. .. code-block:: csharp
  227. await ToSignal(timer, "timeout");
  228. GD.Print("After timeout");
  229. Other differences
  230. -----------------
  231. ``preload``, as it works in GDScript, is not available in C#.
  232. Use ``GD.Load`` or ``ResourceLoader.Load`` instead.
  233. Other differences:
  234. ================ ==================================================================
  235. GDScript C#
  236. ================ ==================================================================
  237. ``Color8`` ``Color.Color8``
  238. ``is_inf`` ``float.IsInfinity``
  239. ``is_nan`` ``float.IsNaN``
  240. ``dict2inst`` TODO
  241. ``inst2dict`` TODO
  242. ================ ==================================================================