Debug.Log for debugging in Unity - Deep Dive

Overview - Debug.Log for debugging

What is it?

Debug.Log is a simple tool in Unity that lets you print messages to a console while your game runs. It helps you see what your game is doing behind the scenes by showing text information. This is useful for checking if parts of your code are working as expected or finding where problems happen. It works like leaving notes for yourself inside the game to understand its behavior.

Why it matters

Without Debug.Log, finding errors or understanding game behavior would be like trying to fix a car engine without seeing inside it. You would have to guess what is wrong, which wastes time and causes frustration. Debug.Log gives you clear clues about what your game is doing, making it easier to fix bugs and improve your game. It saves hours of trial and error and helps you learn how your code works in real time.

Where it fits

Before using Debug.Log, you should know basic Unity scripting and how to write simple C# code. After mastering Debug.Log, you can learn more advanced debugging tools like breakpoints and the Unity Profiler. Debug.Log is an early step in understanding how to test and fix your game code effectively.

Mental Model

Core Idea

Debug.Log is like a flashlight that shines light on your game's hidden actions by printing messages you choose to the console.

Think of it like...

Imagine you are trying to find a lost item in a dark room. Debug.Log is like turning on a flashlight that shows you exactly where you are looking and what you find along the way.

┌─────────────────────────────┐
│       Your Game Code        │
│  ┌───────────────────────┐  │
│  │ Debug.Log("Message") │  │
│  └───────────────────────┘  │
│             ↓               │
│       Unity Console         │
│  ┌───────────────────────┐  │
│  │ "Message" appears here │  │
│  └───────────────────────┘  │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

What is Debug.Log and Console

Concept: Introduces Debug.Log as a way to print messages to Unity's Console window.

Debug.Log is a command you write in your script to send a message to the Console. The Console is a special window in Unity where you can see these messages while the game runs. For example, Debug.Log("Hello World") will show "Hello World" in the Console.

Result

When you run the game, the Console shows the message you wrote inside Debug.Log.

Understanding that Debug.Log sends messages to the Console is the first step to seeing inside your game's behavior.

2

Foundation

Basic Syntax of Debug.Log

Concept: Shows how to write Debug.Log with text and variables.

You write Debug.Log followed by parentheses and a message inside quotes. You can also print variables by adding them inside the parentheses. For example, int score = 10; Debug.Log("Score: " + score); will print "Score: 10".

Result

The Console displays the combined message with the variable's value.

Knowing how to include variables in Debug.Log helps you track changing values during gameplay.

3

Intermediate

Using Debug.Log for Conditional Checks

🤔Before reading on: Do you think Debug.Log can help you check if a condition is true or false during the game? Commit to your answer.

Concept: Shows how to use Debug.Log inside if statements to check conditions.

You can put Debug.Log inside if or else blocks to see which path your code takes. For example: if(playerHealth <= 0) { Debug.Log("Player is dead"); } else { Debug.Log("Player is alive"); } This helps you know which part of your code runs.

Result

The Console shows messages depending on the player's health, helping you verify game logic.

Using Debug.Log inside conditions reveals the flow of your game logic, making bugs easier to find.

4

Intermediate

Debug.Log with Object States

🤔Before reading on: Can Debug.Log show you the current state of game objects like position or speed? Commit to your answer.

Concept: Explains how to print properties of game objects to understand their state.

You can print details like position or speed by accessing object properties. For example: Debug.Log("Player position: " + player.transform.position); This shows where the player is in the game world at that moment.

Result

The Console displays the player's position coordinates, helping you track movement.

Seeing object states in real time helps you understand how your game world changes frame by frame.

5

Intermediate

Debug.Log Variants: Warning and Error

🤔Before reading on: Do you think Debug.Log can show different types of messages like warnings or errors? Commit to your answer.

Concept: Introduces Debug.LogWarning and Debug.LogError for different message types.

Besides Debug.Log, Unity has Debug.LogWarning and Debug.LogError. They show messages in yellow or red in the Console, making important issues stand out. For example: Debug.LogWarning("This might be a problem"); Debug.LogError("This is a serious error");

Result

The Console highlights warnings and errors with colors, helping you spot critical issues quickly.

Using different message types helps prioritize what needs your attention during debugging.

6

Advanced

Performance Impact of Excessive Debug.Log

🤔Before reading on: Does using many Debug.Log calls slow down your game? Commit to your answer.

Concept: Explains how too many Debug.Log calls can affect game performance.

Debug.Log writes messages every time it runs, which can slow your game if used inside fast loops or Update methods. For example, calling Debug.Log every frame can cause lag. It's best to limit logs or disable them in production builds.

Result

Excessive logging can reduce frame rates and make the game feel slow.

Knowing the cost of logging helps you balance debugging needs with game performance.

7

Expert

Conditional Compilation to Control Debug Logs

🤔Before reading on: Can you control when Debug.Log runs without removing the code? Commit to your answer.

Concept: Shows how to use conditional compilation to enable or disable Debug.Log in different builds.

You can wrap Debug.Log calls inside #if UNITY_EDITOR or custom symbols to run logs only in the editor or debug builds. For example: #if DEBUG Debug.Log("Debug info"); #endif This way, logs don't run in the final game, improving performance.

Result

Debug messages appear only when you want them, keeping production builds clean and fast.

Controlling logs with compilation symbols is a professional way to keep debugging powerful but safe for release.

Under the Hood

When your game runs and hits a Debug.Log call, Unity sends the message string to its internal logging system. This system queues the message and displays it in the Console window. The Console stores messages with timestamps and types (log, warning, error). Behind the scenes, Debug.Log calls are lightweight but still consume CPU and memory, especially if called frequently. Unity's editor listens for these messages and updates the Console UI in real time.

Why designed this way?

Debug.Log was designed as a simple, universal way to get feedback from running code without needing complex tools. It uses a text-based message system because text is easy to generate and understand. The separation of log types (log, warning, error) helps developers quickly identify issues. The design balances ease of use with performance, allowing quick debugging during development but encouraging disabling logs in production.

┌───────────────┐
│ Your Script   │
│ Debug.Log()   │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Unity Logging │
│ System       │
└──────┬────────┘
       │
       ▼
┌───────────────┐
│ Console UI    │
│ Displays Msgs │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does Debug.Log slow down your game significantly even if used once per frame? Commit to yes or no.

Common Belief: Debug.Log calls are free and have no impact on game speed.

Reality: Each Debug.Log call uses CPU and memory, so many calls per frame can slow the game down noticeably.

Why it matters: Ignoring this can cause performance problems, especially on slower devices or complex games.

Quick: Does Debug.Log show messages in the final built game by default? Commit to yes or no.

Common Belief: Debug.Log messages always appear in the final game build.

Reality: By default, Debug.Log messages do appear in builds, but developers often disable or remove them for performance and security reasons.

Why it matters: Leaving logs in production can expose internal info and reduce performance.

Quick: Can Debug.Log show variable values without converting them to strings? Commit to yes or no.

Common Belief: You can pass any variable directly to Debug.Log and it will display correctly without conversion.

Reality: Debug.Log calls ToString() on variables, so complex objects may not display useful info unless you override ToString() or format the output.

Why it matters: Assuming automatic readable output can lead to confusing logs and wasted debugging time.

Quick: Does Debug.Log work the same way in all Unity platforms (PC, mobile, console)? Commit to yes or no.

Common Belief: Debug.Log behaves identically across all platforms and always shows messages.

Reality: Some platforms may handle logs differently or limit Console access, so Debug.Log messages might not always be visible or behave the same.

Why it matters: Relying on Debug.Log without platform testing can cause missed bugs or confusion.

Expert Zone

1

Debug.Log calls can be grouped and filtered in the Console, but excessive logs can flood the UI and hide important messages.

2

Using string interpolation with Debug.Log (e.g., $"Score: {score}") is more efficient and readable than string concatenation.

3

Debug.Log messages can be linked to source code lines in the Console, allowing quick navigation to the code that generated the message.

When NOT to use

Debug.Log is not suitable for tracking complex game state or performance profiling. Instead, use Unity's Profiler, custom logging frameworks, or debugging tools like breakpoints and watch windows for deeper inspection.

Production Patterns

In production, developers often disable Debug.Log calls using conditional compilation or remove them entirely. For critical errors, they use Debug.LogError with remote logging services to capture issues from players. Debug.Log is mainly a development-time tool.

Connections

Logging in Software Engineering

Debug.Log is a specific example of logging, a common practice in software to record program events.

Understanding Debug.Log helps grasp the universal idea of logging, which is essential for monitoring and debugging any software system.

Flashlight

Both Debug.Log and a flashlight reveal hidden details in dark or unknown environments.

This connection shows how tools that reveal hidden information are crucial for exploration and problem solving in many fields.

Scientific Experimentation

Debug.Log acts like recording observations during an experiment to understand cause and effect.

Knowing this helps appreciate debugging as a process of gathering evidence to test hypotheses about code behavior.

Common Pitfalls

#1 Logging inside Update() without limits causes performance drops.

Wrong approach:

void Update() {
Debug.Log("Frame update");
}

Correct approach:

void Update() {
if(Time.frameCount % 60 == 0) {
Debug.Log("Frame update every 60 frames");
}
}

Root cause:

Not realizing that Update runs every frame and logging each time overloads the Console and CPU.

#2 Leaving Debug.Log calls in production builds reduces performance and leaks info.

Wrong approach:

Debug.Log("Player position: " + player.transform.position); // left in final build

Correct approach:

#if UNITY_EDITOR
Debug.Log("Player position: " + player.transform.position);
#endif

Root cause:

Forgetting to disable or remove logs before releasing the game.

#3 Passing complex objects to Debug.Log without formatting shows unreadable output.

Wrong approach:

Debug.Log(player);

Correct approach:

Debug.Log($"Player position: {player.transform.position}, Health: {player.health}");

Root cause:

Assuming Debug.Log automatically formats complex objects for easy reading.

Key Takeaways

Debug.Log is a simple but powerful tool to see what your Unity game is doing while it runs.

Using Debug.Log helps you find bugs by printing messages about game events, conditions, and object states.

Too many Debug.Log calls can slow your game, so use them wisely and disable them in production.

Advanced use includes different message types and conditional compilation to control when logs appear.

Understanding Debug.Log builds a foundation for more advanced debugging and monitoring techniques.