Este artículo proporciona una guía detallada para configurar un entorno de desarrollo C# compatible con Godot 4.3.2, .NET 6.0.302 y VSCode 1.89.1. Se enfoca en la alineación de versiones y configuraciones entre estas tres herramientas para asegurar una experiencia de desarrollo fluida, especialmente para aquellos que migran desde Unity.

La configuración del entorno C# en Godot 4.x difiere significativamente de Unity. Godot utiliza un enfoque de ejecución administrada independiente, integración personalizada de MSBuild y reescritura de IL a nivel de motor. Esto implica que el archivo .csproj, aunque parezca un proyecto .NET estándar, está intrínsecamente ligado a la cadena de compilación de Godot, la capa de puente del tiempo de ejecución de Mono y una lógica de localización de ensamblados diseñada para la recarga en caliente del código.

La compatibilidad entre VSCode, .NET SDK y el editor Godot requiere una alineación precisa:

• El OmniSharp de VSCode debe ser capaz de interpretar los archivos .csproj generados por Godot.
• El editor Godot debe reconocer las sesiones de depuración iniciadas por VSCode.
• La versión del .NET SDK debe ser compatible con el ABI del tiempo de ejecución Mono integrado en Godot.

La falta de alineación en cualquiera de estos puntos puede provocar errores comunes como: "No se puede encontrar el tipo o el nombre del espacio de nombres 'Godot'", "Error al iniciar el depurador: No se puede encontrar el adaptador de depuración para 'godot-csharp'", o "MSB4018: La tarea 'GenerateGodotSharpSolution' falló inesperadamente".

Este documento no es un tutorial de instalación, sino una guía para asegurar que VSCode, .NET SDK y el editor Godot estén sincronizados. Se dirige tanto a desarrolladores C# experimentados que se adaptan a Godot 4.0, como a principiantes que buscan una ruta de solución de problemas clara y verificable.

2. Confirmación de la Línea Base del Entorno: Bloqueo de Versiones y Restricciones de Compatibilidad

---

Muchos problemas surgen al omitir la verificación de la línea base. Godot 4.0.x tiene requisitos de versión específicos para el ecosistema .NET. A diferencia del desarrollo web, la compatibilidad aquí es estricta.

La siguiente tabla muestra la combinación de versiones mínima y estable probada para el flujo completo (creación de proyecto, compilación, depruación, recarga en caliente):

Componente	Versión Recomendada	Razón de la Versión Requerida	Riesgos de Sustitución
Editor Godot	4.3.2 Stable	Este es el primer lanzamiento que actualiza GodotSharp a la versión 4.3.2, resolviendo conflictos de versión de System.Text.Json que causaban fallos en AssemblyResolve en versiones anteriores. El tiempo de ejecución Mono integrado es totalmente compatible con .NET 6.0.302.	Las versiones 4.3.0/4.3.1 pueden experimentar bloqueos esporádicos debido a AccessViolationException. Las versiones 4.2.2 y anteriores no reconocen el protocolo de depuración v2 de VSCode.
.NET SDK	6.0.302 (LTS)	Godot 4.3+ soporta oficialmente solo .NET 6 LTS. La versión 6.0.302 es la última que incluye un parche para la resolución del TargetFrameworkMoniker en compilaciones multi-target. La versión 6.0.300 puede causar reintentos infinitos en la tarea GenerateGodotSharpSolution.	El uso de .NET 7.0.202 puede provocar "No se pudo cargar el archivo o ensamblado 'System.Runtime, Version=7.0.0.0'". .NET 8.0 generalmente rechaza la carga de GodotSharp.dll.
VSCode	1.89.1	Esta es la última versión estable que incluye por defecto OmniSharp v1.37.17, la cual es la primera versión compatible con el SdkResolver de Microsoft.NET.Sdk.Godot. Las versiones posteriores (1.90+) cambian a OmniSharp v1.38.x, cuya lógica de resolución de SDK puede interpretar incorrectamente <targetframework>net6.0</targetframework> como net6.0-windows.	Las versiones 1.90.0 y superiores requieren la degradación manual de OmniSharp o la modificación de omnisharp.json para evitar la pérdida del autocompletado y la sugerencia de tipos para Godot..

Nota: No intente usar versiones más recientes de .NET SDK (como .NET 8) con el pretexto de "más características". Godot 4.x no es un simple consumidor del ecosistema .NET; adapta el SDK de MSBuild a través de su propio Microsoft.NET.Sdk.Godot. Su versión del .NET SDK debe coincidir exactamente con la esperada por Godot.

Verifique su configuración con los siguientes comandos:

# 1. Comprobar versión de Godot (Editor: Help -> About)
godot --version

# 2. Comprobar versión de .NET SDK (Debería mostrar solo 6.0.302)
dotnet --list-sdks

# 3. Comprobar versión de VSCode (Editor: Help -> About)
code --version

Si las versiones no coinciden, se recomienda desinstalar todas las versiones de .NET SDK, descargar e instalar la versión 6.0.302, obtener la versión 4.3.2 Stable de Godot (la versión Standard, no la Mono), y descargar la versión 1.89.1 de VSCode.

Nota para Windows: Asegúrese de que el registro de Windows (HKEY_LOCAL_MACHINE\SOFTWARE\dotnet\Setup\InstalledVersions\x64\Sdk\Version) apunte a 6.0.302. Si no es así, modifíquelo manualmente o utilice dotnet-install.ps1 para una instalación limpia que actualice el registro.

3. Configuración Profunda de VSCode: OmniSharp como Intérprete

---

La instalación del plugin C# Dev Kit no es suficiente. OmniSharp, el proceso subyacente que interpreta los archivos .csproj y proporciona inteligencia de código, debe ser configurado para reconocer el SDK personalizado de Godot (Microsoft.NET.Sdk.Godot).

3.1 Mecanismo de Carga del Godot SDK Resolver de OmniSharp

Microsoft.NET.Sdk.Godot no es un paquete NuGet, sino un conjunto de archivos .targets y .props dentro de la instalación de Godot. Para que OmniSharp lo cargue correctamente:

• La versión de OmniSharp debe ser v1.37.17 o superior (incluida en VSCode 1.89.1).
• OmniSharp debe poder localizar la ruta de instalación de Godot, donde se encuentran los archivos del SDK.

OmniSharp no escanea automáticamente el directorio de Godot. Por lo tanto, debe configurarse manualmente.

3.2 Creación de omnisharp.json: Primera Cláusula del Contrato

Cree un archivo omnisharp.json en el directorio de configuración de usuario de VSCode (no en el directorio del proyecto):

• Windows: %USERPROFILE%\AppData\Roaming\Code\User\omnisharp.json
• macOS: $HOME/Library/Application Support/Code/User/omnisharp.json
• Linux: $HOME/.config/Code/User/omnisharp.json

Contenido del archivo (reemplace YOUR_GODOT_PATH con la ruta absoluta a su instalación de Godot 4.3.2):

{
  "sdkPath": "/usr/share/dotnet/sdk/6.0.302",
  "roslynExtensionsPaths": [
    "/path/to/your/godot/GodotSharp/Tools"
  ],
  "projectLoadTimeout": 120,
  "useModernNet": true,
  "enableRoslynAnalyzers": true,
  "enableEditorConfigSupport": true,
  "enableImportCompletion": true,
  "showReferencesCodeLens": true,
  "maxProjectResults": 1000,
  "testFrameworks": {
    "xunit": "xunit.runner.visualstudio",
    "nunit": "NUnit3TestAdapter",
    "mstest": "MSTest.TestAdapter"
  }
}

• sdkPath: Debe apuntar exactamente al directorio raíz del SDK 6.0.302.
• roslynExtensionsPaths: Crucial. Indica a OmniSharp que cargue los archivos .targets y .props de Godot ubicados en GodotSharp/Tools.
• projectLoadTimeout: Aumentado a 120 segundos para permitir la carga completa de los metadatos de Godot.

Reinicie VSCode después de crear este archivo. El icono de OmniSharp debería volverse azul y mostrar "Ready". La escritura de GD. debería ahora activar el autocompletado.

3.3 Interruptor Oculto en C# Dev Kit: Clave para el Protocolo de Depuración

El plugin C# Dev Kit tiene un depurador específico para Godot desactivado por defecto. Para activarlo, añada lo siguiente a su archivo settings.json de VSCode (Ctrl+Shift+P o Cmd+Shift+P -> Preferences: Open Settings (JSON)):

{
  "csharp.debugging.enabled": true,
  "csharp.debugging.godotEnabled": true,
  "csharp.debugging.godotPath": "/path/to/your/godot/godot"
}

• csharp.debugging.godotEnabled: Activa el modo de depuración específico de Godot.
• csharp.debugging.godotPath: Debe apuntar al ejecutable de Godot (godot.exe en Windows, godot en macOS/Linux).

Es recomendable copiar el ejecutable de Godot a una ubicación global (como /usr/local/bin/ en macOS/Linux o C:\Windows\ en Windows) y usar esa ruta aquí para mayor consistencia.

4. Configuración del Editor Godot: Hacer que el Motor "Reconozca" la Sesión de Depuración de VSCode

---

Incluso con VSCode configurado, el editor Godot necesita ser instruido para actuar como un socio de depuración.

4.1 Habilitar el Modo de "Depuración Externa" en Godot

Cree un archivo .godot/editor_settings.cfg en la raíz de su proyecto Godot:

[debug]
remote_debug_port=5005
remote_debug_enabled=true
remote_debug_host="127.0.0.1"

• remote_debug_port: Debe coincidir con el puerto que escucha el depurador de VSCode (5005 por defecto).
• remote_debug_enabled: Habilita la funcionalidad de depuración remota.
• remote_debug_host: Restringe las conexiones a la máquina local.

Importante: Añada el directorio .godot/ y el archivo editor_settings.cfg a su control de versiones (Git).

4.2 Configurar el Botón "Run" del Editor Godot

Vaya a Editor -> Editor Settings -> Run -> Executables. Marque Run in Terminal y configure Run in Terminal Arguments como:

--debug --breakpoints --remote-debug 127.0.0.1:5005

• --debug: Habilita el modo de depuración en Godot.
• --breakpoints: Permite el uso de puntos de interrupción en C#.
• --remote-debug: Indica a Godot que se conecte al servicio de depuración de VSCode en el puerto especificado.

Nota: Esta es una configuración global del editor. Para un control más preciso, se recomienda iniciar la depuración desde VSCode.

4.3 launch.json de VSCode: El Contrato Final de la Sesión de Depuración

Cree el archivo .vscode/launch.json en la raíz de su proyecto:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Godot C# Debug",
      "type": "godot-csharp",
      "request": "launch",
      "mode": "gdscript",
      "projectPath": "${workspaceFolder}",
      "godotPath": "/path/to/your/godot/godot",
      "port": 5005,
      "preLaunchTask": "build"
    }
  ]
}

• type: Debe ser godot-csharp.
• godotPath: Debe coincidir con la ruta en settings.json.
• port: Debe coincidir con remote_debug_port en editor_settings.cfg.
• preLaunchTask: Define una tarea que se ejecuta antes de iniciar la depuración.

4.4 tasks.json: Definiendo la Tarea "Build"

Para evitar problemas con dotnet restore y fuentes de NuGet, se recomienda usar el propio sistema de compilación de Godot. Cree el archivo .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "type": "shell",
      "command": "\"/path/to/your/godot/godot\" --headless --export \"Linux/X11\" /dev/null",
      "presentation": {
        "reveal": "silent",
        "panel": "shared",
        "showReuseMessage": true,
        "clear": true
      },
      "problemMatcher": []
    }
  ]
}

• command: Utiliza el ejecutable de Godot para activar un proceso de exportación, que internamente ejecuta dotnet restore y dotnet build. Esto asegura la compatibilidad de la compilación con el entorno de Godot.

Al presionar F5 en VSCode, se ejecutará la tarea "build" y luego se iniciará la sesión de depuración, conectándose al editor Godot.

5. Solución de Problemas Comunes

---

5.1 Error: The type or namespace name 'Godot' could not be found

1. Estado de OmniSharp: Verifique si el icono de OmniSharp está activo. Si no, revise omnisharp.json y la ruta roslynExtensionsPaths.
2. Archivo .csproj: Asegúrese de que el SDK sea Microsoft.NET.Sdk.Godot.
3. Paquetes GodotSharp: Ejecute dotnet list package. Si faltan, ejecute el comando de exportación headless de Godot y vuelva a verificar.
4. Verificación con ildasm: Use ildasm para desensamblar su DLL y confirmar la presencia de referencias a Godot.

5.2 Error: Failed to launch debugger: Could not find debug adapter for 'godot-csharp'

1. Plugin C# Dev Kit: Verifique que esté instalado y habilitado (versión ≥ 1.29.0).
2. launch.json: Confirme que "type": "godot-csharp".
3. Permisos del Ejecutable: Asegúrese de que el ejecutable de Godot tenga permisos de ejecución (macOS/Linux).
4. Puerto: Verifique que el puerto 5005 no esté en uso. Si lo está, cámbielo en editor_settings.cfg y launch.json.

5.3 Error: MSB4018: The "GenerateGodotSharpSolution" task failed unexpectedly

1. Versión de .NET SDK: Debe ser 6.0.302.
2. project.godot: Asegúrese de que solution_path="." esté presente bajo la sección [csharp].
3. Archivos .sln: Elimine los archivos .sln y .sln.docstates existentes y regenere la solución.
4. Registro detallado: Ejecute Godot con el flag --verbose para identificar el DLL faltante.

Al seguir estos pasos, se establece un entorno de desarrollo C# robusto y alineado para Godot 4.3.2, permitiendo una depuración y desarrollo eficientes.