El Editor Funciona, la Compilación Falla: Rastrea Errores de Consola a Referencias de Scripts y Escenas con Unity MCP

Los hilos titulados “Unity funciona en el editor, falla en el dispositivo / compilación” se ven igual: Play está bien, luego una compilación para Player / dispositivo se pone en rojo, se bloquea, se queda en negro o lanza NullReferenceException al entrar en la escena. El motor rara vez está “roto”: la ruta del editor ocultó referencias y brechas de plataforma: escena no incluida en la lista de compilación, campos serializados que son None en disco, sensibilidad de mayúsculas en rutas, o APIs de UnityEditor filtradas a un ensamblado de runtime hasta el momento del empaquetado.

Esta publicación tiene tres ejes (igual que el título):

1. Consola / pila → objetos de script y escena
2. Verificar Build Settings, Missing Script, referencias serializadas
3. Diagnóstico de solo lectura en Cursor mediante Unity MCP → corrección mínima después de confirmar

Sin tutorial de instalación de plugins, sin guía completa de publicación en tienda. El stripping de IL2CPP y los plugins nativos quedan en el apéndice.

Relacionado:

• Instalación de Unity MCP
• Unity MCP con Claude Code y Cursor
• Conecta un HUD de AI Studio a eventos de salud (cableado correcto; esta publicación es “cómo encontrar la rotura”)

Primero: ¿qué capa falló?

A. Ventana de compilación en rojo (fallo de compilación / empaquetado)
        ↓
B. La compilación tiene éxito; el dispositivo muere o se queda en negro al iniciar
        ↓
C. El juego arranca; una escena o característica explota en tiempo de ejecución

Lo que ves	Capa	Revisa primero aquí
La compilación falla, error CS… / tipo no encontrado	A	Ensamblado de runtime que referencia UnityEditor, #if incorrecto, asmdef
NRE / MissingReference en la escena de arranque	B/C	Escena en la lista de compilación, Missing Script, None en el Inspector
Solo falla en Resources.Load / escena aditiva	C	Mayúsculas en la ruta, asset en el paquete, escena realmente cargada

Unity MCP es más fuerte en un editor abierto: Consola, Jerarquía, campos de componentes. Las pilas de logcat / Xcode del dispositivo deben pegarse en Cursor—o envía una Development Build y reproduce con la misma escena de arranque en el Editor cuando puedas.

Bucle de solución de problemas (manual + MCP)

No omitas el pase manual y pidas a la IA que reescriba el Player.

Paso 0: Congela la escena a mano (~2 min)

Antes de Cursor:

1. Anota la versión de Unity y el objetivo (ej. Android / IL2CPP)
2. Limpia Window → General → Console, luego compila o haz una Development Build una vez
3. Copia el primer Error relevante (con pila)—no un muro de advertencias
4. Abre File → Build Settings: ¿está marcada la escena sospechosa? ¿Es el índice 0 la escena de arranque?
5. Si editaste una instancia de Prefab: ¿hiciste Apply? Los overrides no aplicados a menudo nunca llegan al asset en disco que crees que enviaste

Paso 1: Triage de Consola de solo lectura con MCP

Resume los Errores de Consola relacionados con esta compilación / último Play (ignora Info).
Clasifícalos como compilación / Missing Script / NullReference / carga de recursos.
Enumera la ruta del script, la línea, el nombre del GameObject por error cuando esté presente.
No modifiques ningún asset.

Paso 2: “Trío de referencias” manual + MCP

Para NREs en runtime (B/C), selecciona el objeto de la pila en el editor y verifica con MCP:

Manual	Prompt de MCP
Lista de Build Settings (captura o dictado)	“Enumera las rutas de escenas de Build Settings y los indicadores habilitados; nombra la escena de arranque.”
Inspector: Missing Script / refs None	”En la escena <Nombre>, enumera Missing Scripts; verifica los campos serializados en <Objeto>.<Componente> para None. Solo tabla. No edites.”
Asset de Prefab vs instancia de escena	”¿Es <X> un asset de Prefab o una instancia de escena? ¿Hay overrides no aplicados si son visibles? Solo informa.”

Regla: Los paquetes usan escenas/Prefabs en disco. Los OnValidate temporales que “se ven bien” en el Editor no cuentan—confía en los valores serializados de MCP/Inspector.

Paso 3: Plantilla de diagnóstico, luego confirma

[Restricciones]
- Diagnostica y propón un plan mínimo; espera mi OK antes de editar
- No finjas una corrección con GameObject.Find masivo
- Toca solo scripts/Prefabs/escenas vinculados a este Error

[Escena]
- Play en Editor: OK / roto (veraz)
- Plataforma / compilación: …
- Escena de arranque en Build Settings: …
- Pila de Consola / dispositivo (cruda):
<pega>

[Respuesta]
1. Capa A / B / C
2. 1–2 causas raíz principales (no en compilación / ref None / Missing Script / mayúsculas / API de Editor…)
3. Objetos y nombres de campo que debo verificar
4. Pasos de corrección mínima (aún no ejecutes)

Paso 4: Escritura mínima + recheck

Aplica la corrección mínima confirmada: solo <objeto.campo> o las pocas líneas en <ruta del script> para este Error.
Guarda la escena/Prefab.
Luego recheck de solo lectura: ¿los campos siguen None? ¿Sigue el mismo Error en la Consola?

Ejemplo trabajado: pila → campo

Log sintético pero realista de Player/dispositivo (cambia las rutas por las de tu proyecto).

Log

NullReferenceException: Object reference not set to an instance of an object
  at HudHealthView.HandleHealthChanged (System.Single current, System.Single max) [0x00000] in Assets/Scripts/UI/HudHealthView.cs:42
  at PlayerHealth.TakeDamage (System.Single amount) [0x00000] in Assets/Scripts/Combat/PlayerHealth.cs:28
  at DebugDealDamage.Update () [0x00000] in Assets/Scripts/Debug/DebugDealDamage.cs:15

Capa

• Llegó a Update → no es A (compilación OK)
• Muere al recibir daño → C (runtime); sospecha refs de UI, no “reescribir combate”

Manual

1. ¿Está la escena del HUD en Build Settings?
2. Selecciona el objeto HudHealthView; ¿están healthFill / playerHealth None?
3. Ediciones de Prefab: ¿Aplicadas?

MCP

Solo lectura: abre la escena que contiene el HUD.
1. Encuentra objetos con HudHealthView
2. Informa si healthFill, playerHealth (y similares) están None / Missing
3. No edites
Si están None: el plan mínimo es reasignar refs y guardar—no cambiar TakeDamage.

Corrección mínima (después del OK)

• Arrastra la Imagen HUD_HealthFill → healthFill; el PlayerHealth del Player → playerHealth
• Guarda; Development Build; recibe daño de nuevo

”Corrección” mala (no hacer)

// Anti-patrón: Find oculta None — sigue rompiendo al renombrar / carga aditiva
healthFill = GameObject.Find("HUD_HealthFill").GetComponent<Image>();

Cableado correcto: HUD → eventos de salud. Aquí: fija el campo desde la pila, luego re-vincula.

Matriz de síntomas (eje)

Síntoma 1: Compilación en rojo — tipo no encontrado / UnityEditor

Causa probable	Manual	MCP
Script de runtime usa API de Editor	¿Está el archivo fuera de Editor/?	”Busca UnityEditor. fuera de carpetas Editor; enumera solo rutas.”
#if invertido, tipos faltantes en Player	Verifica que UNITY_EDITOR envuelva	”¿Qué tipos existen bajo Editor vs Player para este archivo?”
Brecha de asmdef	Abre el .asmdef que falla	”Enumera refs de asmdef; ¿cuál falta?”

Anti-patrón (API de Editor en ensamblado de runtime → falla la compilación de Player):

using UnityEngine;
using UnityEditor; // Falla la compilación si no es un ensamblado Editor

public class BadBake : MonoBehaviour
{
    [MenuItem("Tools/Bad")] // dependencia adicional de UnityEditor
    static void Run() { }
}

Corrección A: archivo completo bajo Editor/

Assets/Scripts/Editor/BakeTools.cs   ← compilación solo Editor

Corrección B: aislar en el archivo (solo si debes compartir un archivo)

using UnityEngine;

public class RuntimeSafe : MonoBehaviour
{
    public void DoGameplay() { /* visible para Player */ }

#if UNITY_EDITOR
    [ContextMenu("Debug/Fill Refs")]
    void EditorOnlyFill()
    {
        // Solo Editor — no trates esto como datos de runtime empaquetados desde Awake
    }
#endif
}

Aún más limpio: scripts solo Editor + asmdef para que los ensamblados de runtime nunca arrastren refs de Editor.

Síntoma 2: NRE en dispositivo al entrar en escena; Play en Editor “parece bien”

Verifica en orden—sin mega-reescritura en paralelo:

1. Escena no en Build Settings o escena de arranque incorrecta
2. Missing Script / None serializado (incluyendo Prefab no aplicado)
3. Escena aditiva no cargada antes de Find / acceso
4. Mayúsculas en ruta de Resources.Load (el Editor de macOS a menudo no distingue mayúsculas; Android no)

1. Informa escenas de Build Settings, indicadores habilitados, índice de arranque
2. Enumera todos los Missing Scripts en la escena <X>
3. Verifica refs públicas en GameManager / Player / HUD a lo largo de la ruta de arranque para None
Solo informa; no edites.

En Editor	En paquete	Causa típica
Las refs se ven establecidas	None en runtime	Overrides de instancia no aplicados; archivo de escena incorrecto editado
Find funciona	Null en dispositivo	Objeto en escena no cargada; nombre incorrecto
Resources.Load funciona	Null en dispositivo	Mayúsculas en ruta; asset no bajo Resources/

// En disco: Assets/Resources/UI/HealthBar.png
// A menudo falla en Android (mayúsculas incorrectas):
Resources.Load<Sprite>("ui/healthbar");
// Coincide con la ruta bajo Resources, ej.:
Resources.Load<Sprite>("UI/HealthBar");

Busca cadenas de ruta en Resources.Load / Addressables.LoadAssetAsync;
construye una tabla sensible a mayúsculas vs rutas relativas reales. No edites código aún.

Síntoma 3: Consola inundada con Missing Script

Escanea la escena <X> y el Prefab <ruta>:
Enumera rutas de GameObject con Missing Script.
Por elemento: sugiere volver a adjuntar el script original o eliminar el componente vacío (del nombre/GUID sobrante si es visible).
No elimines en masa automáticamente.

Manual: confirma que el archivo de script aún existe y que asmdef/GUID no se rompió; confirma uno por uno antes de eliminar vacíos.

Lista de verificación de aceptación

1. Los Errores coincidentes desaparecen de la Consola
2. Play en Editor recorre la misma ruta que falla (entrar al nivel, recibir daño, abrir UI…)
3. Una Development Build al objetivo (o Player local)
4. Recheck de solo lectura con MCP: los campos sospechosos ya no están None / Missing
5. El diff de Git es solo el pequeño cambio esperado de escena/Prefab/script—sin refactor de paso

Recheck de solo lectura: ¿algún None o Missing Script en <lista de objetos>? Enumera excepciones. No edites.

Líneas rojas de prompts

No hacer	Hacer
”Solo haz que Play funcione”	Capa A/B/C + fija el campo desde la pila
Find masivo en lugar de refs	Corrige campos serializados o inyección explícita
Reordenar Build Settings sin que se pida	Informa la lista actual y la escena de arranque primero
”Hay un NRE”	Pega las primeras 20–40 líneas de pila

Límites del producto

• Unity MCP: Consola del editor, Jerarquía, scripts, refs—el eje de este artículo.
• AI Studio: estructura de UI en el motor; re-vincula después de re-exportar según la publicación de cableado—no busques UI desde el gameplay.
• Certificados, tiendas, ROMs de OEM: pega el texto del log en Cursor para ayuda de lectura; fuera del ámbito de edición de escenas de MCP.

Apéndice: común pero fuera del eje

Descarta primero el eje de este artículo:

Síntoma	Dirección
Development OK, Release muere	Managed Stripping / link.xml; MCP: “Adivina tipos eliminados de la pila de crash; propón link.xml; no escribas archivos aún.”
Crash nativo de Android (no administrado)	.so / permisos / Gradle; pega logcat para lectura
API de Unity fuera del hilo principal	Verifica que los callbacks asíncronos regresen al hilo principal

No combines stripping y Missing Script en una “gran reescritura”.

Resumen

1. Editor OK / paquete roto → trata refs / escenas en compilación / rutas / API de Editor primero
2. Congela manualmente Build Settings + primer Error, luego triage de solo lectura con MCP
3. Pila → línea de script → campo de componente; re-vincula o elimina componentes vacíos después de confirmar
4. Sin Find ni reescrituras de gameplay como correcciones falsas
5. Acepta con Development Build + recheck de solo lectura

Ejecuta “congela → capa → trío de referencias → fija el campo como en el ejemplo” y la mayoría de los bugs de refs en dispositivo se reducen a un diff pequeño y revisable.