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¶

Instala la última versión estable del .NET SDK <https://dotnet.microsoft.com/download>, anteriormente conocido como .NET Core SDK.

Desde Godot 3.2.3 en adelante, la instalación de Mono SDK ya no es un requisito, excepto que es obligatorio si está construyendo el motor desde la fuente.

Godot incluye las partes de Mono necesarias para ejecutar juegos ya compilados. Sin embargo, Godot no incluye las herramientas necesarias para construir y compilar juegos, como MSBuild y el compilador de C#. Estas herramientas se incluyen en el .NET SDK, el cual debe ser instalado por separado.

En resumen, debes tener instalado tanto el .NET SDK como la versión habilitada para Mono de Godot.

Notas adicionales¶

Asegúrese de instalar la versión de 64 bits de los SDK si está utilizando la versión de 64 bits de Godot.

Si está compilando Godot desde la fuente, instale la última versión estable de`Mono <https://www.mono-project.com/download/stable/>`__, y asegúrese de seguir los pasos para habilitar el soporte Mono en su compilación como se describe en la página .:ref:doc_compiling_with_mono.

Configuración de un editor externo¶

El soporte de C# en el editor de scripts de Godot es mínimo. Considera utilizar un IDE o editor externo como Visual Studio Code o MonoDevelop. Estos proporcionan autocompletado, depuración, y otras características útiles para C#. Para seleccionar un editor externo en Godot, haz clic en Editor → Ajustes del Editor y ve hacia abajo hasta Mono. En Mono, haz clic en Editor y selecciona el editor externo que desees. Godot soporta actualmente los siguientes editores externos:

Visual Studio 2019
Visual Studio Code
MonoDevelop
Visual Studio for Mac
JetBrains Rider

Consulte las siguientes secciones para saber cómo configurar un editor externo:

JetBrains Rider¶

Después de leer la sección "Requisitos previos", puede descargar e instalar JetBrains Rider <https://www.jetbrains.com/rider/download> __.

En el menú Editor → Configuración del editor de Godot:

Establezca Mono -> Editor -> Editor externo a JetBrains Rider.
Establezca Mono -> Compilaciones -> Herramienta de compilación a dotnet CLI.

En Rider:

Establezca Vesión de MSBuild a .NET Core.
Instale el plugin de Godot support.

Visual Studio Code¶

Después de leer la sección "Requisitos previos", puede descargar e instalar Visual Studio Code <https://code.visualstudio.com/download> __ (también conocido como VS Code).

En el menú Editor → Configuración del editor de Godot:

Establezca Mono -> Editor -> Editor externo a Visual Studio Code.
Establezca Mono -> Compilaciones -> Herramienta de compilación a dotnet CLI.

En Visual Studio Code:

Instala la extensión C#.
Instala la extensión Mono Debug.
Instala la extensión C# Tools for Godot.

Nota

Si usas Linux necesitarás instalar Mono SDK <https://www.mono-project.com/download/stable/#download-lin> para que el plugin C# tools funcione.

Para configurar un proyecto para la depuración, abre la carpeta del proyecto de Godot en VS Code. Ve a la pestaña "Run" y haz clic en Agregar configuración.... Selecciona C# Godot en el menú desplegable. Abre los archivos tasks.json y launch.json que se crearon. Cambia la configuración "executable" en launch.json y las configuraciones "command" en tasks.json para que apunten a la ruta del ejecutable de Godot en tu sistema. Ahora, cuando inicies el depurador en VS Code, se ejecutará tu proyecto de Godot.

Visual Studio (Solo Windows)¶

Descargue e instale la última versión de Visual Studio <https://visualstudio.microsoft.com/downloads/> __. Visual Studio incluirá los SDK necesarios si ha seleccionado las cargas de trabajo correctas, por lo que no es necesario que instale manualmente las cosas que se enumeran en la sección "Requisitos previos".

Mientras instala Visual Studio, seleccione estos workloads:

Desarrollo mobile con .NET
Desarrollo multiplataforma de .NET Core

En el menú Editor → Configuración del editor de Godot:

Establezca Mono -> Editor -> Editor externo a Visual Studio.
Establezca Mono -> Compilaciones -> Herramienta de compilación a dotnet CLI.

A continuación, debe descargar la extensión de Godot Visual Studio desde github aquí <https://github.com/godotengine/godot-csharp-visualstudio/releases> __. Haga doble clic en el archivo descargado y siga el proceso de instalación.

Nota

La opción para depurar tu juego en Visual Studio puede que no aparezca después de instalar la extensión. Para habilitar la depuración, hay un solucionador temporal para Visual Studio 2019 disponible en este enlace: `https://github.com/godotengine/godot-csharp-visualstudio/issues/10#issuecomment-720153256`__. Además, existe un problema separado sobre este problema en Visual Studio 2022 que se discute aquí: `https://github.com/godotengine/godot-csharp-visualstudio/issues/28`__.

Nota

Si ves un error como "Unable to find package Godot.NET.Sdk", es posible que la configuración de NuGet esté incorrecta y necesite ser corregida.

Una forma sencilla de corregir el archivo de configuración de NuGet es regenerándolo. En una ventana del explorador de archivos, ve a %AppData%\NuGet. Cambia el nombre o elimina el archivo NuGet.Config. Cuando vuelvas a construir tu proyecto de Godot, el archivo se creará automáticamente con los valores predeterminados.

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:

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 Lenguaje de 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

Necesita (re) construir los ensamblajes del proyecto cada vez que desee ver nuevas variables o señales exportadas en el editor. Esta compilación se puede activar manualmente haciendo clic en la palabra Mono en la parte inferior de la ventana del editor para revelar el panel Mono, luego haciendo clic en el botón Compilar proyecto.

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.

La exportación de proyectos Mono es compatible con plataformas de escritorio (Linux, Windows y macOS), Android, HTML5 e iOS. La única plataforma que aún no es compatible es 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>

A partir de Godot 3.2.3, Godot descarga y configura automáticamente los paquetes NuGet recién agregados la próxima vez que compila el proyecto.

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