godot-extended-libraries / godot-debug-menu

Display in-game FPS/performance/hardware metrics in a Godot 4.x project

Debug Menu add-on for Godot 4.x

Displays performance information in a Godot project during gameplay. Can be used when running from the editor and in exported projects. Inspired by id Tech 6/7's performance overlay.

This repository only contains the add-on. See godot-extended-libraries/godot-debug-menu-demo for the demonstration project.

Features

• Features compact and full display modes, with the compact mode only displaying FPS, frametime and framerate cap.
• Displays FPS, frametime, CPU time and GPU time graphs with a summary of the best/worst/average frametimes over recently drawn frames.
• Displays hardware information, including graphics driver version.
• Displays software information, including project version (if specified in the application/config/version custom project setting) and graphics settings.
• Works with the Forward+, Mobile and Compatibility rendering methods.
• Works with 2D and 3D projects.
• Works when running the project from the editor, but also in exported projects (debug and release).

Why use this debug menu?

• Compared to the Godot editor's Profiler, Monitors and Visual Profiler bottom panels, you can look at an in-game debug menu while the project is running, even in fullscreen if you only have a single monitor.
  • Rendering performance is highly dependent on window size, so resizing the window is not advised for reliable performance measurements in real world scenarios.
• This debug menu accurately displays graphs and best/worst frametime metrics over a period of the last 150 rendered frames, which is useful to diagnose stuttering issues. The Monitor bottom panel is only updated once a second and doesn't feature a 1% low FPS metric, which makes tracking stuttering difficult when relying solely on the monitors.
• This debug menu can be used in exported projects to reliably test performance without any editor interference. This includes testing on mobile and Web platforms, which tend to be more difficult to set up for profiling within Godot (if it's even possible).
• This debug menu can be used in exported projects for tech support purposes. For example, in a bug report, you could ask a player to upload screenshots with the debug menu visible to troubleshoot performance issues.

External tools such as RTSS or MangoHud provide some insight on how well a project actually runs. However, they lack information on engine-specific things such as per-frame CPU/GPU time and graphics settings.

How to read values in the debug menu

To determine whether values for Total, CPU and GPU displayed in the debug menu are good or bad, you need to set yourself a target frametime first. Unlike FPS (frames per second), lower frametimes are better.

The frametime is determined by the formula 1000.0 / FPS where FPS is your target FPS. For example, if you aim to have at least 60 FPS at all times on your current hardware, you should ensure that Total never exceeds 16.66 mspf (milliseconds per frame). At 30 FPS, this target frametime is 33.33 mspf, and at 120 FPS, it's 8.33 mspf.

When looking at Avg (average) metrics, it's recommended to keep at least 25% of headroom to ensure that more demanding situations in the game can match the target frametime. This also allows the hardware to cool better and have better battery life if using a framerate cap. This means that if you target 60 FPS, your average FPS should be at least 75, which is a frametime of 13.33 mspf or lower.

If the FPS dips below the target due to the frame time being too high, this could be due to a bottleneck in one of 3 areas:

• GPU rendering: This is denoted by the GPU time going close to the target frametime (not necessarily above, as the total frametime is also determined by the CPU time and scripting). This is usually caused by stressing the GPU too much with advanced shaders, high polygon counts or antialiasing, or having a weak GPU compared to the CPU.
• CPU rendering: This is denoted by the CPU time going close to the target (not necessarily above, as the total frametime is also determined by the GPU time and scripting). This is usually caused by having too many draw calls in the scene, or having a weak CPU compared to the GPU.
• CPU other: This is not denoted by the CPU or GPU time metrics, but by the Total time metric (which is just a different way to display FPS). This is usually caused by scripting, physics simulation or navigation computations taking too much time in a given frame.

The metrics marked as Worst are also important, as these denote the time taken to render the slowest frame in the currently displayed graph (the graph shows the last 150 rendered frames). You want to make sure this metric stays below your target frametime as much as possible.

You can find detailed guidance on optimizing a project's performance in the documentation.

Installation

Using the Asset Library

• Open the Godot editor.
• Navigate to the AssetLib tab at the top of the editor and search for "debug menu".
• Install the Debug Menu plugin. Keep all files checked during installation.
• In the editor, open Project > Project Settings, go to Plugins and enable the Debug Menu plugin.

Manual installation

Manual installation lets you use pre-release versions of this add-on by following its master branch.

• Clone this Git repository:

git clone https://github.com/godot-extended-libraries/godot-debug-menu.git

Alternatively, you can download a ZIP archive if you do not have Git installed.

• Move the addons/ folder to your project folder.
• In the editor, open Project > Project Settings, go to Plugins and enable the Debug Menu plugin.

Usage

Press F3 while the project is running. This cycles between no debug menu, a compact debug menu (only FPS and frametime visible) and a full debug menu.

The key to cycle the debug menu is set to F3 by default. This can be changed by setting the cycle_debug_menu action in the Input Map to a different key. This action is not created by the plugin in the editor, so you will have to create it in the Project Settings if you wish to override the key.

To toggle the debug menu from code, use:

• DebugMenu.style = DebugMenu.Style.NONE to hide the debug menu.
• DebugMenu.style = DebugMenu.Style.VISIBLE_COMPACT to show the compact debug menu.
• DebugMenu.style = DebugMenu.Style.VISIBLE_DETAILED to show the detailed debug menu.

License

Copyright © 2023-present Hugo Locurcio and contributors

Unless otherwise specified, files in this repository are licensed under the MIT license. See LICENSE.md for more information.

godot-debug-menu's Issues

Implement memory monitoring.

Hello there!

Since Godot(Atleast in 4.x in my testing) actually supports memory monitoring. I think it should be possible to implement both RAM and VRAM usage in the monitoring as well....

....like this is the final thing that its missing to make this the perfect plugin to monitor performance stats..

V1.1.1 - Crash on project run for Godot 4.1.0 running on MacOS + ARM

StackTrace:

Godot Engine v4.1.stable.official.970459615 - https://godotengine.org
OpenGL API 4.1 Metal - 83.1 - Compatibility - Using Device: Apple - Apple M1 Pro
 
  
  ================================================================
  handle_crash: Program crashed with signal 11
  Engine version: Godot Engine v4.1.stable.official (970459615f6b2b4151742ec6d7ef8559f87fd5c5)
  Dumping the backtrace. Please include this when reporting the bug to the project developer.
  [1] 1   libsystem_platform.dylib            0x00000001a798aa24 _sigtramp + 56
  [2] Ref<DirAccess> DirAccess::_create_builtin<DirAccessUnix>()
  [3] Object::can_translate_messages() const
  [4] VariantInitializer<Vector<Color>>::init(Variant*)
  [5] Object* ClassDB::creator<ENetConnection>()
  [6] Object::get_instance_id() const
  [7] JSON::get_data() const
  [8] VariantInitializer<Vector<Color>>::init(Variant*)
  [9] Object* ClassDB::creator<ENetConnection>()
  [10] RendererRD::ParticlesStorage::_create_particles_material_funcs(RendererRD::MaterialStorage::ShaderData*)
  [11] MutexLock<MutexImpl<std::__1::mutex>>::MutexLock(MutexImpl<std::__1::mutex> const&)
  [12] MutexLock<MutexImpl<std::__1::mutex>>::MutexLock(MutexImpl<std::__1::mutex> const&)
  [13] 13  libsystem_pthread.dylib             0x00000001a795bfa8 _pthread_start + 148
--- Debugging process stopped ---

Game frezes when call get_tree().quit()

Hi,

Tested versions

Reproducible in:

• Godot v4.2.1.stable.
• Debug Menu v1.2.0

System information

Godot v4.2.1.stable - Windows 11 - v10.0.22631 Build 2263 - Vulkan API 1.3.260 - Forward+ - Using Vulkan Device #0: NVIDIA - NVIDIA GeForce RTX 3050 6GB Laptop GPU

Issue description

When you call the method get_tree().quit() with the "debug menu" addon enabled the game freezes.

Minimal reproduction project (MRP)

test.zip

debug menu showing twice

it isn't obvious at first. but if you attach the debug menu to a control node, move it at a different position other than top left, then it shows up twice. the new position and always at the top left position.

Module branch

A branch would be interesting:
A branch module that would be a mirror of the master, but ready to be added via git modules

I created mine here https://github.com/expressobits/godot-debug-menu/tree/module

Default visibility in project settings.

Suggestion / Enchantment
Default visibility in project settings.

I imagine in init it would look something like this:
visible = ProjectSettings.get_setting("debug/settings/debug_menu/visible")

I don't know exactly how, but I believe it would be possible to create this property when the plugin is initialized.

For now I'm using the plugin with this local change and I created this configuration using the Godot UI.
I made this change because I'm using the plugin to see performance on mobile.

Calling "DebugMenu.style" returns "Invalid get index 'style' (on base: 'CanvasLayer')"

The addon is working well with the F3 shortcut, but I tried to make an on screen button to toggle it but calling the DebugMenu.style is for some reason causing the "Invalid get index 'style' (on base: 'CanvasLayer')" error.

The singleton is loaded and everything seems to be working, so why it's retuning a CanvasLayer instead of a script instance is beyond me.

Using Godot 4.1.2.stable. I'll update if I figure out what causes it.

Errors in Godot 4.1-stable-mono

There are many errors at runtime, most of them about red colored errors:

E 0:00:00:0987   is_auto_translating: This function in this node (/root/DebugMenu/DebugMenu/VBoxContainer/Settings) can only be accessed from either the main thread or a thread group. Use call_deferred() instead.
  <C++ Error>    Condition "!is_readable_from_caller_thread()" is true. Returning: (false)
  <C++ Source>   scene/gui/control.cpp:3047 @ is_auto_translating()

many of these errors are Use call_deferred() probably cause of the changes in 4.1
and this :

E 0:00:00:0527   viewport_set_measure_render_time: Condition "!viewport" is true.
  <C++ Source>   servers/rendering/renderer_viewport.cpp:1253 @ viewport_set_measure_render_time()

plugin seems to work fine but not sure if any of the errors impacts the performance or make the calculations incorrect.

Game freezes when closing the game immediately after it starts

Reproducible with Debug Menu v1.2.0 in Godot v4.2.1.stable.mono.official [b09f793f5].

System Information

Godot v4.2.1.stable.mono - Windows 10.0.22631 - Vulkan (Forward+) - dedicated NVIDIA GeForce RTX 3060 Laptop GPU (NVIDIA; 31.0.15.4633) - 12th Gen Intel(R) Core(TM) i7-12700H (20 Threads)

Issue Description

Closing the game immediately after it starts causes the game to freeze when the "Debug Menu" addon is enabled.

Minimal reproduction project (MRP)

Test_Bug.zip

Specify input action in Project Settings

Great plugin!
A suggestion for an improvement would be to be able to specify the name of the action used to toggle the visibility in Godot's Project Settings window. Much like this plugin does:
https://github-production-user-asset-6210df.s3.amazonaws.com/11432672/269932201-ca604382-569f-4367-ba9a-457aaf1d2a6a.png

Setting the default to VISIBLE_DETAILED requires removing visible=false

Setting the default to VISIBLE_DETAILED requires removing visible=false in init

Want to set a default for style.

Release automation?

Hello :) I was browsing around some godot repo's when I came across this. I'm not using 4.x for my current project yet but I will definitely be trying this in the future. You also gave me some great ideas in here with pre-commit for addressing things like line-endings (something I learned the pain of recently), so I wanted to share an idea I thought may be helpful.

I see that this repo follows semver and keepachangelog. Have you considered adding a github action for managing releases - specifically I think this google-release-please action might be well suited. It would require using conventional commit messages, which may not be a welcome tradeoff for some.

If this is something you might be interested in adding to this repo let me know and we can discuss the idea further!

With latest godot getting 4.1 a lot of "This function in this node can only be accessed from either the main thread or a thread group"

About 25 errors similar to this one.

E 0:00:01:0591   get_viewport_rid: This function in this node can only be accessed from either the main thread or a thread group. Use call_deferred() instead.
  <C++ Error>    Condition "!is_readable_from_caller_thread()" is true. Returning: (RID())
  <C++ Source>   scene/main/viewport.cpp:927 @ get_viewport_rid()

README about programatically toggle the menu isn't correct

Using the latest in the master branch, the toggle code examples don't work (https://github.com/godot-extended-libraries/godot-debug-menu#usage).

If I do that, I get errors that the Canvas does not have those properties.

If I instead do this:

var debug_menu = DebugMenu.get_node("DebugMenu")
debug_menu.style = debug_menu.Style.VISIBLE_COMPACT

Then as well the NONE should be HIDDEN instead

var debug_menu = DebugMenu.get_node("DebugMenu")
debug_menu.style = debug_menu.Style.HIDDEN

I'm not sure if this is expected behavior or not, if it is I could open a PR for some README changes.

Can't render the menu in a SubViewport

Prerequisites:

• display/window/size/viewport_width = 640
• display/window/size/viewport_height = 360
• display/window/size/window_width_override = 1280
• display/window/size/window_height_override = 720
• display/window/stretch/mode = "viewport"
• display/window/stretch/aspect = "expand"

The issue:
With the settings above, I've managed to achieve the desired PS1 style of the game. Unfortunately, your debug menu now also looks scaled-down because of this. It's completely unreadable.

What I've tried:
The Godot's documentation suggests using a SubViewport node to overcome this exact problem.

Unfortunately, when I try to place debug_menu.tscn inside this node and then press F3 while in the game, the menu's script breaks on the line 172 (if viewport.content_scale_mode == Window.CONTENT_SCALE_MODE_VIEWPORT:) with the following error: Invalid get index 'content_scale_mode' (on base: 'SubViewport').

How can I render the debug menu inside a separate viewport so that it is displayed in higher resolution than everything else in the game? Thanks in advance!

DebugMenu ends up getting created behind the scene

As title says, the DebugMenu node gets added behind the current scene when it needs to be above.

The most minor problem ever: F3 to "pop up"

Not a big issue of course just a bit annoying that's all:

Having the key detection exclusively when the key is reported is annoying when you can "flicker" the Debug Menu Performance screen by holding the key.

What I replaced it with is of course a super simple solution I've done up myself.
Change to some sort of "just pressed" please. Thanks!

Error when trying to modify `DebugMenu.style` through code

Error

The example says to use that line in order to set the DebugMenu

DebugMenu.style = DebugMenu.Style.VISIBLE_DETAILED

But this error happens.

Invalid get index 'Style' (on base: 'CanvasLayer').

Cause

It stunned me because the script debug_menu.gd extends Control, not CanvasLayer. But I realized that the instantiated autoload is the scene, not the script. And the root node of the scene is a CanvasLayer.