Erro CS0246 na Unity: Type or Namespace Not Found

O Unity error CS0246 aparece quando o seu script usa um tipo que o compilador não encontra: falta um using, o pacote que traz aquele tipo não está instalado, o nome foi digitado errado ou uma Assembly Definition não tem a referência. A mensagem completa diz qual tipo, em qual arquivo e em qual linha, e lendo ela com calma você resolve em minutos. Este guia mostra como ler a mensagem e corrige cada uma das quatro causas, com os casos que mais aparecem no Unity 6.3 LTS, e termina com o CS0103, o primo que confunde todo mundo.

Enquanto houver um erro desses no Console, a Unity não entra no Play Mode. Se você chegou aqui pela mensagem "All compiler errors have to be fixed", o guia sobre Unity que não entra no Play Mode por erros de compilação cobre o quadro geral.

O que significa o erro CS0246 na Unity

A Unity compila seus scripts C# com o compilador da plataforma .NET, e CS0246 é um código desse compilador, não da Unity. O texto em inglês é sempre o mesmo:

error CS0246: The type or namespace name 'X' could not be found (are you missing a using directive or an assembly reference?)

Tradução livre: "não achei o tipo ou namespace X. Faltou um using ou uma referência de assembly?". A pergunta entre parênteses já é o diagnóstico. Em C#, toda classe mora num namespace, e o arquivo só enxerga direto o que está no próprio namespace ou nos que ele importou com using. E o namespace só existe para o compilador se o assembly (a DLL ou o pacote) que o contém estiver referenciado.

Lendo a mensagem: arquivo, linha e tipo

No Console (Window > General > Console), a linha do erro tem este formato:

Assets/Scripts/PlayerHUD.cs(14,13): error CS0246: The type or namespace name 'TextMeshProUGUI' could not be found (are you missing a using directive or an assembly reference?)

Três informações:

• Assets/Scripts/PlayerHUD.cs: o arquivo. Dois cliques na linha abrem o script na IDE.
• (14,13): linha 14, coluna 13. É ali que o nome aparece.
• 'TextMeshProUGUI': o tipo que faltou. É esse nome que você pesquisa.

Se aparecerem 30 erros, não entre em pânico: um único using faltando gera um erro para cada uso do tipo. Corrija o primeiro, salve, espere recompilar e veja quantos sobram.

Causa 1: using faltando

É a mais comum. O tipo existe no projeto, só não foi importado. A correção é adicionar o using no topo do arquivo. Os que mais faltam em projeto de jogo:

Exemplo corrigido, arquivo PlayerHUD.cs:

using TMPro;
using UnityEngine;

public class PlayerHUD : MonoBehaviour
{
    [SerializeField] private TextMeshProUGUI coinLabel;

    public void SetCoins(int amount)
    {
        coinLabel.text = amount.ToString();
    }
}

Uma IDE configurada resolve isso sozinha: no Visual Studio, Rider ou VS Code com a extensão de Unity, o nome fica sublinhado e o atalho de ação rápida (Ctrl+. no Visual Studio e no VS Code, Alt+Enter no Rider) oferece adicionar o using. Se o sublinhado não aparece, a IDE não está ligada à Unity: em Edit > Preferences > External Tools, escolha a IDE em External Script Editor e clique em Regenerate project files.

Causa 2: pacote não instalado ou namespace mudou

Quando o using está lá e o erro continua, ou o próprio using fica vermelho, o pacote que traz o namespace não está no projeto, ou mudou de nome. Abra Window > Package Management > Package Manager e confira.

Os casos clássicos no Unity 6:

Input System. Projetos novos do Unity 6 vêm com ele ativo, mas um projeto antigo atualizado pode não ter o pacote. Sem ele, using UnityEngine.InputSystem; dá CS0246 no próprio namespace. Instale Input System pela aba Unity Registry.

Cinemachine 3. Esse derruba quem segue tutorial antigo. No Cinemachine 2, o namespace era Cinemachine e o componente era CinemachineVirtualCamera. No Cinemachine 3, que é o que o Package Manager instala no Unity 6, a documentação oficial de upgrade diz que os namespaces passaram para Unity.Cinemachine, e o componente de câmera virtual é o CinemachineCamera. Código assim não compila mais:

using Cinemachine;

public class OldCamera : UnityEngine.MonoBehaviour
{
    public CinemachineVirtualCamera vcam;
}

Versão para o Cinemachine 3, arquivo CameraTargetSwitcher.cs:

using Unity.Cinemachine;
using UnityEngine;

public class CameraTargetSwitcher : MonoBehaviour
{
    [SerializeField] private CinemachineCamera virtualCamera;
    [SerializeField] private Transform newTarget;

    public void FollowNewTarget()
    {
        virtualCamera.Follow = newTarget;
    }
}

TextMeshPro. No Unity 6, o TextMeshPro foi incorporado ao pacote Unity UI (com.unity.ugui). Se você removeu o Unity UI do projeto para "limpar pacotes", o TMPro some junto.

Asset da Asset Store que depende de outro pacote. Um sistema de diálogo pode exigir o Input System, ou o Newtonsoft Json (com.unity.nuget.newtonsoft-json). O README do asset costuma listar. Se o erro aponta para um arquivo dentro da pasta do asset, essa é a primeira suspeita.

Causa 3: erro de digitação e maiúsculas

C# diferencia maiúsculas de minúsculas. Rigidbody2d, rigidbody2D e RigidBody2D dão CS0246; o certo é Rigidbody2D. Outros que pegam muito iniciante:

• Textmeshprougui em vez de TextMeshProUGUI.
• Gameobject em vez de GameObject.
• Monobehaviour (com o "b" minúsculo) em vez de MonoBehaviour.
• Referência a uma classe sua que foi renomeada: você trocou Inimigo por Enemy no arquivo, e outros scripts ainda escrevem Inimigo.

Se o tipo é uma classe sua, confira também se o nome da classe é igual ao nome do arquivo e se o arquivo não está com erro próprio, que impede a compilação do resto.

Esses erros de leitura de código são o tipo de coisa que trava semanas quando você aprende sozinho, porque cada mensagem parece um problema novo. No curso de Unity você escreve o código de um jogo completo com uma base de C# que deixa esses erros previsíveis, e aprende a ler o Console como ferramenta, não como castigo.

Causa 4: Assembly Definition sem referência

Se o seu projeto usa arquivos .asmdef (Assembly Definition), cada pasta com um deles vira um assembly separado. Scripts dentro desse assembly só enxergam o que está referenciado nele, mesmo com o using certo e o pacote instalado.

Sintoma típico: o mesmo using TMPro; funciona num script fora da pasta e dá CS0246 num script dentro dela.

Correção:

1. Selecione o .asmdef da pasta do script com erro.
2. No Inspector, em Assembly Definition References, clique no +.
3. Adicione a referência do pacote: Unity.TextMeshPro para TMP, Unity.InputSystem para Input System, Unity.Cinemachine para Cinemachine, Unity.RenderPipelines.Universal.Runtime para tipos do URP.
4. Clique em Apply.

Outra armadilha: código em .asmdef não enxerga scripts que ficaram fora de qualquer .asmdef (o assembly padrão, Assembly-CSharp). Se o seu Player está na pasta sem asmdef e o Inventory está num asmdef, o Inventory não consegue referenciar Player. Ou você cria um asmdef para os scripts principais e referencia, ou não usa asmdef ainda.

Um caso que só aparece no build: script de jogo com using UnityEditor;. No editor compila, no build dá CS0246 porque o UnityEditor não existe fora do editor. Coloque o código de editor dentro de #if UNITY_EDITOR ... #endif ou mova para uma pasta chamada Editor.

Para descobrir o nome exato da referência, selecione o .asmdef do pacote: ele fica na pasta do pacote, em Packages no Project, e o campo Name do Inspector é o texto que você procura na lista. Se você não sabe se o seu projeto usa asmdef, busque t:AssemblyDefinitionAsset na barra de busca do Project. Nenhum resultado dentro de Assets significa que todos os seus scripts estão no assembly padrão e essa causa está descartada.

CS0103: o primo do CS0246

O CS0103 tem outra mensagem:

error CS0103: The name 'X' does not exist in the current context

A diferença é onde o nome aparece. O CS0246 reclama de um nome usado como tipo (declarar campo, herdar, GetComponent<X>()). O CS0103 reclama de um nome usado como valor ou chamada que não existe ali.

Causas comuns:

• Variável fora do escopo. Declarada dentro de um if ou de outro método e usada fora.
• Erro de digitação em variável. speed declarado, Speed usado.
• Classe estática sem using. SceneManager.LoadScene("Fase2") sem using UnityEngine.SceneManagement; dá CS0103, não CS0246, porque SceneManager aparece numa chamada. A correção é a mesma: o using.

Arquivo LevelExit.cs, com as duas correções aplicadas:

using UnityEngine;
using UnityEngine.SceneManagement;

public class LevelExit : MonoBehaviour
{
    [SerializeField] private string nextSceneName = "Fase2";

    private void OnTriggerEnter2D(Collider2D other)
    {
        bool isPlayer = other.CompareTag("Player");
        if (isPlayer)
        {
            SceneManager.LoadScene(nextSceneName);
        }
    }
}

Próximo passo

Configure a IDE hoje, antes do próximo erro: com a integração ativa, CS0246 e CS0103 aparecem sublinhados enquanto você digita, e o atalho de ação rápida adiciona o using em um segundo. Depois, revise a lista de erros de iniciante em desenvolvimento de jogos para os problemas que não aparecem no Console. Se C# ainda é novidade, o post sobre qual linguagem a Unity usa explica namespace, classe e tipo do começo, e deixa essas mensagens bem menos misteriosas.