mirror of
https://github.com/godotengine/godot-docs.git
synced 2025-12-31 17:49:03 +03:00
7b98025f2e
This also covers how to create custom loggers. - Remove notice on Windows 10 requirement for `print_rich()` in Output panel, since Godot requires Windows 10 as of 4.5.
261 lines
10 KiB
ReStructuredText
261 lines
10 KiB
ReStructuredText
.. _doc_debugger_panel:
|
|
|
|
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.webp
|
|
|
|
The debugger panel is split into several tabs, each focusing on a specific task.
|
|
|
|
Stack Trace
|
|
-----------
|
|
|
|
The Stack Trace tab opens automatically when the GDScript compiler reaches
|
|
a breakpoint in your code.
|
|
|
|
It gives you a `stack trace <https://en.wikipedia.org/wiki/Stack_trace>`__,
|
|
information about the state of the object, and buttons to control the program's
|
|
execution. When the debugger breaks on a breakpoint, a green triangle arrow is
|
|
visible in the script editor's gutter. This arrow indicates the line of code the
|
|
debugger broke on.
|
|
|
|
.. tip::
|
|
|
|
You can create a breakpoint by clicking the gutter in the left of the script
|
|
editor (on the left of the line numbers). When hovering this gutter, you
|
|
will see a transparent red dot appearing, which turns into an opaque red dot
|
|
after the breakpoint is placed by clicking. Click the red dot again to
|
|
remove the breakpoint. Breakpoints created this way persist across editor
|
|
restarts, even if the script wasn't saved when exiting the editor.
|
|
|
|
You can also use the ``breakpoint`` keyword in GDScript to create a
|
|
breakpoint that is stored in the script itself. Unlike breakpoints created by
|
|
clicking in the gutter, this keyword-based breakpoint is persistent across
|
|
different machines when using version control.
|
|
|
|
You can use the buttons in the top-right corner to:
|
|
|
|
- Skip all breakpoints. That way, you can save breakpoints for future
|
|
debugging sessions.
|
|
- Copy the current error message.
|
|
- **Step Into** the code. This button takes you to the next line of code,
|
|
and if it's a function, it steps line-by-line through the function.
|
|
- **Step Over** the code. This button goes to the next line of code,
|
|
but it doesn't step line-by-line through functions.
|
|
- **Break**. This button pauses the game's execution.
|
|
- **Continue**. This button resumes the game after a breakpoint or pause.
|
|
|
|
.. note::
|
|
|
|
Using the debugger and breakpoints on :ref:`tool scripts <doc_running_code_in_the_editor>`
|
|
is not currently supported. Breakpoints placed in the script editor or using
|
|
the ``breakpoint`` keyword are ignored. You can use print statements to
|
|
display the contents of variables instead.
|
|
|
|
Errors
|
|
------
|
|
|
|
This is where error and warning messages are printed while running the game.
|
|
|
|
You can disable specific warnings in **Project Settings > Debug > GDScript**.
|
|
|
|
Evaluator
|
|
----------
|
|
|
|
This tab contains an expression evaluator, also known as a :abbr:`REPL (Read-Eval-Print Loop)`.
|
|
This is a more powerful complement to the Stack Variables tree available in the Stack Trace tab.
|
|
|
|
When the project is interrupted in the debugger (due to a breakpoint or script
|
|
error), you can enter an expression in the text field at the top. If the project
|
|
is running, the expression field won't be editable, so you will need to set a
|
|
breakpoint first. Expressions can be persisted across runs by unchecking **Clear on Run**,
|
|
although they will be lost when the editor quits.
|
|
|
|
Expressions are evaluated using :ref:`Godot's expression language
|
|
<doc_evaluating_expressions>`, which allows you to perform arithmetic and call
|
|
some functions within the expression. Expressions can refer to member variables,
|
|
or local variables within the same scope as the line the breakpoint is on. You
|
|
can also enter constant values, which makes it usable as a built-in calculator.
|
|
|
|
Consider the following script:
|
|
|
|
::
|
|
|
|
var counter = 0
|
|
|
|
func _process(delta):
|
|
counter += 1
|
|
if counter == 5:
|
|
var text = "Some text"
|
|
breakpoint
|
|
elif counter >= 6:
|
|
var other_text = "Some other text"
|
|
breakpoint
|
|
|
|
If the debugger breaks on the **first** line containing ``breakpoint``, the following
|
|
expressions return non-null values:
|
|
|
|
- **Constant expression:** ``2 * PI + 5``
|
|
- **Member variable:** ``counter``, ``counter ** 2``, ``sqrt(counter)``
|
|
- **Local variable or function parameter:** ``delta``, ``text``, ``text.to_upper()``
|
|
|
|
If the debugger breaks on the **second** line containing ``breakpoint``, the following
|
|
expressions return non-null values:
|
|
|
|
- **Constant expression:** ``2 * PI + 5``
|
|
- **Member variable:** ``counter``, ``counter ** 2``, ``sqrt(counter)``
|
|
- **Local variable or function parameter:** ``delta``, ``other_text``, ``other_text.to_upper()``
|
|
|
|
Profiler
|
|
--------
|
|
|
|
The profiler is used to see what code is running while your project is in use,
|
|
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.
|
|
|
|
.. _doc_debugger_panel_visual_profiler:
|
|
|
|
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**
|
|
|
|
.. tip::
|
|
|
|
You can also check **Autostart**, which will make the visual profiler automatically
|
|
start when the project is run the next time. Note that the **Autostart**
|
|
checkbox's state is not preserved across editor sessions.
|
|
|
|
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
|
|
<doc_multiple_resolutions>`.
|
|
|
|
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.
|
|
|
|
.. note::
|
|
|
|
The Visual Profiler is not supported when using the Compatibility renderer
|
|
on macOS, due to platform limitations.
|
|
|
|
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 it's running such as
|
|
FPS, memory usage, how many nodes are in a scene and more. All monitors keep
|
|
track of stats automatically, so even if one monitor isn't open while the game
|
|
is running, you can open it later and see how the values changed.
|
|
|
|
.. seealso::
|
|
|
|
In addition to the default performance monitors, you can also create
|
|
:ref:`custom performance monitors <doc_custom_performance_monitors>`
|
|
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
|
|
of resource it is, what format it is in, and how much Video RAM that resource is
|
|
using. There is also a total video RAM usage number at the top right of the panel.
|
|
|
|
.. image:: img/video_ram.png
|
|
|
|
Misc
|
|
----
|
|
|
|
The **Misc** tab contains tools to identify the control nodes you are clicking
|
|
at runtime:
|
|
|
|
- **Clicked Control** tells you where the clicked node is in the scene tree.
|
|
- **Clicked Control Type** tells you the type of the node you clicked is.
|