Guide to the Godot game engine/Debugging

<-- Your first game Debugging Input-->

The debugger dock

The debugger dock is the default and best way to debug. If a red circle is shown next to it, there is an error to read. If there is a yellow circle, you have a new warning to read.

When you open it, you have several tabs:

Debugger

This is the tab opened when a script error occurs. It is not shown for a fatal error, instead the game just crashes. In this case, see below.

It shows the "stack frames". This is a stack of function calls, allowing you to find the source of the error. This is invaluable. To the right of the stack frames show all the variables the script can access, and what they are set to. Above that is a few buttons:

Skip Breakpoints: stops the game being paused on breakpoints until this is repressed.
Copy Error: copy the error to your clipboard.
Step Into: runs the next expression. Enters indented blocks that it would enter anyway.
Step Over: runs the next expression. Skips indented blocks.
Break: pauses the game as if a breakpoint was used.
Continue: resumes the game.

Errors

Allows you to see every fatal and non-fatal error and warning that you encountered during the running game. There are a few buttons:

Clear: empties this list.
Expand All: expands every error to see more information.
Collapse All: collapses every error to see less information.

Each error may be pressed to go to the script and line the error came from. Double click it to expand or collapse. You can also click the arrow to expand/collapse. Expanding it shows the error and the code stack.

Profiler

This allows you to record function call count and how much frame time is used. It is priceless when optimizing your game, and can be used for debugging too.

To begin, you must press start. On the right, a chart will generate. Higher up lines means that something takes up a large amount of the game's processing. They should be optimised at some point, as much as possible.

To check what is slowing the game down the most, click in the chart in the area with a high peak, and scroll down the left. You will see how many seconds each function call costs, and how many times it was called. If you want a percentage, click on the Mesure: value, and choose Frame %.

The Time: has two values:

Inclusive: shows the frame time or percentage of all calls to a function
Self: shows the single largest frame time or percentage during a single call.

Network Profiler

This allows you to see how much internet is being used by each node. Both how much used in sending, and how much used in reciving.

Monitors

This allows you to check performance in a graph. Most useful options to show are:

Time:
- FPS: Frames per second.
- Process: The amount of time spent every idle frame.
- Physics Process: The amount of time spent in the physics frame.
Memory:
- Static: How much memory is used for unchanging things.
- Dynamic: How much memory used is always changing or code being ran.
- Static Max: The maximum static memory reached.
- Dynamic Max: The maximum dynamic memory reached.
- Msg Buf Max: The memory used by output, including errors and warnings.
Object
- Objects: The total number of Objects there are.
- Resources: The amount of Resources that exist.
- Nodes: The number of Nodes that exist.
- Orphan Nodes: The number of Nodes that are not inside the SceneTree. In general, this should always be zero. Try to use resources or an object if it is intentional. Otherwise you should free it if possible, by calling free() on that node when you are finished with it.

Video RAM

This allows you to see how many images are using up memory, and which ones.

Misc

This allows you to see the Control node last activated before the game closed, and its node path.

Script debugging

With the script editor open, press the "Debug" button at the top. It is close to "File" and "Search".

You have a few options explained above: Step into, step over, break and continue.

You also have two other options:

Keep Debugger Open: having a running game slows down the editor, so closing it is a must. But closing the game also closes the debugger. Check this option to keep it open when you close your game.
Debug With External Editor: allows you to use another editor to debug with.

Debug options

At the very top of the screen, press the "Debug" button. It appears near "Scene" and "Project". You have the following options:

Deploy with Remote Debug: when exporting, the resulting executable will attempt to connect with the computer to be debugged.
Small Deploy with Network FS: exporting produces a minimal executable. The file system is provided over the internet.
Visible Collision Shapes: whether or not to show collision shapes.
Visible Navigation: whether or not navigation meshes and polygons are visible in the running game.
Sync Scene Changes: if checked, changes to a scene is replicated to the running game.
Sync Script Changes: if checked, changes to a script will cause it to be reloaded in the running game.

Debugging editor plugins

The best way to debug an editor plugin is to keep an eye on the output dock. If that doesn't help, adding temporary print() calls can help you to see what is called and the values of variables.

Catching fatal errors

A fatal error is a crash that doesn't throw an error message. Its usually caused by an engine bug, and sometimes has nothing to do with your code. You can either try a different way of doing what the code was doing when it crashed, or report a bug report here. You may need to send a copy of the code that was running when it happened.

Note exactly what you were doing when it happened. Try to find out what code was running, and add breakpoints everywhere around that area. If it doesn't crash this time, remove the breakpoints again. If it still doesn't crash when playing, make certain you are doing exactly what you wrote down.

If you still can't reproduce the crash, assume it is not an issue you can fix, and is an editor bug. Consider sending a bug report. This may require giving a sample of the code used in the general area of where you think the issue is, and you may need to give the exact instructions of what you were doing. Consider also uploading any helpful log files.