EditorDebuggerSession in Godot – Complete Guide

Learning to navigate and utilize the tools of any game development environment is absolutely essential for making the most out of the platform and efficiently debugging games. In the context of Godot 4, an open-source game engine rapidly gaining popularity for its accessibility and powerful features, understanding the EditorDebuggerSession class can significantly enhance your game development workflow. This tutorial will provide you with insights into the EditorDebuggerSession class—an integral part of creating and debugging your Godot projects.

What is EditorDebuggerSession?

The EditorDebuggerSession is a vital class within Godot 4 that serves as an interface to interact with the editor’s debugger. It is a backend bridge that allows developers to extend the editor’s capabilities by adding custom tabs, toggling profilers, and communicating with the debugged game. It’s the behind-the-scenes manager for your debug operations within the Godot editor’s UI.

What is it for?

Utilizing EditorDebuggerSession, you can perform essential debugging tasks such as:

  • Adding custom user interface elements to the debugger.
  • Sending bespoke messages between the editor and the game instance.
  • Managing the profiling tools to gather performance data.

Why should I learn it?

Getting a handle on EditorDebuggerSession elevates your debugging skills from merely watching variables to actively manipulating the debugging environment for a tailored experience. This ability is fundamental because:

  • It enhances productivity by allowing rapid access to custom debugging tools directly within the editor.
  • Learning to send messages and toggle profilers can save hours when optimizing game performance or tracking down bugs.
  • Understanding this class gives you a deeper grasp of Godot’s architecture, enabling more complex and controlled developments.

With this foundation in place, let’s dive into how to utilize the EditorDebuggerSession in practical scenarios to streamline your Godot game development.

CTA Small Image

Initializing EditorDebuggerSession

Before you can tap into the power of the EditorDebuggerSession class, you must understand how to initialize and begin a session. This is typically done when the editor itself initializes, but for custom tool scripts, you may want to do it manually.

var debugger_session = EditorInterface.get_editor_interface().get_debugger()

# Now you have an instance of EditorDebuggerSession to work with

Note that EditorInterface.get_editor_interface() is a function that retrieves the main interface of the editor, from which you can access the debugger interface.

Adding Custom Debugger Tabs

Adding custom tabs to your debugger allows you to create specific interfaces for your debug tools. This can include anything from a visual representation of in-game physics to a panel for editing live character stats.

# Assuming 'custom_tab' is a Control node you've created for your tab

# Now 'custom_tab' will appear in the debugger's tab area

Keep in mind that your custom tab should extend Control to properly integrate with the debugger UI.

Interacting with the Running Game Instance

Sometimes, you’ll need to send custom messages back and forth between the editor and the running game. This can be incredibly useful for testing specific scenarios or triggering in-game events while debugging.

Sending a message to the game:

debugger_session.send_message("my_custom_signal", [argument1, argument2])

# This sends "my_custom_signal" to the game with two arguments

To receive and respond to this message within the game, you’d need to have a script listening for “my_custom_signal”.

In-game script:

func _notification(what):
        var message = get_message()
        if message.get("message") == "my_custom_signal":

Utilizing Profiler Data

One of the most powerful features of EditorDebuggerSession is its ability to interact with profilers. This can enable you to monitor performance issues such as bottlenecks or memory leaks in real-time.

Activating the profiler:

# Before starting the game, activate the profiler to gather data

# Once done, don't forget to stop profiling

After profiling, you might want to obtain the data and analyze it:

# After stopping the profiler, fetch the data
var profiling_data = debugger_session.get_profile_data()

# You can now process 'profiling_data' as needed

All of these operations merely scratch the surface of what’s possible with the EditorDebuggerSession class, but they provide a solid foundation for customizing your debugging experience within Godot 4. Armed with these examples, you’re ready to start experimenting and integrating these tools into your development process for more efficient and effective game creation.Continuing from where we left off, let’s dive deeper into practical examples that illustrate the versatility of the EditorDebuggerSession class.

Breaking and Continuing Execution

During a debugging session, you might want to programmatically control the execution flow of your game. For example, to pause the game at a specific moment, you can use:

debugger_session.break_request()  # This pauses the game execution

Once you’ve paused execution, you can resume it with:

debugger_session.continue_request()  # This resumes the game execution

Setting and Removing Breakpoints

Breakpoints are essential for debugging as they allow you to halt execution at a particular line of code. Setting and clearing breakpoints dynamically can add a layer of flexibility in your debugging process.

To set a breakpoint within the game’s code:

var script_path = "res://path_to_your_script.gd"  # Path to your script
var line_number = 42  # The line number to break on

debugger_session.set_breakpoint(script_path, line_number, true)

Similarly, you can remove a breakpoint when it’s no longer needed:

debugger_session.set_breakpoint(script_path, line_number, false)

Inspecting Variables and Objects

Often, you’ll need to inspect variables or the state of objects during a debug session to understand what’s happening inside your game. The EditorDebuggerSession allows you to do this programmatically:

# To inspect a variable or an object

# 'your_object' can be any variable or object instance you want to inspect

After executing this command, the object inspector in the debugger should focus on the object you wanted to inspect.

Monitoring Errors and Warnings

Capturing and responding to errors and warnings as they happen can be crucial for maintaining a stable game. The EditorDebuggerSession class provides a way to retrieve them:

# This call fetches errors and warnings collected by the debugger
var errors_and_warnings = debugger_session.get_error_warnings()

This will provide you with an array of dictionaries, each containing information about an error or a warning that occurred during the debug session.

Custom Debugger Commands

Sometimes you may want to define custom commands that can be called while debugging. Here’s how you can add a custom debugging command:

# Custom command registration should be done in the _ready() function
func _ready():
    debugger_session.register_message("my_command", self, "_my_command_handler")

func _my_command_handler(data):
    print("Command received with data: ", data)

# Now when 'my_command' is received, it will call '_my_command_handler'

This feature enables you to execute specific pieces of code within the game whenever a custom command message is sent from the EditorDebuggerSession. It opens up countless possibilities for interactive debugging and game testing.

With these code snippets and explanations, you’re now armed with more advanced knowledge of how the EditorDebuggerSession can directly influence the gameplay from within the Godot Editor. Whether setting breakpoints, inspecting objects, or creating custom debugger commands, you can refine how you interact with your game during development, leading to a more polished end product. Dive into your current project with these tools, and experience an immediate difference in your debugging and development process!Moving forward, let’s explore additional functionalities provided by the EditorDebuggerSession class for an even more sophisticated debugging experience in Godot 4.

When debugging physics or AI-related features, there may be instances where you need to step through one frame at a time to analyze precise behaviors. This is similar to a breakpoint, but it allows you to advance frame-by-frame manually.

debugger_session.next_request()  # Steps to the next frame

Often, while investigating an issue, you might want to validate certain conditions or express assertions within the editor’s context. You can craft conditions that, when not met, will send a message via the debugger:

if not condition:
    debugger_session.send_message("condition_failed", ["Your condition failed."])

Retrieving information about the current state of the debugger is also quite beneficial, for instance, checking if the debugger is active:

var is_debugging_active = debugger_session.is_session_active()
print("Is debugging active?: ", is_debugging_active)

For scenarios that require live tweaking of game properties, the EditorDebuggerSession grants the ability to edit remote objects’ properties:

debugger_session.set_remote_object_property(path_to_object, property_name, new_value)

# For example, changing the health of a character in-game.
debugger_session.set_remote_object_property("res://Characters/Player.tscn", "health", 100)

The above code would set the ‘health’ property of a Player object to 100, assuming such a property exists and the path is correct.

In multiplayer or network-driven games, you might find it necessary to monitor network messages. EditorDebuggerSession provides hooks to facilitate this type of monitoring:

func _on_network_message_received(message_type, message_data):
    print("Network message received: ", message_type, message_data)

debugger_session.connect("network_peer_packet", self, "_on_network_message_received")

With this connection, every time a network packet is received by the debugger’s network peer, your ‘_on_network_message_received’ function would be called with the details.

Lastly, if you want to retrieve the path to the currently edited scene for operations such as automated testing or scene analysis, you can do so with EditorDebuggerSession:

var current_scene = debugger_session.get_edited_scene_root()

# This will return the root node of the currently edited scene in the editor
print("Currently edited scene root: ", current_scene)

These practical applications of EditorDebuggerSession not only show its proficiency in traditional breakpoint-and-inspect debugging but also its use as a real-time development assistant. By integrating these capabilities into your game development routines, you can uncover new insights, push the boundaries of your creativity, and build a cleaner, more robust game codebase. Embrace these tools within Godot 4, and let them empower your quest to create games that captivate and enthrall.

Where to Go Next with Your Godot Journey

Your exploration into Godot’s EditorDebuggerSession is just the beginning of a thrilling journey into game development. To continue advancing your skills, we highly recommend delving into our Godot Game Development Mini-Degree. This comprehensive program covers various facets of game creation with Godot 4, from mastering the basics to perfecting advanced game mechanics across several game genres.

In addition to our mini-degree, you can broaden your knowledge with our wider array of Godot courses. These cater to both beginners and seasoned developers, complete with practical projects that can shine in your portfolio. With the skills you’ll gain, you’ll be well on your way to making a mark in the game development industry, whether as a job-seeker or an indie developer starting your own business.

At Zenva, we are committed to helping you grow from a novice to a professional game developer, offering over 250 courses that are designed to boost your career and fulfill your passion for creating games. Our mission is to provide you with the tools, knowledge, and hands-on experience to make your game development dreams a reality. Why wait? Start your next chapter with us today and see where your creativity takes you!


As you embark on your creative journey through the rich landscapes of Godot 4, remember that the knowledge of the EditorDebuggerSession class and debugging strategies is a treasure trove that can profoundly enhance the quality and efficiency of your game development process. Each feature, command, and tool you’ve learned about today is a step towards realizing the true potential of your game ideas, transforming them into immersive experiences for players around the world.

At Zenva, we’re excited to accompany you as you wield these new skills to craft stunning games and expand your developer toolkit. Dive into our comprehensive Godot Game Development Mini-Degree and let’s turn your passion for gaming into tangible, playable art. The path from imagination to implementation is clear, and we are here to guide you through every step. Seize this opportunity to become a trailblazer in the game development frontier and let your creative flag fly high!

Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Godot, Unreal, Python and more.