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

Windows (Visual Studio)

Descarga e instala la última versión de Visual Studio (no Visual Studio Code), que contiene las utilidades necesarias para utilizar C# en Godot. Si no planeas usar el IDE de Visual Studio, puedes descargar sólo Visual Studio Build Tools en su lugar. Asegúrate de tener instalado al menos el paquete .NET Framework 4.5, puedes obtenerlo usando cualquiera de los instaladores mencionados anteriormente dentro de la pestaña "Componentes individuales".

Windows (JetBrains Rider)

JetBrains Rider viene con MSBuild incluído, así que no se requiere nada extra. Asegúrate de configurar las siguientes preferencias:

  • En Godot:

    • Mono Editor externo para JetBrains Rider
    • Mono Build Tool a JetBrains Mono.
  • En Rider:

    • Conjunto `Msbuild versión para ya sea incluido con Rider o . NET Core.
    • Instalar el plugin Godot support.

macOS y Linux

Descarga e instala la última versión del SDK Mono <http://www.mono-project.com/download/>. Como en el caso de Godot 3.1 beta 3, el número de versión no tiene importancia desde que Godot agrupa su propia instalación Mono 5.18. Solamente necesitaremos la instalación mono para NuGet y MSBuild, los cuales son requeridos para el uso de C# en Godot.

Nota

Para descargar Mono en macOS, utiliza el enlace "Stable Channel" de la página Mono Downloads Page. El canal Visual Studio es una versión anterior de Mono y no funcionará.

Notas adicionales

Tu versión de Godot debe tener habilitada la compatibilidad con Mono, así que asegúrate de descargar la ** versión Mono ** de Godot. Si estás compilando Godot desde el código fuente, asegúrate de seguir los pasos tal y cómo se describen en la página :ref :doc_compiling_with_mono para incluir soporte Mono en tu compilación.

En resumen, debes tener instalado Visual Studio o Mono (dependiendo de tu sistema operativo) y la versión Mono de Godot.

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

Nota

Si usas Visual Studio Code, asegúrate de descargar e instalar la extensión de C# para habilitar características como el resaltado de sintaxis y el IntelliSense.

Nota

Si utiliza Visual Studio 2019, debe seguir las instrucciones que se encuentran en la sección "Configurar VS2019 para la depuración" a continuación.

Creando un script de C#

Después de que hayas configurado adecuadamente C# para Godot, deberías ver la siguiente opción cuando selecciones Añadir script en el menú contextual de los nodos en tu 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++. En la medida de lo posible, los campos y los getters/setters se han convertido en propiedades. En general, la API de C# Godot se esfuerza en ser idiomática dentro de lo razonable.

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

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.

Así como Godot 3.2.2 soporta la exportación de proyectos Mono a plataformas de escritorio (Linux, Windows y macOS). Android, iOS, HTML5 y UWP no son compatibles actualmente.

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</Version>
        </PackageReference>
    </ItemGroup>
    ...
</Project>

Nota

Por defecto, herramientas como NuGet colocan "Version" como un atributo del nodo "PackageReference". Debes crear manualmente un nodo de Version como se muestra arriba. Esto se debe a que la versión de MSBuild usada requiere esto. (Esto se arreglará en Godot 4.0.)

Cada vez que se añadan o modifiquen paquetes, ejecuta nuget restore (no dotnet restore) en la raíz del directorio del proyecto. Para asegurarse de que los paquetes NuGet estén disponibles para ser usados por msbuild, ejecuta:

msbuild /t:restore

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

Configurando Visual Studio 2019 para la depuración

Nota

Godot tiene incorporado soporte para flujos de trabajo que involucran varios IDEs populares de C#. El soporte incorporado para Visual Studio se incluirá en futuras versiones, pero mientras tanto, los siguientes pasos pueden permitirte configurar Visual Studio 2019 para su uso con proyectos de Godot C#.

  1. Instalar Visual Studio 2019 con ".NET desktop development" y "Desktop development with C++" seleccionadas.
  2. **Asegúrate de no tener instalado Xamarin. No elijas la carga de trabajo de "Desarrollo móvil con .NET". Xamarin cambia las DLLs usadas por el MonoDebugger, lo que rompe la depuración.
  3. Instala la extensión "VSMonoDebugger" <https://marketplace.visualstudio.com/items?itemName=GordianDotNet.VSMonoDebugger0d62>`_.
  4. En Visual Studio 2019 --> Extensiones --> Mono --> Configuración:
    • Selecciona "Debug/Deploy to local Windows".
    • Deje en blanco "Ruta de Despliegue Local".
    • Coloca "Puerto de Depuración Mono" en el puerto en Godot --> Proyecto --> Configuración del Proyecto --> Mono --> Agente Depurador.
    • También selecciona "Esperar por el depurador" en las opciones de Godot Mono. "Este plugin Godot <https://godotengine.org/asset-library/asset/435>`_ puede ser útil.
  5. Ejecuta el juego en Godot. Debería colgarse en la pantalla de bienvenida de Godot mientras espera a que tu depurador se conecte.
  6. En Visual Studio 2019, abra su proyecto y elija Extensiones --> Mono --> Adjuntar al Depurador Mono.

Configurar el código de Visual Studio para la depuración

Para configurar el código de Visual Studio para la depuración, abre un proyecto en Godot. Haz clic en "Project" y abre la configuración del proyecto. Desplázate hacia abajo y haz clic en "Debugger Agent" en la categoría Mono. Luego activa el ajuste "Wait for debugger". A continuación, copia el número de puerto y abre el código de Visual Studio.

Necesitas descargar la extensión "Mono Debug" de Microsoft. Luego abre la carpeta del proyecto Godot. Ve a la pestaña de ejecución y haz clic en crear un archivo llamado "launch.json". Selecciona C# Mono en el menú desplegable. Cuando el archivo "launch.json" se abra automáticamente, cambia el número de puerto al número que has copiado anteriormente y guarda el archivo. En la pestaña de ejecución, cambie la configuración de ejecución de "Launch a attach". Siempre que quieras depurar, asegúrate de que "Wait for Debugger" esté activado en Godot, ejecuta el proyecto y ejecuta el depurador en Visual Studio Code.