Conceptos básicos de C #

Introducción

Advertencia

El soporte C# es una nueva característica en Godot 3.0. Como tal, es posible que todavía encuentres algunos problemas o puntos en los que la documentación podría mejorarse. Por favor, informe de los problemas con C# en Godot en engine Github page. Y cualquier problema de documentación en documentation Github Page.

Esta página proporciona una breve introducción a C#, tanto lo que es y cómo usarlo en Godot. Después, puede que quiera ver cómo usar características específicas, lea sobre :ref:diferencias entre C# y GDScript API <doc_c_sharp_differences>` y (re)visite la sección Scripting del tutorial paso a paso.

C# es un lenguaje de programación de alto nivel desarrollado por Microsoft. En Godot se implementa con el framework .NET Mono 6.x, incluyendo soporte completo para C# 8.0. Mono es una implementación de código abierto del Microsoft's .NET Framework basada en los estándares ECMA para C# y Common Language Runtime. Un buen punto de partida para comprobar sus capacidades es la página Compatibilidad de la documentación de Mono.

Nota

Este es no un tutorial a gran escala sobre el lenguaje C# en general. Si aún no está familiarizado con su sintaxis o características, consulte la guía Microsoft C# o busque una introducción adecuada en otro lugar.

Configuración C# para Godot

Pre-requisitos

Install the latest stable version of .NET Core SDK (3.1 as of writing).

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 include the tools required to build and compile games, such as MSBuild. These tools need to be installed separately. The required tools are included in the .NET Core SDK. MSBuild is also included in the Mono SDK, but it can't build C# projects with the new csproj format, therefore .NET Core SDK is required for Godot 3.2.3+.

In summary, you must have installed .NET Core SDK and the Mono-enabled version of Godot.

Notas adicionales

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 Compiling with Mono page.

Configuración de un editor externo

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.

En Rider:

  • Set MSBuild version to .NET Core.

  • Instale el plugin de Godot support.

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.

En Visual Studio Code:

To configure a project for debugging open the Godot project folder in VS Code. Go to the Run tab and click on create a launch.json file. Select C# Godot from the dropdown menu. 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.

Next, you need to download the Godot Visual Studio extension from github here. Double click on the downloaded file and follow the installation process.

Creando un script de C#

Después de configurar con éxito C# para Godot, debería ver la siguiente opción al seleccionar Añadir script en el menú contextual de un nodo en su escena:

../../../_images/attachcsharpscript.png

Observaras que, aunque algunos elementos específicos cambian, la mayoría funciona de la misma manera al usar C# para escribir código. Si estás comenzando con Godot, quizás sea buena idea en este momento mirar los tutoriales en Scripting. Aunque es cierto que algunas partes de la documentación no contiene ejemplos en C#, la mayoría de los ejemplos son fácilmente transferibles desde GDScript.

Ajustes del proyecto y flujo de trabajo

Cuando creas el primer script en C#, Godot inicializa los archivos de proyecto de C# para tu proyecto actual. Esto incluye generar una solución C# (.sln) y un archivo de proyecto (.csproj) y también algunas utilidades y carpetas (.mono, y algunas veces Properties/AssemblyInfo.cs). Todos estos salvo .mono son importantes y deben formar parte de tu sistema de control de versiones. .mono se puede añadir a la lista de ignorados de tu VCS. Cuando hay problemas, algunas veces ayuda borrar la carpeta .mono y dejar que se vuelva a generar.

Ejemplo

Aquí hay un script C# en blanco con algunos comentarios para demostrar cómo funciona.

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.
    }
}

Como se puede ver, las funciones de alcance global en GDScript como la función print de Godot están disponibles en la clase GD que forma parte del espacio de nombres Godot. Para ver una lista de los métodos de la clase GD, consulta las páginas de referencia de la clase para @GDScript y @GlobalScope.

Nota

Ten en cuenta que la clase que deseas adjuntar a tu nodo debe ser nombrada igual que el archivo .cs. De lo contrario, se producirá el siguiente error y no se podrá ejecutar la escena: "Cannot find class XXX for script res://XXX.cs"

Diferencias generales entre C# y GDScript

La API de C# usa PascalCase en lugar de snake_case en GDScript/C++. Siempre que ha sido posible, los campos y los getters/setters han sido convertidos a propiedades. En general, la API de C# Godot se esfuerza por ser fluida tanto como sea razonablemente posible.

Para más información, consulta la página Diferencias de la API de C# con GDScript.

Advertencia

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.

También tendrás que reconstruir los ensamblajes del proyecto para aplicar los cambios en los scripts de las "herramientas".

Problemas actuales y problemas conocidos

Como el soporte de C# es bastante nuevo en Godot, hay algunos problemas de desarrollo y cosas que necesitan ser solucionadas. Abajo hay una lista de los temas más importantes que debes tener en cuenta cuando te sumerjas en C# en Godot, pero si tienes alguna duda, también puedes echar un vistazo al rastreador oficial de incidencias de Mono.

  • Es posible crear plugins para el editor, pero actualmente es bastante complicado.

  • Actualmente, el estado no se está guardando y se restaura durante la recarga en caliente, con la excepción de las variables exportadas.

  • Los scripts adjuntos de C# deben referirse a una clase que tenga el mismo nombre que el nombre del archivo. O lo que es lo mismo, el nombre de la clase que se declara en el script y el nombre del archivo deben ser igual.

  • Hay algunos métodos como Get()/Set(), Call()/CallDeferred() y el método de conexión de señales Connect() que se basan en las convenciones de nomenclatura de la API snake_case de Godot. Así que cuando se utiliza, por ejemplo, CallDeferred("AddChild"), AddChild no funcionará porque la API está esperando la versión original de snake_case add_child. Sin embargo, puedes usar cualquier propiedad o método personalizado sin esta limitación.

Exporting Mono projects is supported for desktop platforms (Linux, Windows and macOS), Android, HTML5, and iOS. The only platform not supported yet is UWP.

Rendimiento de C# en Godot

De acuerdo con algunos benchmarks preliminares, el rendimiento de C# en Godot - aunque generalmente en el mismo orden de magnitud - es aproximadamente ~4× el de GDScript en algunos casos ingenuos. C++ es todavía un poco más rápido; las especificaciones van a variar de acuerdo a su caso de uso. GDScript probablemente sea lo suficientemente rápido para la mayoría de las cargas de trabajo de scripting habituales. C# es más rápido, pero requiere de una organización más costosa cuando se comunica con Godot.

Uso de los paquetes NuGet en Godot

Los paquetes NuGet pueden ser instalados y usados en Godot, como en cualquier proyecto C#. Muchos IDEs pueden añadir paquetes directamente. También se pueden añadir manualmente añadiendo la referencia del paquete en el archivo .csproj ubicado en la raíz del proyecto:

    <ItemGroup>
        <PackageReference Include="Newtonsoft.Json" Version="11.0.2" />
    </ItemGroup>
    ...
</Project>

As of Godot 3.2.3, Godot automatically downloads and sets up newly added NuGet packages the next time it builds the project.

Evaluando tu código C#

  • Mono log profiler está disponible para Linux y macOS. Debido a un cambio de Mono, no funciona en Windows actualmente.

  • Un perfil Mono externo como JetBrains dotTrace puede ser usado como se describe aquí.