Editor Funciona, Build Falha: Rastreie Erros do Console para Referências de Script e Cena com Unity MCP

Threads intituladas “Unity funciona no editor, falha no dispositivo / build” parecem iguais: Play está ok, então um build para Player / dispositivo fica vermelho, trava, fica preto ou lança NullReferenceException ao entrar na cena. O motor raramente está “quebrado”—o caminho do editor escondeu lacunas de referência e plataforma: cena não está na lista de build, campos serializados que são None no disco, sensibilidade a maiúsculas/minúsculas no caminho, ou APIs UnityEditor vazadas para um assembly de runtime até o momento do empacotamento.

Este post tem três espinhas (como o título):

1. Console / stack → objetos de script e cena
2. Verificar Build Settings, Missing Script, referências serializadas
3. Diagnóstico somente leitura no Cursor via Unity MCP → correção mínima após confirmação

Sem tutorial de instalação de plugin, sem guia completo de publicação na loja. Stripping IL2CPP e plugins nativos ficam no apêndice.

Relacionados:

• Instalação do Unity MCP
• Unity MCP com Claude Code e Cursor
• Conecte um HUD do AI Studio a eventos de saúde (fiação correta; este post é “como encontrar a quebra”)

Primeiro: qual camada falhou?

A. Janela de Build vermelha (falha de compilação / empacotamento)
        ↓
B. Build bem-sucedido; dispositivo morre ou fica preto ao iniciar
        ↓
C. Jogo inicia; uma cena ou recurso explode em tempo de execução

O que você vê	Camada	Verifique primeiro aqui
Build falha, error CS… / tipo não encontrado	A	Assembly de runtime referenciando UnityEditor, #if ruim, asmdef
NRE / MissingReference na cena inicial	B/C	Cena na lista de build, Missing Script, None no Inspector
Falha apenas em Resources.Load / cena aditiva	C	Maiúsculas/minúsculas no caminho, asset no pacote, cena realmente carregada

O Unity MCP é mais forte em um editor aberto: Console, Hierarchy, campos de componentes. Stacks de logcat / Xcode do dispositivo devem ser colados no Cursor—ou envie um Development Build e reproduza com a mesma cena inicial no Editor quando possível.

Loop de solução de problemas (manual + MCP)

Não pule a passada manual e peça para a IA reescrever o Player.

Passo 0: Congele a cena manualmente (~2 min)

Antes do Cursor:

1. Anote a versão do Unity e o alvo (ex.: Android / IL2CPP)
2. Limpe Window → General → Console, depois Build ou Development Build uma vez
3. Copie o primeiro Erro relevante (com stack)—não uma parede de Avisos
4. Abra File → Build Settings: a cena suspeita está marcada? O índice 0 é a cena inicial?
5. Se você editou uma instância de Prefab: você Aplicou? Overrides não aplicados muitas vezes nunca chegam ao asset em disco que você pensa que enviou

Passo 1: Triagem somente leitura do Console com MCP

Resuma os Erros do Console relacionados a este build / último Play (ignore Info).
Classifique como compilação / Missing Script / NullReference / carregamento de recurso.
Liste caminho do script, linha, nome do GameObject por erro quando presente.
Não modifique nenhum asset.

Passo 2: “Trio de referência” manual + MCP

Para NREs em tempo de execução (B/C), selecione o objeto do stack no editor e verifique com MCP:

Manual	Prompt MCP
Lista de Build Settings (screenshot ou ditado)	“Liste caminhos de cena do Build Settings e flags habilitadas; nomeie a cena inicial.”
Inspector: Missing Script / refs None	”Na cena <Nome>, liste Missing Scripts; verifique campos serializados em <Objeto>.<Componente> para None. Apenas tabela. Não edite.”
Asset Prefab vs instância de cena	”<X> é um asset Prefab ou instância de cena? Há overrides não aplicados se visíveis? Apenas relate.”

Regra: Pacotes usam cenas/Prefabs em disco. Preenchimentos temporários OnValidate que “parecem ok” no Editor não contam—confie nos valores serializados do MCP/Inspector.

Passo 3: Modelo de diagnóstico, depois confirme

[Restrições]
- Diagnostique e proponha um plano mínimo; aguarde meu OK antes de editar
- Não finja uma correção com GameObject.Find em massa
- Toque apenas em scripts/Prefabs/cenas ligados a este Erro

[Cena]
- Play no Editor: OK / quebrado (verdadeiro)
- Plataforma / build: …
- Cena inicial do Build Settings: …
- Stack do Console / dispositivo (bruto):
<cole>

[Resposta]
1. Camada A / B / C
2. Top 1–2 causas raiz (não está no build / ref None / Missing Script / maiúsculas / API Editor…)
3. Objetos e nomes de campos que devo verificar
4. Passos de correção mínima (ainda não execute)

Passo 4: Escrita mínima + recheck

Aplique a correção mínima confirmada: apenas <objeto.campo> ou as poucas linhas em <caminho do script> para este Erro.
Salve a cena/Prefab.
Depois recheck somente leitura: campos ainda None? Mesmo Erro ainda no Console?

Exemplo prático: stack → campo

Log de Player/dispositivo sintético mas realista (troque caminhos pelo seu projeto).

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

Camada

• Chegou ao Update → não é A (compilação ok)
• Morre ao tomar dano → C (runtime); suspeite de refs de UI, não “reescreva o combate”

Manual

1. A cena do HUD está no Build Settings?
2. Selecione o objeto HudHealthView; healthFill / playerHealth estão None?
3. Edições de Prefab: Aplicadas?

MCP

Somente leitura: abra a cena que contém o HUD.
1. Encontre objetos com HudHealthView
2. Relate se healthFill, playerHealth (e pares) estão None / Missing
3. Não edite
Se None: plano mínimo é reatribuir refs e salvar—não mudar TakeDamage.

Correção mínima (após OK)

• Arraste a Image HUD_HealthFill → healthFill; PlayerHealth do Player → playerHealth
• Salve; Development Build; tome dano novamente

”Correção” ruim (não faça)

// Anti-padrão: Find esconde None—ainda quebra em renomeação / carga aditiva
healthFill = GameObject.Find("HUD_HealthFill").GetComponent<Image>();

Fiação correta: HUD → eventos de saúde. Aqui: fixe o campo a partir do stack, depois religue.

Matriz de sintomas (espinha)

Sintoma 1: Build vermelho—tipo não encontrado / UnityEditor

Causa provável	Manual	MCP
Script de runtime usa API do Editor	O arquivo está fora de Editor/?	”Pesquise UnityEditor. fora de pastas Editor; liste apenas caminhos.”
#if invertido, tipos ausentes no Player	Verifique se UNITY_EDITOR envolve	”Quais tipos existem sob Editor vs Player para este arquivo?”
Lacuna de asmdef	Abra o .asmdef com falha	”Liste refs do asmdef; qual está faltando?”

Anti-padrão (API do Editor em assembly de runtime → build do Player falha):

using UnityEngine;
using UnityEditor; // Falha no build se não for assembly Editor

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

Correção A: arquivo inteiro sob Editor/

Assets/Scripts/Editor/BakeTools.cs   ← compilação somente editor

Correção B: isolar no arquivo (apenas se precisar compartilhar o arquivo)

using UnityEngine;

public class RuntimeSafe : MonoBehaviour
{
    public void DoGameplay() { /* visível ao Player */ }

#if UNITY_EDITOR
    [ContextMenu("Debug/Fill Refs")]
    void EditorOnlyFill()
    {
        // Somente editor—não trate como dados de runtime empacotados a partir do Awake
    }
#endif
}

Ainda mais limpo: scripts somente editor + asmdef para que assemblies de runtime nunca arrastem refs do Editor.

Sintoma 2: NRE no dispositivo ao entrar na cena; Play no Editor “parece ok”

Verifique em ordem—sem mega-reescrita paralela:

1. Cena não está no Build Settings ou cena inicial errada
2. Missing Script / None serializado (incluindo Prefab não aplicado)
3. Cena aditiva não carregada antes de Find / acesso
4. Maiúsculas/minúsculas no caminho Resources.Load (Editor macOS geralmente insensível a maiúsculas; Android não é)

1. Relate cenas do Build Settings, flags habilitadas, índice inicial
2. Liste todos os Missing Scripts na cena <X>
3. Verifique refs públicas em GameManager / Player / HUD ao longo do caminho de inicialização para None
Relate apenas; não edite.

No Editor	No pacote	Causa típica
Refs parecem definidas	None em runtime	Overrides de instância não aplicados; arquivo de cena errado editado
Find funciona	Null no dispositivo	Objeto em cena não carregada; nome incompatível
Resources.Load funciona	Null no dispositivo	Maiúsculas/minúsculas no caminho; asset não está sob Resources/

// Em disco: Assets/Resources/UI/HealthBar.png
// Frequentemente falha no Android (incompatibilidade de maiúsculas):
Resources.Load<Sprite>("ui/healthbar");
// Corresponda ao caminho sob Resources, ex.:
Resources.Load<Sprite>("UI/HealthBar");

Pesquise strings de caminho em Resources.Load / Addressables.LoadAssetAsync;
monte uma tabela sensível a maiúsculas vs caminhos relativos reais. Não edite código ainda.

Sintoma 3: Console inundado com Missing Script

Escaneie a cena <X> e o Prefab <caminho>:
Liste caminhos de GameObject com Missing Script.
Por item: sugira religar o script original ou remover o componente vazio (a partir do nome/GUID restante se visível).
Não exclua em massa automaticamente.

Manual: confirme que o arquivo de script ainda existe e que asmdef/GUID não quebrou; confirme um a um antes de excluir vazios.

Checklist de aceitação

1. Erros correspondentes sumiram do Console
2. Play no Editor percorre o mesmo caminho com falha (entrar no nível, tomar dano, abrir UI…)
3. Um Development Build para o alvo (ou Player local)
4. Recheck somente leitura do MCP: campos suspeitos não estão mais None / Missing
5. Diff do Git é apenas a pequena mudança esperada de cena/Prefab/script—sem refatoração de passagem

Recheck somente leitura: algum None ou Missing Script em <lista de objetos>? Liste exceções. Não edite.

Linhas vermelhas de prompt

Não faça	Faça
”Apenas faça o Play funcionar”	Camada A/B/C + fixe o campo a partir do stack
Find em massa em vez de refs	Corrija campos serializados ou injeção explícita
Reordenar Build Settings sem pedir	Relate a lista atual e a cena inicial primeiro
”Há um NRE”	Cole as primeiras 20–40 linhas do stack

Limites do produto

• Unity MCP: Console do editor, Hierarchy, scripts, refs—espinha deste artigo.
• AI Studio: estrutura de UI no motor; religue após reexportar conforme o post de fiação—não faça Find de UI a partir da jogabilidade.
• Certificados, lojas, ROMs OEM: cole o texto do log no Cursor para ajuda de leitura; fora do escopo de edição de cena do MCP.

Apêndice: comuns, mas fora da espinha

Elimine primeiro a espinha deste artigo:

Sintoma	Direção
Development ok, Release morre	Managed Stripping / link.xml; MCP: “Adivinhe tipos removidos a partir do stack de crash; proponha link.xml; não escreva arquivos ainda.”
Crash nativo Android (não gerenciado)	.so / permissões / Gradle; cole logcat para leitura
API Unity fora da thread principal	Verifique se callbacks assíncronos retornam à thread principal

Não misture stripping e Missing Script em uma “grande reescrita”.

Resumo

1. Editor ok / pacote quebrado → trate como refs / cenas no build / caminhos / API Editor primeiro
2. Congele manualmente Build Settings + primeiro Erro, depois triagem somente leitura com MCP
3. Stack → linha do script → campo do componente; religue ou remova componentes vazios após confirmação
4. Sem Find ou reescritas de jogabilidade como correções falsas
5. Aceite com Development Build + recheck somente leitura

Execute “congele → camada → trio de referência → fixe o campo como no exemplo” e a maioria dos bugs de ref em dispositivo encolhe para um diff pequeno e revisável.