diff --git a/tutorials/scripting/c_sharp/c_sharp_basics.rst b/tutorials/scripting/c_sharp/c_sharp_basics.rst deleted file mode 100644 index 18162c2..0000000 --- a/tutorials/scripting/c_sharp/c_sharp_basics.rst +++ /dev/null @@ -1,320 +0,0 @@ -.. _doc_c_sharp: - -C# basics -========= - -Introduction ------------- - -.. warning:: C# support is a new feature available since Godot 3.0. - As such, you may still run into some issues, or find spots - where the documentation could be improved. - Please report issues with C# in Godot on the - `engine GitHub page `_, - and any documentation issues on the - `documentation GitHub page `_. - -This page provides a brief introduction 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 `, read about the -:ref:`differences between the C# and the GDScript API ` -and (re)visit the :ref:`Scripting section ` of the -step-by-step tutorial. - -C# is a high-level programming language developed by Microsoft. In Godot, -it is implemented with the Mono 6.x .NET framework, including full support -for C# 8.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 `_ -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 `_ - or look for a suitable introduction elsewhere. - -.. _doc_c_sharp_setup: - -Setting up C# for Godot ------------------------ - -Prerequisites -~~~~~~~~~~~~~ - -Install the latest stable version of the -`.NET SDK `__, previously known as the -.NET Core SDK. - -From Godot 3.2.3 onwards, installing Mono SDK is not a requirement anymore, -except it is required if you are building the engine from source. - -Godot bundles the parts of Mono needed to run already compiled games. -However, Godot does not bundle the tools required to build and compile -games, such as MSBuild and the C# compiler. These are -included in the .NET SDK, which needs to be installed separately. - -In summary, you must have installed the .NET SDK -**and** the Mono-enabled version of Godot. - -Additional notes -~~~~~~~~~~~~~~~~ - -Be sure to install the 64-bit version of the SDK(s) -if you are using the 64-bit version of Godot. - -If you are building Godot from source, install the latest stable version of -`Mono `__, and make sure to -follow the steps to enable Mono support in your build as outlined in the -:ref:`doc_compiling_with_mono` page. - -Configuring an external editor ------------------------------- - -C# support in Godot's built-in script editor is minimal. Consider using an -external IDE or editor, such as `Visual Studio Code `__ -or MonoDevelop. These provide autocompletion, debugging, and other -useful features for C#. To select an external editor in Godot, -click on **Editor → Editor Settings** and scroll down to -**Mono**. Under **Mono**, click on **Editor**, and select your -external editor of choice. Godot currently supports the following -external editors: - -- Visual Studio 2019 -- Visual Studio Code -- MonoDevelop -- Visual Studio for Mac -- JetBrains Rider - -See the following sections for how to configure an external editor: - -JetBrains Rider -~~~~~~~~~~~~~~~ - -After reading the "Prerequisites" section, you can download and install -`JetBrains Rider `__. - -In Godot's **Editor → Editor Settings** menu: - -- Set **Mono** -> **Editor** -> **External Editor** to **JetBrains Rider**. -- Set **Mono** -> **Builds** -> **Build Tool** to **dotnet CLI**. - -In Rider: - -- Set **MSBuild version** to **.NET Core**. -- Install the **Godot support** plugin. - -Visual Studio Code -~~~~~~~~~~~~~~~~~~ - -After reading the "Prerequisites" section, you can download and install -`Visual Studio Code `__ (aka VS Code). - -In Godot's **Editor → Editor Settings** menu: - -- Set **Mono** -> **Editor** -> **External Editor** to **Visual Studio Code**. -- Set **Mono** -> **Builds** -> **Build Tool** to **dotnet CLI**. - -In Visual Studio Code: - -- Install the `C# `__ extension. -- Install the `Mono Debug `__ extension. -- Install the `C# Tools for Godot `__ extension. - -.. note:: If you are using Linux you need to install the - `Mono SDK `__ - for the C# tools plugin to work. - -To configure a project for debugging open the Godot project folder in VS Code. -Go to the Run tab and click on **Add Configuration...**. Select **C# Godot** -from the dropdown menu. Open the ``tasks.json`` and ``launch.json`` files that -were created. Change the executable setting in ``launch.json`` and command -settings in ``tasks.json`` to your Godot executable path. Now, when you start -the debugger in VS Code, your Godot project will run. - -Visual Studio (Windows only) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Download and install the latest version of -`Visual Studio `__. -Visual Studio will include the required SDKs if you have the correct -workloads selected, so you don't need to manually install the things -listed in the "Prerequisites" section. - -While installing Visual Studio, select these workloads: - -- Mobile development with .NET -- .NET Core cross-platform development - -In Godot's **Editor → Editor Settings** menu: - -- Set **Mono** -> **Editor** -> **External Editor** to **Visual Studio**. -- Set **Mono** -> **Builds** -> **Build Tool** to **dotnet CLI**. - -Next, you can download the Godot Visual Studio extension from github -`here `__. -Double click on the downloaded file and follow the installation process. - -.. note:: The option to debug your game in Visual Studio may not appear after - installing the extension. To enable debugging, there is a - `workaround for Visual Studio 2019 `__. - There is - `a separate issue about this problem in Visual Studio 2022 `__. - -.. note:: If you see an error like "Unable to find package Godot.NET.Sdk", - your NuGet configuration may be incorrect and need to be fixed. - - A simple way to fix the NuGet configuration file is to regenerate it. - In a file explorer window, go to ``%AppData%\NuGet``. Rename or delete - the ``NuGet.Config`` file. When you build your Godot project again, - the file will be automatically created with default values. - -Creating a C# script --------------------- - -After you successfully set up 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 concepts work the same -when using C# for scripting. If you're new to Godot, you may want to follow -the tutorials on :ref:`doc_scripting` at this point. -While some places in the documentation still lack C# examples, most concepts -can be transferred easily from GDScript. - -Project setup and workflow --------------------------- - -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 a project file (``.csproj``), as well as some utility files and folders -(``.mono`` and ``Properties/AssemblyInfo.cs``). -All of these but ``.mono`` are important and should be committed to your -version control system. ``.mono`` can be safely added to the ignore list of your VCS. -When troubleshooting, it can sometimes help to delete the ``.mono`` folder -and let it regenerate. - -Example -------- - -Here's a blank C# script with some comments to demonstrate how it works. - -.. code-block:: csharp - - using Godot; - using System; - - public class YourCustomClass : Node - { - // Member variables here, example: - private int a = 2; - private string b = "textvar"; - - public override void _Ready() - { - // 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) - { - // Called every frame. Delta is time since the last frame. - // Update game logic here. - } - } - -As you can see, functions normally in global scope in GDScript like Godot's -``print`` function are available in the ``GD`` class which is part of -the ``Godot`` namespace. For a list of methods in the ``GD`` class, see the -class reference pages for -:ref:`@GDScript ` and :ref:`@GlobalScope `. - -.. note:: - Keep in mind that the class you wish to attach to your node should have the same - name as the ``.cs`` file. Otherwise, you will get the following error - and won't be able to run the scene: - *"Cannot find class XXX for script res://XXX.cs"* - -General differences between C# and GDScript -------------------------------------------- - -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 information, see the :ref:`doc_c_sharp_differences` page. - -.. warning:: - - You need to (re)build the project assemblies whenever you want to see new - exported variables or signals in the editor. This build can be manually - triggered by clicking the word **Build** in the top right corner of the - editor. You can also click **Mono** at the bottom of the editor window - to reveal the Mono panel, then click the **Build Project** button. - - You will also need to rebuild the project assemblies to apply changes in - "tool" scripts. - -Current gotchas and known issues --------------------------------- - -As C# support is quite new in Godot, there are some growing pains and things -that 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 `_. - -- Writing editor plugins is possible, but it is currently quite convoluted. -- State is currently not saved and restored when hot-reloading, - with the exception of exported variables. -- Attached C# scripts should refer to a class that has a class name - that matches the file name. -- There are some methods such as ``Get()``/``Set()``, ``Call()``/``CallDeferred()`` - and signal connection method ``Connect()`` that rely on Godot's ``snake_case`` API - naming conventions. - So when using e.g. ``CallDeferred("AddChild")``, ``AddChild`` will not work because - the API is expecting the original ``snake_case`` version ``add_child``. However, you - can use any custom properties or methods without this limitation. - - -Exporting Mono projects is supported for desktop platforms (Linux, Windows and -macOS), Android, HTML5, and iOS. The only platform not supported yet is UWP. - -Performance of C# in Godot --------------------------- - -According to some preliminary `benchmarks `_, -the performance of C# in Godot — while generally in the same order of magnitude -— is roughly **~4×** that of GDScript in some naive cases. 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. - -Using NuGet packages in Godot ------------------------------ - -`NuGet `_ packages can be installed and used with Godot, -as with any C# project. Many IDEs are able to add packages directly. -They can also be added manually by adding the package reference in -the ``.csproj`` file located in the project root: - -.. code-block:: xml - :emphasize-lines: 2 - - - - - ... - - -As of Godot 3.2.3, Godot automatically downloads and sets up newly added NuGet -packages the next time it builds the project. - -Profiling your C# code ----------------------- - -- `Mono log profiler `_ is available for Linux and macOS. Due to a Mono change, it does not work on Windows currently. -- External Mono profiler like `JetBrains dotTrace `_ can be used as described `here `_. diff --git a/tutorials/scripting/c_sharp/c_sharp_differences.rst b/tutorials/scripting/c_sharp/c_sharp_differences.rst deleted file mode 100644 index 6b586dc..0000000 --- a/tutorials/scripting/c_sharp/c_sharp_differences.rst +++ /dev/null @@ -1,358 +0,0 @@ -.. _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 -^^^^^^^^^ - -Global constants were moved to their own enums. -For example, ``ERR_*`` constants were moved to the ``Error`` enum. - -Special cases: - -======================= =========================================================== -GDScript C# -======================= =========================================================== -``SPKEY`` ``GD.SpKey`` -``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``. - -Random functions -^^^^^^^^^^^^^^^^ - -Random global functions, like ``rand_range`` and ``rand_seed``, are located under ``GD``. -Example: ``GD.RandRange`` and ``GD.RandSeed``. - -Other functions -^^^^^^^^^^^^^^^ - -Many other global functions like ``print`` and ``var2str`` are located under ``GD``. -Example: ``GD.Print`` and ``GD.Var2Str``. - -Exceptions: - -=========================== ======================================================= -GDScript C# -=========================== ======================================================= -``weakref(obj)`` ``Object.WeakRef(obj)`` -``is_instance_valid(obj)`` ``Object.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"); - } - } - -Export keyword --------------- - -Use the ``[Export]`` attribute instead of the GDScript ``export`` keyword. -This attribute can also be provided with optional :ref:`PropertyHint` and ``hintString`` parameters. -Default values can be set by assigning a value. - -Example: - -.. code-block:: csharp - - using Godot; - - public 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; - } - -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. - -.. code-block:: csharp - - [Signal] - delegate void MySignal(string willSendsAString); - -See also: :ref:`doc_c_sharp_signals`. - -`onready` keyword ------------------ - -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_keyword`). -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