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

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

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

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

C# support in Godot’s 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

Nota

Si está usando Visual Studio Code, asegúrese de descargar e instalar la extensión de C# <https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp>`_ para habilitar características como el resaltado de sintaxis y el autocompletado.

Nota

If you are using Visual Studio 2019, you must follow the instructions found in the «Configure VS2019 for Debugging» section below.

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.

Ten en cuenta que actualmente hay algunos problemas en los que los proyectos Godot y C# no permanecen sincronizados; si eliminas, renombras o mueves cosas como scripts o nodos, es posible que ya no coincidan. En este caso, puede ser útil editar los archivos de la solución manualmente.

Ejemplo: Si creaste un script (e.g. Test.cs) y lo borras en Godot, la compilación fallará porque se espera que el archivo que falta aún se encuentre en el proyecto CS. Para corregir, simplemente abre el .csproj y busca el ItemGroup, debería haber una línea incluida como la siguiente:

<ItemGroup>
    <Compile Include="Test.cs" />
    <Compile Include="AnotherTest.cs" />
</ItemGroup>

Simplemente elimina esa línea y tu proyecto debería volver a compilarse correctamente. Lo mismo para renombrar y mover cosas, simplemente renómbralas y muévelas en el archivo del proyecto si es necesario.

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

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»

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 con la API de 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.

  • Como se explicó anteriormente, el proyecto C# no siempre se mantiene sincronizado automáticamente cuando las cosas son borradas, renombradas o movidas en Godot (#12917).
  • 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.
  • La exportación de proyectos Mono sólo es compatible con plataformas de escritorio (Linux, Windows y macOS). Android, iOS, HTML5 y UWP no son compatibles actualmente (#20267, #20268 #20270 #20271).
  • 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.
  • 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.

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

By default, tools like NuGet put Version as an attribute of the `PackageReference` Node. You must manually create a Version node as shown above. This is because the version of MSBuild used requires this. (This will be fixed in Godot 4.0.)

Whenever packages are added or modified, run nuget restore (not dotnet restore) in the root of the project directory. To ensure that NuGet packages will be available for msbuild to use, run:

msbuild /t:restore

Profiling your C# code

Configuring VS 2019 for debugging

Nota

Godot has built-in support for workflows involving several popular C# IDEs. Built-in support for Visual Studio will be including in future versions, but in the meantime, the steps below can let you configure VS 2019 for use with Godot C# projects.

  1. Install VS 2019 with .NET desktop development and Desktop development with C++ workloads selected.
  2. Ensure that you do not have Xamarin installed. Do not choose the Mobile development with .NET workload. Xamarin changes the DLLs used by MonoDebugger, which breaks debugging.
  3. Install the VSMonoDebugger extension.
  4. In VS 2019 –> Extensions –> Mono –> Settings:
    • Select Debug/Deploy to local Windows.
    • Leave Local Deploy Path blank.
    • Set the Mono Debug Port to the port in Godot –> Project –> Project Settings –> Mono –> Debugger Agent.
    • Also select Wait for Debugger in the Godot Mono options. This Godot Addon may be helpful.
  5. Run the game in Godot. It should hang at the Godot splash screen while it waits for your debugger to attach.
  6. In VS 2019, open your project and choose Extensions –> Mono –> Attach to Mono Debugger.