Improve C# intro docs

learning/editor/unity_to_godot.rst

@@ -105,7 +105,7 @@ Finally, the main scene would then be composed of one root node with 2 children:
 The root node can be anything, generally a "root" type such as "Node" which is the most global type, or "Node2D" (root type of all 2D-related nodes), "Spatial" (root type of all 3D-related nodes) or "Control" (root type of all GUI-related nodes).
 
 
-As you can see, every scene is organized as a tree. The same goes for nodes' properties: you don't *add* a collision component to a node to make it collidable like Unity does. Instead, you make this node a *child* of a new specific node that has collision properties. Godot features various collision types nodes, depending of the use (see the :ref:`Physics introduction <_doc_pysics_introduction>`).
+As you can see, every scene is organized as a tree. The same goes for nodes' properties: you don't *add* a collision component to a node to make it collidable like Unity does. Instead, you make this node a *child* of a new specific node that has collision properties. Godot features various collision types nodes, depending of the use (see the :ref:`Physics introduction <doc_physics_introduction>`).
 
 - Question: What are the advantages of this system? Wouldn't this system potentially increase the depth of the scene tree? Besides, Unity allows organizing GameObjects by putting them in empty GameObjects.
 
@@ -149,19 +149,19 @@ Add a component -> Inheriting
 Prefab -> Externalized branch
 
 
-Scripting : From C# to GDScript
--------------------------------
+Scripting: GDScript, C# and Visual Script
+-----------------------------------------
 
 Design
 ^^^^^^
 
-As you may know already, Unity supports 2 scripting languages for its API: C# and Javascript (called UnityScript). Both languages can be used in the same project (but not in the same file, of course). Choosing one instead of the other is a matter of personal taste, as performances seem not to be affected that much by the use of Javascript as long as the project remains small. C# benefits from its integration with Visual Studio and other specific features, such as static typing.
+As you may know already, Unity supports C#. C# benefits from its integration with Visual Studio and other features, such as static typing.
 
-Godot provides its own scripting language: GDScript. This language borrows its syntax to Python, but is not related to it. If you wonder about why GDScript and not Lua, C# or any other, please read :ref:`GDScript <doc_gdscript>` and `FAQ <faq>`_ pages. GDScript is strongly attached to Godot API, but it is really easy to learn: between 1 evening for an experimented programmer and 1 week for a complete beginner.
+Godot provides its own scripting language, :ref:`GDScript <doc_scripting>` as well as support for :ref:`Visual Script <toc-learn-scripting-visual_script>` and :ref:`doc_c_sharp`. GDScript borrows its syntax from Python, but is not related to it. If you wonder about the reasoning for a custom scripting language, please read :ref:`GDScript <doc_gdscript>` and `FAQ <faq>`_ pages. GDScript is strongly attached to the Godot API, but it is really easy to learn: between one evening for an experienced programmer and a week for a complete beginner.
 
 Unity allows you to attach as many scripts as you want to a GameObject. Each script adds a behaviour to the GameObject: for example, you can attach a script so that it reacts to the player's controls, and another that controls its specific game logic.
 
-In Godot, you can only attach one script per node. You can use either an external GDScript file, or include it directly in the node. If you need to attach more scripts to one node, then you may consider 2 solutions, depending on your scene and on what you want to achieve:
+In Godot, you can only attach one script per node. You can use either an external GDScript file, or include it directly in the node. If you need to attach more scripts to one node, then you may consider two solutions, depending on your scene and on what you want to achieve:
 
 - either add a new node between your target node and its current parent, then add a script to this new node. 
 - or, your can split your target node into multiple children and attach one script to each of them.

learning/scripting/c_sharp/c_sharp_basics.rst

@@ -1,49 +1,93 @@
 .. _doc_c_sharp:
 
-C#
-===
-
 Introduction
---------------
+============
+
+.. warning:: C# support is a new feature in Godot 3.0.
+	     As such, you may still run into some issues or find spots where the documentation could be improved.
+	     Please report those issues on `Github <https://github.com/godotengine/godot/issues>`_.
 
-C# is a high-level programming language developed by Microsoft. In Godot it is implemented with the Mono 5.2 .NET framework including full support for C# 7.0.   
+This page provides a brief intro to C#, both what it is and how to use it in Godot.
+Afterwards, you may want to look at :ref:`how to use specific features <doc_c_sharp_features>`,
+read about the :ref:`differences between the C# and the GDScript API <doc_c_sharp_differences>`
+and (re)visit the :ref:`Scripting section <doc_scripting>` of the step-by-step tutorial.
+
+C# is a high-level programming language developed by Microsoft. In Godot it is implemented with the Mono 5.2 .NET framework including full support for C# 7.0.
+Mono is an open source implementation of Microsoft's .NET Framework based on the ECMA standards for C# and the Common Language Runtime.
+A good starting point for checking its capabilities is the `Compatibility <http://www.mono-project.com/docs/about-mono/compatibility/>`_ page in the Mono documentation.
 
 .. note:: This is **not** a full-scale tutorial on the C# language as a whole.
         If you aren't already familiar with its syntax or features,
-        see the `Microsoft C# guide <https://docs.microsoft.com/en-us/dotnet/csharp/index>`_.
+        see the `Microsoft C# guide <https://docs.microsoft.com/en-us/dotnet/csharp/index>`_ or look for a suitable introduction elsewhere.
+
+Setup C# for Godot
+------------------
 
-Necessary Downloads
--------------------------
+To use C# in Godot you must have `Mono <http://www.mono-project.com/download/>`_ installed (at least version 5.2).
 
-To use C# in Godot you must have `Mono <http://www.mono-project.com/download/>`_
-installed (at least version 5.2), and use a Godot version with Mono enabled, which adds C# support next to the existing options of GDScript, visual scripting and C++.
+Additionally, your Godot version must have Mono support enabled, so take care to download the **Mono version** of Godot.
+If you are building Godot from source, make sure to follow the steps to include Mono support in your build outlined on the  :ref:`doc_compiling_with_mono` page.
 
 Windows users also need MS Build 15.0, which comes bundled with Visual Studio 2017,
 or can be downloaded separately with `build tools for Visual Studio 2017 <https://www.visualstudio.com/thank-you-downloading-visual-studio/?sku=BuildTools&rel=15#>`_.
 
+Configuring an external editor
+------------------------------
+
+While Godot does have its own scripting editor, its support for C# is kept
+minimal, and it's recommended that you use an external IDE or editor, such as
+Microsoft Visual Studio Code, or MonoDevelop, which provide auto-completion,
+debugging and other features useful when working with C#.
+To set it up, in Godot click on ``Editor``, then ``Editor Settings``. Scroll 
+down to the bottom, to the ``Mono`` settings. Under Mono click on ``Editor``,
+and on that page choose your external editor of choice.
+
+Creating a C# script
+--------------------
+
+After you sucessfully setup C# for Godot, you should see the following option when selecting ``Attach script`` in the context menu of a node in your scene:
+
+.. image:: img/attachcsharpscript.png
+
+Note that while some specifics change, most of the things work the same when using C# for scripting.
+If you're new to Godot, you may want to peruse the tutorials on :ref:`doc_scripting` at this point.
+While some places in the documentation still lack C# examples, most things can be transferred easily from GDScript.
+
+Project setup and workflow
+--------------------------
 
-History
---------
+When you create the first C# script, Godot initializes the C# project files for your Godot project.
+This includes generating a C# solution (``.sln``) and project (``.csproj``) as well as some utility files and folders (``.mono``, sometimes ``Properties``).
+All of these but ``.mono`` are important and should be kept in your version control system. ``.mono`` can be safely added to the ignore list of your VCS.
+When troubleshooting, it sometimes can help to delete the ``.mono`` folder and let it regenerate.
 
-Back in 2016 the Godot team reached out to Microsoft, with Miguel de Icaza's 
-support, to see if they would consider funding C# support being added to 
-Godot. Microsoft agreed and gave the team a $24,000 donation to work on adding
-C# support. Thanks to that donation, Juan Lineietsky and Ignacio Roldán 
-Etcheverry were able to work on bringing C# support to Godot using the Mono 
-.NET framework. Support was added to Godot version 3.0 using mono 5.2, giving users 
-the power of C# in their game making.
+Note that currently there are some issues where the Godot and the C# project don't stay in sync; if you delete, rename or move things like scripts or nodes, they may no longer match up.
+In this case, it can help to edit the solution files manually.
+
+Example: If you created a script (e.g. ``Test.cs``) and delete it in Godot, compilation will fail because the now missing file is still expected to be there by the CS project.
+You can for now simply open up the ``.csproj`` and look for the ``ItemGroup``, there should be a line included like the following:
+
+.. code-block:: xml
+   :emphasize-lines: 2
+
+    <ItemGroup>
+        <Compile Include="Test.cs" />``
+        <Compile Include="AnotherTest.cs" />``
+    </ItemGroup>
+
+Simply remove that line and your project should now again build fine. Same for renaming and moving things, simply rename and move them in the project file if needed.
 
 Example
 -------
 
-Here's a blank C# script with some comments to demonstate how it works. 
+Here's a blank C# script with some comments to demonstrate how it works. 
 
 .. code-block:: csharp
 
     using Godot;
     using System;
 
-    public class Path : Path
+    public class YourCustomClass : Node
     {
         // Member variables here, example:
         private int a = 2;
@@ -53,6 +97,7 @@ Here's a blank C# script with some comments to demonstate how it works.
         {
             // Called every time the node is added to the scene.
             // Initialization here
+            GD.Print("Hello from C# to Godot :)");
         }
 
         public override void _Process(float delta)
@@ -62,14 +107,33 @@ Here's a blank C# script with some comments to demonstate how it works.
         }
     }
 
+As you can see, the things normally in global scope in GDScript like Godot's ``print`` function are available in the ``GD`` namespace.
+For a list of those, see the class reference pages for :ref:`@GDScript <class_@gdscript>` and :ref:`@GlobalScope <class_@globalscope>`.
 
-Configuring an external editor
------------------------------------
+General differences between C# and GDScript
+-------------------------------------------
 
-While Godot does have its own scripting editor, its support for C# is kept
-minimal, and it's reccomended that you use an external IDE or editor, such as
-Microsoft Visual Studio Code, or MonoDevelop, which provide auto-completion,
-debugging and other features useful when working with C#.
-To set it up, in Godot click on ``Editor``, then ``Editor Settings``. Scroll 
-down to the bottom, to the ``Mono`` settings. Under Mono click on ``Editor``,
-and on that page choose your external editor of choice.
+The C# API uses ``PascalCase`` instead of ``snake_case`` in GDScript/C++.
+Where possible, fields and getters/setters have been converted to properties.
+In general, the C# Godot API strives to be as idiomatic as is reasonably possible.
+
+For more, see the :ref:`doc_c_sharp_differences` page.
+
+Current gotchas and known issues
+--------------------------------
+
+As C# support is quite new to Godot, there are some growing pains and things that still need to be ironed out.
+Below is a list of the most important issues you should be aware of when diving into C# in Godot, but if in doubt also take a look over the official `issue tracker for Mono issues <https://github.com/godotengine/godot/labels/topic%3Amono>`_.
+
+- As explained above, the C# project isn't always kept in sync automatically when things are deleted, renamed or moved in Godot (`#12917 <https://github.com/godotengine/godot/issues/12917>`_)
+- Signals can only be added with ``add_user_signal()`` and don't show up in UI (`#11956 <https://github.com/godotengine/godot/issues/11956>`_)
+- Debug output like stack traces, file path and line numbers is missing on Windows (`#14589 <https://github.com/godotengine/godot/issues/14589>`_)
+- Writing editor plugins and tool scripts in C# is not yet supported
+- Exporting a project may not yet work
+
+Performance of C# in Godot
+--------------------------
+
+According to some preliminary `benchmarks <https://github.com/cart/godot3-bunnymark>`_, performance of C# in Godot - while generally in the same order of magnitude - is roughly **~4x** that of GDScript in some naive cases.
+For full performance, C++ is still a little faster; the specifics are going to vary according to your use case. GDScript is likely fast enough for most general scripting workloads.
+C# is faster, but requires some expensive marshalling when talking to Godot.

learning/scripting/c_sharp/c_sharp_differences.rst

@@ -0,0 +1,220 @@
+.. _doc_c_sharp_differences:
+
+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`` in GDScript and C++.
+
+Global Scope
+------------
+
+Available under ``Godot.GD``.
+Some things were moved to their own classes, like Math and Random. See below.
+
+Global functions like ``print``, ``var2str`` and ``weakref`` are located under
+``GD`` in C#.
+
+``ERR_*`` constants were moved to ``Godot.Error``.
+
+Math
+----
+
+Math functions like ``abs``, ``acos``, ``asin``, ``atan`` and ``atan2`` are
+located under ``Mathf`` instead of in global scope.
+``PI`` is ``Mathf.PI``
+
+Random
+------
+
+Random functions like ``rand_range`` and ``rand_seed`` are located under ``Random``,
+so use ``Random.RandRange`` instead of ``rand_range``.
+
+Export keyword
+--------------
+
+Use the ``[Export]`` attribute instead of the GDScript ``export`` keyword.
+
+Singletons
+----------
+
+Singletons provide static methods rather than using the singleton pattern in C#.
+This is to make code less verbose and similar to GDScript. Example:
+
+.. code-block:: csharp
+
+    Input.IsActionPressed("ui_down")
+
+String
+------
+
+Use ``System.String`` (``string``). All the Godot String methods are provided
+by the ``StringExtensions`` class as extension methods. Example:
+
+.. code-block:: csharp
+
+    string upper = "I LIKE SALAD FORKS";
+    string lower = upper.ToLower();
+
+There are a few differences though:
+
+* ``erase``: Strings are immutable in C#, so we cannot modify the string
+  passed to the extension method. For this reason ``Erase`` was added as an
+  extension method of ``StringBuilder`` instead of string.
+  Alternatively you can use ``string.Remove``.
+* ``IsSubsequenceOf``/``IsSubsequenceOfi``: An additional method is provided
+  which is an overload of ``IsSubsequenceOf`` allowing to explicitly specify
+  case sensitivity:
+
+.. code-block:: csharp
+
+  str.IsSubsequenceOf("ok"); // Case sensitive
+  str.IsSubsequenceOf("ok", true); // Case sensitive
+  str.IsSubsequenceOfi("ok"); // Case insensitive
+  str.IsSubsequenceOf("ok", false); // Case insensitive
+
+* ``Match``/``Matchn``/``ExprMatch``: An additional method is provided besides
+  ``Match`` and ``Matchn``, which allows to explicitly specify case sensitivity:
+
+.. code-block:: csharp
+
+  str.Match("*.txt"); // Case sensitive
+  str.ExprMatch("*.txt", true); // Case sensitive
+  str.Matchn("*.txt"); // Case insensitive
+  str.ExprMatch("*.txt", false); // Case insensitive
+
+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 to ``Basis()`` in GDScript and C++.
+
+The following methods were converted to properties with their respective names changed:
+
+================  ==================================================================
+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 to ``Transform2D()`` in GDScript and C++.
+
+The following methods were converted to properties with their respective names changed:
+
+================  ==================================================================
+GDScript          C#
+================  ==================================================================
+get_origin()      Origin
+get_rotation()    Rotation
+get_scale()       Scale
+================  ==================================================================
+
+Plane
+-----
+
+The following methods were converted to properties with their respective names changed:
+
+================  ==================================================================
+GDScript          C#
+================  ==================================================================
+center()          Center
+================  ==================================================================
+
+Rect2
+-----
+
+The following fields were converted to properties with their respective names changed:
+
+================  ==================================================================
+GDScript          C#
+================  ==================================================================
+end               End
+================  ==================================================================
+
+The following methods were converted to properties with their respective names changed:
+
+================  ==================================================================
+GDScript          C#
+================  ==================================================================
+get_area()        Area
+================  ==================================================================
+
+Quat
+----
+
+Structs cannot have parameterless constructors in C#, therefore ``new Quat()``
+initializes all primitive members to their default value.
+Please use ``Quat.Identity`` for the equivalent to ``Quat()`` in GDScript and C++.
+
+Array
+-----
+
+*This is temporary. Array is ref-counted, so it will need its own type that wraps the native side.
+PoolArrays will also need their own type to be used the way they are meant to.*
+
+================  ==================================================================
+GDScript          C#
+================  ==================================================================
+Array             object[]
+PoolIntArray      int[]
+PoolByteArray     byte[]
+PoolFloatArray    float[]
+PoolStringArray   String[]
+PoolColorArray    Color[]
+PoolVector2Array  Vector2[]
+PoolVector3Array  Vector3[]
+================  ==================================================================
+
+In some exceptional cases a raw array (``type[]``) may be required instead of a ``List``.
+
+Dictionary
+----------
+
+*This is temporary. Array is ref-counted, so it will need its own type that wraps the native side.*
+
+Use ``Dictionary<object, object>``.
+
+Variant
+-------
+
+``System.Object`` (``object``) is used in place of ``Variant``.
+
+Communicating with other scripting languages
+--------------------------------------------
+
+The methods ``object Object.call(string method, params object[] args)``,
+``object Object.get(string field)`` and ``object Object.set(string field, object value)``
+are provided to communicate with instances of other
+scripting languages via the Variant API.
+
+Other differences
+-----------------
+
+``preload``, ``assert`` and ``yield`` as they work in GDScript are currently
+not available in C#.
+
+Other differences:
+
+================  ==================================================================
+GDScript          C#
+================  ==================================================================
+Color8            Color.Color8
+is_inf            float.IsInfinity
+is_nan            float.IsNaN
+dict2inst         ? TODO
+inst2dict         ? TODO
+load              GD.load which is the same as ResourceLoader.load
+================  ==================================================================
+
+

learning/scripting/c_sharp/c_sharp_features.rst

@@ -0,0 +1,93 @@
+.. _doc_c_sharp_features:
+
+Features
+============
+
+This page provied an overview over the commonly used features of both C# and Godot
+and how they are used together.
+
+Type Conversion and Casting
+---------------------------
+
+C# is a statically typed language. Therefore you can't do the following:
+
+.. code-block:: csharp
+
+    var mySprite = GetNode("MySprite")
+    mySprite.SetFrame(0)
+
+The method ``GetNode()`` returns a ``Node`` instance.
+You must explicitly convert it to the desired derived type, ``Sprite`` in this case.
+
+For this, you have various options in C#.
+
+**Casting and Type Checking**
+
+Throws ``InvalidCastException`` if the returned node cannot be casted to Sprite.
+You would use it instead of the ``as`` operator if you are pretty sure it won't fail.
+
+.. code-block:: csharp
+
+    Sprite mySprite = (Sprite)GetNode("MySprite");
+    mySprite.SetFrame(0);
+
+**Using the AS operator**
+
+The ``as`` operator returns null if the node cannot be casted to Sprite,
+and for this reason it cannot be used with value types.
+
+.. code-block:: csharp
+
+    Sprite mySprite = GetNode("MySprite") as Sprite;
+    // Only call SetFrame() is mySprite is not null
+    mySprite?.SetFrame(0);;
+
+**Type checking using the IS operator**
+
+To check if the node can be casted to Sprite, you can use the ``is`` operator.
+The ``is`` operator returns false if the node cannot be casted to Sprite,
+otherwise it returns true.
+
+.. code-block:: csharp
+
+    if (GetNode("MySprite") is Sprite)
+    {
+        // Yup, it's a sprite!
+    }
+
+For more advanced type checking, you can look into `Pattern Matching <https://docs.microsoft.com/en-us/dotnet/csharp/pattern-matching>`_.
+
+Signals
+-------
+
+For a complete C# example, see the **Handling a signal** section in the step by step :ref:`doc_scripting` tutorial.
+
+You can use ``Connect("SomeSignal", someObject, "SomeMethod")`` to connect to signals.
+``AddUserSignal("SignalName")`` is used to define custom signals.
+Emitting signals is done with ``EmitSignal("SignalName")``. Params can be given, like ``EmitSignal("SignalName", arg1, arg2, ...)``.
+
+**Custom signals**
+
+.. code-block:: csharp
+   :emphasize-lines: 5, 10
+   :linenos:
+
+    public class ExampleScript : Node
+    {
+        public override void _Ready()
+        {
+            AddUserSignal("YourSignal");
+        }
+
+        public override void _Process(float delta)
+        {
+            EmitSignal("YourSignal");
+        }
+    }
+
+Above in line 5, ``AddUserSignal()`` is used to define the new custom signal ``YourSignal``.
+In line 10 ``EmitSignal()`` is used to emit that custom signal on every frame in ``_Process()``.
+
+Make sure that ``AddUserSignal()`` is always executed before any calls using that signal (``EmitSignal()`` and ``Connect()``).
+If you are using both ``AddUserSignal()`` and ``Connect()`` or ``EmitSignal()`` in ``_Ready()``, this is especially important as load order of your node may change,
+and thus the order in which your various ``_Ready()`` functions are called.

learning/scripting/c_sharp/index.rst

@@ -6,5 +6,7 @@ C#
    :name: toc-learn-scripting-C#
 
    c_sharp_basics
+   c_sharp_features
+   c_sharp_differences