diff --git a/tutorials/scripting/debug/debugger_panel.rst b/tutorials/scripting/debug/debugger_panel.rst index 08e5fb975..21f21f004 100644 --- a/tutorials/scripting/debug/debugger_panel.rst +++ b/tutorials/scripting/debug/debugger_panel.rst @@ -6,12 +6,12 @@ Debugger panel Many of Godot's debugging tools, including the debugger, can be found in the debugger panel at the bottom of the screen. Click on **Debugger** to open it. -.. image:: img/overview_debugger.png +.. image:: img/overview_debugger.webp The debugger panel is split into several tabs, each focusing on a specific task. Debugger -++++++++ +-------- The Debugger tab opens automatically when the GDScript compiler reaches a breakpoint in your code. @@ -39,29 +39,118 @@ You can use the buttons in the top-right corner to: This is a current limitation of the GDScript debugger. Errors -++++++ +------ This is where error and warning messages are printed while running the game. You can disable specific warnings in **Project Settings > Debug > GDScript**. Profiler -++++++++ +-------- The profiler is used to see what code is running while your project is in use, -and how that effects performance. A detailed explanation of how to use it can -be found :ref:`here `. +and how that effects performance. + +.. seealso:: + + A detailed explanation of how to use the profiler can be found in the + dedicated :ref:`doc_the_profiler` page. + +Visual Profiler +--------------- + +The Visual Profiler can be used to monitor what is taking the most time when +rendering a frame on the CPU and GPU respectively. This allows tracking sources +of potential CPU and GPU bottlenecks caused by rendering. + +.. warning:: + + The Visual Profiler only measures CPU time taken for rendering tasks, such + as performing draw calls. The Visual Profiler does **not** include CPU time + taken for other tasks such as scripting and physics. Use the standard + Profiler tab to track non-rendering-related CPU tasks. + +To use the visual profiler, run the project, switch to the **Visual Profiler** +tab within the Debugger bottom panel, then click **Start**: + +.. figure:: img/debugger_visual_profiler_results.webp + :alt: Visual Profiler tab after clicking Start, waiting for a few seconds, then clicking Stop + + Visual Profiler tab after clicking **Start**, waiting for a few seconds, then clicking **Stop** + +You will see categories and results appearing as the profiler is running. Graph +lines also appear, with the left side being a CPU framegraph and the right side +being a GPU framegraph. + +Click **Stop** to finish profiling, which will keep the results visible but +frozen in place. Results remain visible after stopping the running project, but +not after exiting the editor. + +Click on result categories on the left to highlight them in the CPU and GPU +graphs on the right. You can also click on the graph to move the cursor to a +specific frame number and highlight the selected data type in the result +categories on the left. + +You can switch the result display between a time value (in milliseconds per +frame) or a percentage of the target frametime (which is currently hardcoded to +16.67 milliseconds, or 60 FPS). + +If framerate spikes occur during profiling, this can cause the graph to be +poorly scaled. Disable **Fit to Frame** so that the graph will zoom onto the 60 +FPS+ portion. + +.. note:: + + Remember that Visual Profiler results can vary **heavily** based on + viewport resolution, which is determined by the window size if using the + ``disabled`` or ``canvas_items`` :ref:`stretch modes + `. + + When comparing results across different runs, make sure to use the same + viewport size for all runs. + +Visual Profiler is supported when using any rendering method (Forward+, Mobile +or Compatibility), but the reported categories will vary depending on the +current rendering method as well as the enabled graphics features. For example, +when using Forward+, a simple 2D scene with shadow-casting lights will result in +the following categories appearing: + +.. figure:: img/debugger_visual_profiler_2d_example.webp + :alt: Example results from a 2D scene in the Visual Profiler + + Example results from a 2D scene in the Visual Profiler + +To give another example with Forward+, a 3D scene with shadow-casting lights and +various effects enabled will result in the following categories enabled: + +.. figure:: img/debugger_visual_profiler_3d_example.webp + :alt: Example results from a 3D scene in the Visual Profiler + + Example results from a 3D scene in the Visual Profiler + +Notice how in the 3D example, several of the categories have **(Parallel)** +appended to their name. This hints that multiple tasks are being performed in +parallel on the GPU. This generally means that disabling only one of the +features involved won't improve performance as much as anticipated, as the other +task still needs to be performed sequentially. Network Profiler -++++++++++++++++ +---------------- The Network Profiler contains a list of all the nodes that communicate over the multiplayer API and, for each one, some counters on the amount of incoming and outgoing network interactions. It also features a bandwidth meter that displays the total bandwidth usage at any given moment. +.. note:: + + The bandwidth meter does **not** take the :ref:`doc_high_level_multiplayer` + API's own compression system into account. This means that changing the + compression algorithm used will not change the metrics reported by the + bandwidth meter. + Monitors -++++++++ +-------- The monitors are graphs of several aspects of the game while its running such as FPS, memory usage, how many nodes are in a scene and more. All monitors keep @@ -75,7 +164,7 @@ is running, you can open it later and see how the values changed. to track arbitrary values in your project. Video RAM -+++++++++ +--------- The **Video RAM** tab shows the video RAM usage of the game while it is running. It provides a list of every resource using video RAM by resource path, the type @@ -85,7 +174,7 @@ using. There is also a total video RAM usage number at the top right of the pane .. image:: img/video_ram.png Misc -++++ +---- The **Misc** tab contains tools to identify the control nodes you are clicking at runtime: diff --git a/tutorials/scripting/debug/img/debugger_visual_profiler_2d_example.webp b/tutorials/scripting/debug/img/debugger_visual_profiler_2d_example.webp new file mode 100644 index 000000000..b5e0c3248 Binary files /dev/null and b/tutorials/scripting/debug/img/debugger_visual_profiler_2d_example.webp differ diff --git a/tutorials/scripting/debug/img/debugger_visual_profiler_3d_example.webp b/tutorials/scripting/debug/img/debugger_visual_profiler_3d_example.webp new file mode 100644 index 000000000..495ebfae0 Binary files /dev/null and b/tutorials/scripting/debug/img/debugger_visual_profiler_3d_example.webp differ diff --git a/tutorials/scripting/debug/img/debugger_visual_profiler_results.webp b/tutorials/scripting/debug/img/debugger_visual_profiler_results.webp new file mode 100644 index 000000000..c6a0e3fc1 Binary files /dev/null and b/tutorials/scripting/debug/img/debugger_visual_profiler_results.webp differ diff --git a/tutorials/scripting/debug/img/overview_debug.png b/tutorials/scripting/debug/img/overview_debug.png deleted file mode 100644 index a7467c152..000000000 Binary files a/tutorials/scripting/debug/img/overview_debug.png and /dev/null differ diff --git a/tutorials/scripting/debug/img/overview_debug.webp b/tutorials/scripting/debug/img/overview_debug.webp new file mode 100644 index 000000000..53d7ac315 Binary files /dev/null and b/tutorials/scripting/debug/img/overview_debug.webp differ diff --git a/tutorials/scripting/debug/img/overview_debugger.png b/tutorials/scripting/debug/img/overview_debugger.png deleted file mode 100644 index dd740db0f..000000000 Binary files a/tutorials/scripting/debug/img/overview_debugger.png and /dev/null differ diff --git a/tutorials/scripting/debug/img/overview_debugger.webp b/tutorials/scripting/debug/img/overview_debugger.webp new file mode 100644 index 000000000..47933063b Binary files /dev/null and b/tutorials/scripting/debug/img/overview_debugger.webp differ diff --git a/tutorials/scripting/debug/img/overview_remote.png b/tutorials/scripting/debug/img/overview_remote.png deleted file mode 100644 index 93a0f0610..000000000 Binary files a/tutorials/scripting/debug/img/overview_remote.png and /dev/null differ diff --git a/tutorials/scripting/debug/img/overview_remote.webp b/tutorials/scripting/debug/img/overview_remote.webp new file mode 100644 index 000000000..6e2dd8440 Binary files /dev/null and b/tutorials/scripting/debug/img/overview_remote.webp differ diff --git a/tutorials/scripting/debug/img/overview_script_editor.png b/tutorials/scripting/debug/img/overview_script_editor.png deleted file mode 100644 index 64eb7fba8..000000000 Binary files a/tutorials/scripting/debug/img/overview_script_editor.png and /dev/null differ diff --git a/tutorials/scripting/debug/img/overview_script_editor.webp b/tutorials/scripting/debug/img/overview_script_editor.webp new file mode 100644 index 000000000..2555aa5b2 Binary files /dev/null and b/tutorials/scripting/debug/img/overview_script_editor.webp differ diff --git a/tutorials/scripting/debug/overview_of_debugging_tools.rst b/tutorials/scripting/debug/overview_of_debugging_tools.rst index 410aa88b3..ccb2f1d3e 100644 --- a/tutorials/scripting/debug/overview_of_debugging_tools.rst +++ b/tutorials/scripting/debug/overview_of_debugging_tools.rst @@ -28,7 +28,7 @@ your game in the editor, which can help you in debugging your game. You can find these options in the **Debug** editor menu. -.. image:: img/overview_debug.png +.. image:: img/overview_debug.webp Here are the descriptions of the options: @@ -81,7 +81,7 @@ The script editor has its own set of debug tools for use with breakpoints and two options. The breakpoint tools can also be found in the **Debugger** tab of the debugger. -.. image:: img/overview_script_editor.png +.. image:: img/overview_script_editor.webp The **Break** button causes a break in the script like a breakpoint would. **Continue** makes the game continue after pausing at a breakpoint. @@ -131,7 +131,7 @@ When running a game in the editor two options appear at the top of the **Scene** dock, **Remote** and **Local**. While using **Remote** you can inspect or change the nodes' parameters in the running project. -.. image:: img/overview_remote.png +.. image:: img/overview_remote.webp .. note:: Some editor settings related to debugging can be found inside the **Editor Settings**, under the **Network > Debug** and **Debugger** sections.