Debug na Unity: Debug.Log, Breakpoints e Gizmos

Debug na Unity vai muito além de espalhar Debug.Log("aqui") pelo código. Unity Debug.Log com o objeto de contexto já diz qual inimigo gerou a mensagem; Debug.DrawRay e os Gizmos mostram na cena raios, alcances e áreas que normalmente são invisíveis; e um breakpoint no Visual Studio ou no VS Code para o jogo na linha exata para você olhar cada variável. Este guia junta as quatro ferramentas, com o que usar em cada situação.

Os menus e nomes seguem o Unity 6.3 LTS, conferidos em outubro de 2026.

Debug.Log na Unity além do básico

O Debug.Log aceita qualquer objeto e chama o ToString() dele. Com interpolação de string, a mensagem fica legível e carrega os valores que importam:

Debug.Log($"Pulo: grounded={isGrounded}, velY={rb.linearVelocity.y:F2}, frame={Time.frameCount}");

Três hábitos fazem diferença:

• Inclua o frame. Time.frameCount mostra se duas mensagens aconteceram no mesmo frame ou em frames diferentes, o que resolve metade dos bugs de ordem de execução.
• Formate números. :F2 corta para duas casas. Ler 0.3333333 em cem linhas cansa.
• Use cor para separar sistemas. O Console aceita rich text: Debug.Log("<color=cyan>[IA]</color> mudou para Chase");. Com uma cor por sistema (IA, física, save), você acha a linha certa num relance.

LogWarning, LogError e o objeto de contexto

Os três níveis aparecem com ícones diferentes no Console e podem ser filtrados separadamente:

• Debug.Log: informação.
• Debug.LogWarning: algo estranho, mas o jogo segue (um campo opcional vazio, um valor fora do esperado).
• Debug.LogError: algo que não deveria acontecer. Com a opção Error Pause do Console ligada, o Play Mode pausa no primeiro erro.

O segundo parâmetro, o contexto, é o recurso mais subutilizado. Arquivo EnemyHealth.cs:

using UnityEngine;

public class EnemyHealth : MonoBehaviour
{
    [SerializeField, Min(1)] private int maxHealth = 30;
    [SerializeField] private GameObject deathEffect;

    private int currentHealth;

    private void Awake()
    {
        currentHealth = maxHealth;

        if (deathEffect == null)
        {
            Debug.LogWarning($"{name} está sem deathEffect no Inspector", this);
        }
    }

    public void TakeDamage(int amount)
    {
        if (amount < 0)
        {
            Debug.LogError($"Dano negativo ({amount}) recebido por {name}", this);
            return;
        }

        currentHealth -= amount;
        Debug.Log($"<color=orange>[Dano]</color> {name}: -{amount}, vida {currentHealth}/{maxHealth}", this);
    }
}

Com this como contexto, clicar uma vez na mensagem do Console destaca na Hierarchy exatamente qual dos cinquenta inimigos a gerou. Sem o contexto, você só sabe que "algum" inimigo está sem efeito de morte.

Para verificar uma condição que deveria ser sempre verdadeira, Debug.Assert(currentHealth <= maxHealth, "Vida acima do máximo", this); registra um erro só se a condição falhar. E dentro de catch, prefira Debug.LogException(exception, this), que mantém o stack trace original.

Console: filtros, Collapse e stack trace

Abra pelo menu Window > General > Console (ou Ctrl+Shift+C). Na barra do topo:

• Clear limpa as mensagens. O menu ao lado define se o Console limpa sozinho ao entrar em Play (Clear on Play), ao recompilar e ao gerar build.
• Collapse junta mensagens idênticas numa linha só, com um contador. Útil quando um log em Update gera milhares de linhas iguais.
• Error Pause pausa o Play Mode no primeiro LogError ou exceção.
• A caixa de busca filtra pelo texto. Com prefixos como [IA] e [Save], você isola um sistema digitando o prefixo.
• Os três botões com contador à direita ligam e desligam a exibição de logs, avisos e erros.

Selecionar uma mensagem mostra, no painel de baixo, o stack trace: a sequência de chamadas que levou até ali. Dois cliques na mensagem abrem o script na linha do log no seu editor de código. No menu de três pontos do Console, a opção de stack trace logging deixa escolher quanto de pilha a Unity grava para cada tipo de mensagem; reduzir para logs comuns deixa o Console mais leve quando há muitas mensagens.

O mesmo menu tem atalhos para abrir o Editor.log, que guarda tudo que o editor registrou, inclusive o que já foi limpo da janela.

Desenhando na cena: Debug.DrawRay e Gizmos

Raycast, alcance de visão, área de ataque: a maioria dos bugs de gameplay acontece em coisas que você não vê. Desenhe.

Debug.DrawRay e Debug.DrawLine desenham uma linha por um frame (ou pelo tempo que você passar). Arquivo GroundProbe.cs:

using UnityEngine;

public class GroundProbe : MonoBehaviour
{
    [SerializeField] private float rayLength = 0.6f;
    [SerializeField] private LayerMask groundLayer;

    public bool IsGrounded { get; private set; }

    private void FixedUpdate()
    {
        Vector2 origin = transform.position;
        RaycastHit2D hit = Physics2D.Raycast(origin, Vector2.down, rayLength, groundLayer);
        IsGrounded = hit.collider != null;

        Color rayColor = IsGrounded ? Color.green : Color.red;
        Debug.DrawRay(origin, Vector2.down * rayLength, rayColor);
    }
}

A linha aparece no Scene view durante o Play Mode: verde quando acerta o chão, vermelha quando não. Se o personagem "não pula às vezes", você vê na hora se o raio está curto demais ou saindo do lugar errado. Para a linha aparecer também no Game view, ligue o botão Gizmos na barra do Game view.

Gizmos são desenhos de editor ligados a um componente, visíveis fora do Play Mode também. Arquivo EnemySight.cs:

using UnityEngine;

public class EnemySight : MonoBehaviour
{
    [SerializeField] private float sightRange = 6f;
    [SerializeField] private float attackRange = 1.2f;
    [SerializeField] private Transform patrolA;
    [SerializeField] private Transform patrolB;

    private void OnDrawGizmos()
    {
        if (patrolA != null && patrolB != null)
        {
            Gizmos.color = Color.white;
            Gizmos.DrawLine(patrolA.position, patrolB.position);
        }
    }

    private void OnDrawGizmosSelected()
    {
        Gizmos.color = Color.yellow;
        Gizmos.DrawWireSphere(transform.position, sightRange);

        Gizmos.color = Color.red;
        Gizmos.DrawWireSphere(transform.position, attackRange);
    }
}

OnDrawGizmos roda sempre (a rota de patrulha fica visível na fase inteira), e OnDrawGizmosSelected só quando o inimigo está selecionado (os círculos de alcance aparecem para o inimigo que você está ajustando). Esses métodos rodam só no editor e não custam nada na build.

Depurar bem é metade do trabalho de terminar um jogo. A outra metade é saber o que procurar: quando o bug está na física, quando está na ordem de execução, quando está no design. Essa intuição vem de passar por muitos bugs num projeto completo, de preferência com alguém que já passou por eles mostrando o caminho.

Breakpoints com Visual Studio e VS Code

Debug.Log mostra o que você pensou em imprimir. O breakpoint mostra tudo: para a execução na linha e deixa você inspecionar cada variável, a pilha de chamadas e avançar linha a linha.

Pré-requisitos, segundo o manual do Unity 6.3:

• Visual Studio (Windows): o Visual Studio Tools for Unity instalado no Visual Studio, o pacote Visual Studio Editor (com.unity.ide.visualstudio) no projeto e o Visual Studio definido em Edit > Preferences > External Tools > External Script Editor. Instalações novas do editor no Windows já trazem tudo isso.
• VS Code (Windows, macOS, Linux): as extensões C#, C# Dev Kit e Unity (da Microsoft) no VS Code, o mesmo pacote Visual Studio Editor na versão 2.0.20 ou mais nova e o VS Code como External Script Editor. O antigo pacote com.unity.ide.vscode não é mais suportado e não deve ser usado. O passo a passo da configuração está no post sobre configurar o VS Code para Unity.

Passo a passo:

1. No canto inferior direito da Unity, o ícone de inseto mostra o modo de otimização de código. Em Release, o código roda mais rápido mas o depurador não conecta. Clique e troque para Debug.
2. No editor de código, clique na margem esquerda da linha para criar o breakpoint (ou F9).
3. No Visual Studio, use Attach to Unity. No VS Code, abra Run and Debug e escolha a configuração Attach to Unity da extensão.
4. Volte para a Unity e entre em Play Mode. Quando a linha rodar, a execução para no editor de código.

Com a execução parada, passe o mouse sobre variáveis, use a janela de variáveis locais e avance com Step Over (F10) e Step Into (F11). Um breakpoint condicional (clique direito no ponto vermelho) para só quando, por exemplo, currentHealth < 0, o que é ouro para bug que acontece com um inimigo entre cem.

Debug na build: Development Build e logs

Alguns bugs só aparecem na build. Para depurar nela:

• Marque Development Build nas opções de build. Isso habilita o console de desenvolvimento na tela, que mostra erros durante o jogo.
• Marque Script Debugging para poder anexar o depurador ao jogo rodando, e Wait For Managed Debugger se o bug acontece logo no início e você precisa anexar antes de qualquer código rodar.

Mesmo sem depurador, a build grava tudo num arquivo de log. No Windows, o Player.log fica em %USERPROFILE%\AppData\LocalLow\NomeDaEmpresa\NomeDoProduto\, com os nomes de empresa e produto definidos em Player Settings. No macOS, em ~/Library/Logs/NomeDaEmpresa/NomeDoProduto/Player.log. Peça esse arquivo para quem testa o seu jogo: ele vale mais que qualquer descrição do bug. Esse tipo de rotina entra no processo de testes e QA.

Erros comuns: Debug.Log em Update travando o editor

Log em Update sem filtro. Um Debug.Log por frame em cinquenta inimigos gera milhares de mensagens por segundo. O Console fica lento, o editor engasga e o Profiler mostra o log como o maior custo do frame. Logue só na mudança de estado (if (novoEstado != estadoAtual)), ou ligue o Collapse.

Log esquecido na build. Debug.Log continua sendo executado na build e monta a string mesmo que ninguém leia. Para logs de desenvolvimento frequentes, crie um wrapper que o compilador remove. Arquivo DevLog.cs:

using System.Diagnostics;
using UnityEngine;
using Debug = UnityEngine.Debug;

public static class DevLog
{
    [Conditional("UNITY_EDITOR"), Conditional("DEVELOPMENT_BUILD")]
    public static void Info(string message, Object context = null)
    {
        Debug.Log(message, context);
    }
}

Com [Conditional], as chamadas a DevLog.Info(...) (inclusive a montagem da string) somem da build final quando nenhum dos dois símbolos está definido.

Breakpoint que nunca para. Quase sempre o modo de otimização está em Release, ou o depurador não está anexado ao processo certo. Confira o ícone de inseto e refaça o Attach.

Gizmo que não aparece. O botão Gizmos do Scene view está desligado, ou o tipo do seu componente foi desmarcado na lista do menu suspenso ao lado desse botão. Confira os dois. Esse e outros tropeços clássicos estão no post de erros de iniciante em desenvolvimento de jogos.

Próximo passo

Escolha o bug que mais está te irritando no projeto atual. Antes de mexer no código, desenhe o que está invisível (raio, alcance, rota) com Debug.DrawRay ou Gizmos, e coloque um breakpoint condicional no ponto suspeito. Na maioria das vezes o problema aparece na tela antes de você precisar de um único Debug.Log novo.