Unity Não Entra no Play Mode: Erros de Compilação

Quando você aperta Play e a Unity mostra "All compiler errors have to be fixed before you can enter playmode!", existe pelo menos um script no projeto que não compila, e o jogo não roda até ele ser corrigido. A saída é sempre a mesma: abrir o Console, achar o primeiro erro real (não o 47º), entender a mensagem e corrigir. Este guia mostra como fazer essa leitura rápido, os seis erros que mais travam iniciante, como isolar um asset baixado que quebrou o projeto e como resolver o "Can't add script", que tem a mesma raiz.

Por que a Unity não entra no Play Mode

A Unity compila todos os scripts C# do projeto juntos, em assemblies. Se um único arquivo tem erro, aquele assembly inteiro não gera código novo, e a Unity não tem o que executar. Por isso ela bloqueia o Play Mode e mostra o aviso na Scene View e na Game View.

Dois detalhes que ajudam a não perder tempo:

• Só erro vermelho bloqueia. Avisos amarelos (warnings), como API obsoleta ou variável não usada, não impedem o Play. Leia depois, mas não são a causa.
• O erro pode estar num script que você nem abriu. Um asset importado, um pacote atualizado ou um arquivo que veio de um git pull entram na mesma compilação.

Lendo o Console: o primeiro erro é o que importa

Abra Window > General > Console. A barra do Console tem o botão Clear, que limpa mensagens do seu código mas mantém os erros de compilação (eles só somem quando o código for corrigido), e os contadores de erro, aviso e log à direita. Clique no contador de avisos para escondê-los e ficar só com os erros.

Cada erro de compilação tem este formato:

Assets/Scripts/Player.cs(23,10): error CS1002: ; expected

Arquivo, linha e coluna entre parênteses, código do erro e a descrição. Dois cliques abrem o arquivo na linha certa.

A regra que resolve metade dos casos: corrija o primeiro erro, salve e espere recompilar. Um ponto e vírgula faltando ou uma chave sem par faz o compilador se perder e acusar as linhas seguintes. Você corrige uma linha e 20 erros desaparecem.

Se a lista estiver bagunçada, desligue o Collapse para ver a ordem real e procure o erro com o caminho de arquivo que você mexeu por último.

Os erros de compilação mais comuns

1. CS1002: ; expected. Faltou ponto e vírgula no fim da instrução. O compilador às vezes aponta a linha seguinte, então olhe também a anterior.

2. CS1513: } expected. Chave aberta sem fechar. Use a formatação automática da IDE (no Visual Studio, Ctrl+K, Ctrl+D) e veja onde a indentação desanda.

3. CS0246 e CS0103: nome não encontrado. Um tipo ou nome que o compilador não acha: using faltando, pacote não instalado, erro de digitação. Esse tem um guia inteiro só dele, o do erro CS0246 na Unity, com a tabela de using dos tipos mais comuns e o caso do Cinemachine 3.

4. CS1061: 'X' does not contain a definition for 'Y'. O tipo existe, o membro não. Acontece muito com código de tutorial antigo no Unity 6, quando um pacote atualizado removeu ou renomeou membros (o Cinemachine 3 é o exemplo clássico), ou com erro de digitação no nome do método. Não confunda com API apenas obsoleta, como Rigidbody2D.velocity (o nome atual é linearVelocity) e FindObjectOfType (substituído por FindFirstObjectByType e FindAnyObjectByType): essas geram aviso amarelo CS0618 e não bloqueiam o Play, mas vale trocar logo. Leia a documentação do tipo na sua versão.

5. CS0266 ou CS0029: conversão implícita. Cannot implicitly convert type 'float' to 'int'. Você tentou guardar um float num int. Decida o que quer: Mathf.RoundToInt(valor), Mathf.FloorToInt(valor) ou mudar o tipo da variável.

6. CS0101: The namespace '<global namespace>' already contains a definition for 'Player'. Duas classes com o mesmo nome. Acontece quando você duplica um script (Ctrl+D cria Player 1.cs com a mesma classe dentro) ou importa um asset que também tem uma classe Player ou GameManager. Renomeie uma delas ou coloque o código do asset num namespace.

Exemplo de arquivo com os erros 1, 5 e 4 corrigidos, PlayerMovement.cs:

using UnityEngine;
using UnityEngine.InputSystem;

public class PlayerMovement : MonoBehaviour
{
    [SerializeField] private Rigidbody2D rb;
    [SerializeField] private float speed = 5f;

    private int lastDirection = 1;
    private float horizontal;

    public int LastDirection => lastDirection;

    private void Update()
    {
        horizontal = 0f;
        if (Keyboard.current != null)
        {
            if (Keyboard.current.aKey.isPressed) horizontal -= 1f;
            if (Keyboard.current.dKey.isPressed) horizontal += 1f;
        }

        if (horizontal != 0f)
        {
            lastDirection = Mathf.RoundToInt(Mathf.Sign(horizontal));
        }
    }

    private void FixedUpdate()
    {
        rb.linearVelocity = new Vector2(horizontal * speed, rb.linearVelocity.y);
    }
}

Resolvendo "Can't add script" e "The script class cannot be found"

Essa é a outra mensagem que aparece na mesma situação, ao arrastar um script para um GameObject:

Can't add script component 'PlayerMovement' because the script class cannot be found. Make sure that there are no compile errors and that the file name and class name match.

A própria mensagem lista as causas, e existe uma terceira:

1. Erro de compilação pendente. Se o projeto não compila, a Unity não conhece a classe nova. Resolva o Console primeiro.
2. Nome do arquivo diferente do nome da classe. O arquivo playerMovement.cs com public class PlayerMovement não serve. Maiúsculas contam. Se você renomeou o arquivo no Project, renomeie a classe também, e vice-versa.
3. Classe que não herda de MonoBehaviour. Uma classe C# comum, ou um ScriptableObject, não vira componente. A mensagem nesse caso fala que o script precisa derivar de MonoBehaviour.

O primo dessa mensagem aparece quando o arquivo some depois de o componente já estar no objeto: o Inspector mostra Missing (Mono Script) e o Console avisa que o script referenciado está faltando. Isso acontece quando você renomeia ou move o .cs fora da Unity, sem o arquivo .meta junto. Mexa em scripts sempre pelo Project da Unity, nunca pelo explorador de arquivos.

Juntar dezenas de scripts sem perder o controle do projeto é exatamente o ponto em que muita gente trava sozinha: um erro aqui, um pacote ali, e o jogo para de rodar sem você saber por quê. No curso de Unity você constrói um jogo completo com a organização de scripts e o hábito de compilar e versionar que evitam essa bola de neve.

Erro em asset ou pacote de terceiros

Se o caminho do erro começa com uma pasta que você não escreveu (Assets/AlgumAsset/... ou Packages/...), o problema veio de fora. O roteiro:

1. Confira a versão. Na página do asset, veja as versões da Unity suportadas. Asset feito para versões antigas costuma usar API removida.
2. Atualize o asset pelo Package Manager, na seção My Assets.
3. Isole o asset. Feche a Unity e renomeie a pasta do asset acrescentando um til no fim: AlgumAsset~. A Unity ignora pastas terminadas em ~, então o código delas sai da compilação. Abra o projeto: se os erros sumirem, a causa está confirmada e você decide entre corrigir, atualizar ou remover. Para devolver, tire o til.
4. Pacote do Package Manager com erro geralmente é versão incompatível com a sua Unity. Volte para a versão recomendada (a que aparece marcada no Package Manager) em vez da mais nova experimental.

Se o projeto nem abre normalmente e cai numa tela pedindo para entrar no Safe Mode, é o mesmo problema visto da abertura: o Safe Mode existe justamente para você corrigir erros de compilação sem carregar o resto do projeto.

Recompilar e limpar a pasta Library

A Unity recompila sozinha quando um script muda. Se você editou fora da IDE e nada aconteceu, force com Assets > Refresh (Ctrl+R) e confira se a opção Auto Refresh em Edit > Preferences > Asset Pipeline está ligada.

Apagar a pasta Library é o último recurso, não o primeiro. Ela guarda cache de importação e é recriada ao abrir o projeto, o que pode levar muitos minutos em projeto grande. Ela resolve cache corrompido (erro que aponta para arquivo que não existe mais, ou um erro que continua depois de corrigido e recompilado). Não resolve erro de código. Para apagar com segurança: feche a Unity, faça commit ou backup do projeto, apague apenas Library (nunca Assets, Packages ou ProjectSettings) e abra de novo.

IDE configurada para ver o erro antes da Unity

O jeito mais barato de evitar o bloqueio do Play Mode é ver o erro enquanto digita. Em Edit > Preferences > External Tools, escolha Visual Studio, Rider ou VS Code no campo External Script Editor e clique em Regenerate project files. Com isso a IDE entende o projeto Unity, sublinha o erro em vermelho na hora e sugere a correção (o using faltando, o nome certo do método).

Se a IDE abre o arquivo mas não sublinha nada nem completa MonoBehaviour, a integração não está ativa. No VS Code, instale a extensão oficial de Unity; no Visual Studio, a carga de trabalho de desenvolvimento de jogos com Unity.

Prevenção: compilar pouco e commitar sempre

Os projetos que mais sofrem com esse erro são os que mudam muito código de uma vez. Três hábitos resolvem:

• Mude pouco, volte para a Unity, veja compilar. Escrever 200 linhas e só então apertar Play é pedir 40 erros encadeados.
• Commit a cada coisa que funciona. Com Git, um projeto quebrado volta ao último estado bom com um comando. O post sobre controle de versão para jogos com Git LFS mostra a configuração para projeto Unity.
• Importe assets num branch separado. Se o asset quebrar o projeto, você descarta o branch.

Próximo passo

Na próxima vez que o Play travar, faça o roteiro na ordem: esconder avisos, ler o primeiro erro, corrigir, salvar, recompilar. Para os casos de nome não encontrado, que são a maioria, guarde o guia do CS0246. E se você está começando, a lista de erros de iniciante em desenvolvimento de jogos cobre os tropeços que não aparecem no Console, como escopo grande demais e projeto que nunca termina.