Overview

I've been working on a general-purpose debug console for use in a wide variety of projects that anyone can use for free in the Godot Engine. It will be released under the permissive M.I.T license and coded in GDScript.

I'm sure most of you are familiar with what a debug console is and what its purpose is, but in case you don't know, it's a tool used by developers to test/monitor for bugs while in-game. Usually, debug consoles do many things and give the developers a lot of power to test and look for bugs without needing to exit the game and go back into the editor. They usually have many commands that will alter game settings and display useful information about the game. Think of it as a Swiss Army knife.

Famous examples include the debug screen in Minecraft when you press "F3", or in games like Skyrim when you press the "~" tilde key and the debug console appears. A debug console can be useful even for the player.

Needless to say, this type of tool can be invaluable in a game, particularly in larger-scale projects. It's also something that most people don't think of when they're developing a game or don't want to go to the trouble of creating and implementing. So hopefully this project of mine will help solve that for most people. I've designed it to work in any type of game whether it be 2D, 3D, or a mix of both, this will work just fine regardless. There's also no need to reprogram your existing projects to include this, it just works and integrates out of the box.

It's a single scene and single script, all you need to do is to autoload the scene and set it to the top of your load order. After that, it will work and be present in every scene of your game automatically. It's lightweight and uses very few resources.

Usage

The console is opened by pressing the "debug" action which you must create in your project by adding it to your input map in order to use the console, this will bring up the debug console, the game will be paused, and you'll be able to enter commands.

Commands are entered in a prefix-command order. That is, first you type the prefix, followed by a space, followed by the command/value. Then you press the enter/return key to input the command. If the command is valid it will act upon it, if not it will ignore it, or tell you what's wrong with it. Either way, it prints what you just typed into the output log.

Example: cr 500,500

The above example will change the game window to be 500x500 pixels. In the above example "cr" is the prefix and "500,500" is the value ("cr" is short for "change resolution").

#Preview <iframe width="560" height="315" src="https://www.youtube.com/embed/8-I-5UJ26MA" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

This video is already outdated because I've added two more commands since I made it, those being quit and fov. The quit command will close the application, useful in case it gets stuck and you're in fullscreen mode. While fov will allow you to change the field of view in a 3D scene on the fly. It will automatically check if you have a 3D camera in your current scene to set the fov of, if not, it will tell you so and ignore the command.

As you saw in the video, the console also includes two optional variables exported to the inspector. One that enables the console in-game, and another that sets the mouse visibility when the console is exited. I figured both of these would be useful settings to have available.

This is all the stuff I've managed to do in the last four days since I started this project, but I intend to improve it wherever possible.

@cybereality said: Awesome job! This would be very useful.

Thanks! I'm glad you like it!

5 days later

Update

It's been 5 days since I announced my debug console addon and I've been working to improve both the design and the functionality of it for Godot. I've added several new commands and updated some older ones. Three new commands I've added include: fxaa, msaa, and debug draw. Both the fxaa and msaa commands will simply allow you to toggle between various anti-aliasing settings in-game.

I feel as though this addon is reaching a more mature stage, and I'm just about ready to release version 1.0 now that I've got the majority of features I wanted to be implemented. I've got some more experimental ideas I'd still like to play around with at some point, such as manually calling functions from any of the scripts within the scene from the console.

X-Ray

debug draw will toggle debug overdraw in 3D scenes. It effectively makes all 3D models see-through, a lot like x-ray vision. Great for debugging large complex scenes with lots of geometry.

Note: debug draw only works with the GLES3 render backend and when using a binary in debug mode

Graphics API

I've also added a small label in the bottom right-hand corner of the output log that will display the current graphics API being used. In the future when Godot 4.0 is released I will update this to include Vulkan as well. Overall, it's a minor addition, but it's nice to have. The exact graphics API being used is platform-specific and this label will check for all variations at runtime.

Revisions

I've changed the way the vsync command works to be more intuitive. Previously it required you to type mw vsync. This isn't bad necessarily, but I realized it was a lot more intuitive if the command was shortened to just vsync alone. So that's what I did. The old command will still work too.

Very nice. I already see myself using this in the near future.

Release v1.0

Today, after about a week and a half since I started this project, I've decided to release v1.0 of my debug console addon for Godot. The link to the repository can be found here: https://github.com/SirQuartz/debugconsole

As far as my testing goes I've not found any issues with the console and its functionality in either 2D or 3D scenes, however, there may still be edge cases where it doesn't act how it should. If you find any issues feel free to submit them on the issues page of the GitHub repository. It's intended to work in any project out of the box, however, there are a few things to keep in mind:

  1. This console addon uses an input action called "debug" in your input map. So you need to create an input action by going to Project > Project Settings > Input map and adding a new action called "debug" and assign it a key.
  2. The console.tscn scene must be at the top of your singleton load order in order to guarantee this plugin works properly, that way it's always loaded in first.
  3. You can disable the console in-game by clicking the "Input" node in the console scene tree and unchecking the enable_console variable in the inspector.
  4. This debug console exists within its own CanvasLayer, this CavasLayer is on layer 128. Which is the highest it can go. This is done to ensure that the debug overlay is always rendered on top of everything else in your scenes.

Future

This is unlikely to be the final version of this addon, I just felt that it was a pretty good place with a decent amount of useful functions for an initial release. I will continue to update and improve the addon over time. You can check back here for future updates, or visit the GitHub repository for new releases.

I made this addon with the intention that it would be useful to many people and save them a lot of time. Believe me, I know coding these types of tools isn't exactly fun, and not something most people want to bother doing, but is really useful and really convenient to have, which is why I decided to make this for everyone.

If you haven't already(as in if you have hard-coded it in) I'd recommend making the keybinding configurable. Many games typically ship with console key unmapped by default even, but leave it open for users to enable/map it via config files.

@Megalomaniak said: If you haven't already(as in if you have hard-coded it in) I'd recommend making the keybinding configurable. Many games typically ship with console key unmapped by default even, but leave it open for users to enable/map it via config files.

Yeah, I had considered doing this early on, but figured that the left quote key was already understood to be the console key in most games that have one. I’ll probably update it within the next few days to make it configurable.

@SirQuartz said:

@Megalomaniak said: If you haven't already(as in if you have hard-coded it in) I'd recommend making the keybinding configurable. Many games typically ship with console key unmapped by default even, but leave it open for users to enable/map it via config files.

Yeah, I had considered doing this early on, but figured that the left quote key was already understood to be the console key in most games that have one. I’ll probably update it within the next few days to make it configurable.

Actually, I made an oversight while describing the installation process of this plugin. I forgot to mention that you need to assign an input action called "debug" in your project's input map. So I more or less already had this set up to be reconfigurable. There's actually no default key assigned, but I forgot about that.

Debug draw, draws all the collision, but could you do something like Debug ray, where it would draw all the RayCasts? It would be useful to see if they are even active. Great tool!

Also, msaa command doesnt do anything

EDIT, actually I found out you had to put the text off, or an even number from 2 - 8.

@crogaro said: Debug draw, draws all the collision, but could you do something like Debug ray, where it would draw all the RayCasts? It would be useful to see if they are even active. Great tool!

Also, msaa command doesnt do anything

EDIT, actually I found out you had to put the text off, or an even number from 2 - 8.

Thanks! Yes, MSAA can only be set in multiples of 2 just like in the project settings up to a max of 8.

I can see how drawing all the raycasts would be useful, I'll look into it.

Note that debug draw modes aren't available in exported projects or in GLES2. This means the associated command will only work when the project is run from the editor and uses the GLES3 rendering backend.

@Calinou said: Note that debug draw modes aren't available in exported projects or in GLES2. This means the associated command will only work when the project is run from the editor and uses the GLES3 rendering backend.

I will be sure to put a note about that. Also, I'll have the function check that the user is both using a binary in debug mode and using the GLES3 render backend.

Update Preview #2

I've once again been working on adding more features and functionality to the console. Although, at this point, I'm starting to run out of ideas for new things to add. I've not released this version yet as there are still some things I need to iron out and polish before it's ready, but I'm almost there.

Screenshots

The first new thing I've added is a new shoot command which will allow you to take a screenshot of the viewport. It does this by hiding the debug overlay, getting the viewport texture, asking you to name the screenshot, and then saving it in a folder called "Screenshots" in your project's root directory. This sounds complicated, but it's just a two-step process for the user, the rest is handled automatically for you behind the scenes. All you do is type shoot, then it will ask for you to name the file.

Note: If you name the screenshot something that already exists in the screenshots folder it will automatically overwrite that existing file. You also don't need to type the extension of the file, it does that for you, all you need to do is enter the name.

Manual Method Calls

Next up, I've added the ability to call almost any function on any node within your scene, even on singletons, from the debug console.

You just type Object.method. With "Object" being the exact name of the node as it appears in your scene, and "method" being the exact name of the method you wish to call. It does this by first checking that the object exists somewhere within your scene. This is case-sensitive so you need to keep that in mind. And yes, this will work on custom methods in scripts attached to the node.

Note: The method you call must actually exist within this specific object or exist within the object(s) it inherits from, or exist in a script attached to the object if it's a custom method.

It can also accept up to three optional arguments separated by spaces.

<iframe width="560" height="315" src="https://www.youtube.com/embed/6rRBQX95TUA" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Right now this is command is limited to accepting 3 optional arguments for whatever function you call (I might increase that amount in the future). This is by far the most powerful feature I'll be adding to this console plugin, although, it's not perfect right now. Another limitation is that if your scene has multiple child objects with the exact same name it will only call the method on the first occurrence of the child object in the scene tree hierarchy. So I'd recommend giving all your nodes unique names (which you should be doing anyway just because it's a best practice).

Debug Ray

Lastly, I've added a debug ray command that will show all the collisions shapes and raycasts in 2D or 3D scenes. This command requires that the scene be reloaded in order for the changes to take effect. This command also requires that you are using a debug binary of your game if you export it in order for this command to work.

In this scene, I've placed a single raycast that originates just off the center of the screen and shoots out to the right of the camera. It's represented by the orange line.

I hope you'll find these additions useful (✿◡‿◡)

I think I'd rather have named it screenshot than shoot but perhaps there's a special reason for it.

@Megalomaniak said: I think I'd rather have named it screenshot than shoot but perhaps there's a special reason for it.

I named it "shoot" simply because it's faster and easier to type. My main goal with naming all the commands was to keep it as brief as possible while still making logical sense. This makes it easier to type quickly in-game. That's why the other commands like cr, mt, fov, and mw are all just two/three letters (although you can also use the full name like change_resolution, modify_time, field_of_view, and modify_window as the prefix and it will still accept it as valid).

I could do a similar thing with the shoot command, where I give you two options for the prefix and it will accept either. So shoot and screenshot could both be equally valid. I think that'd be a good solution. I'll add that in the next version.

Yep, that would probably do. It's just that shoot isn't something someone would use unless they've read documentation or --help or man or such.