diff --git a/tutorials/scripting/debug/img/overview_output.webp b/tutorials/scripting/debug/img/overview_output.webp new file mode 100644 index 000000000000..eb1d50880734 Binary files /dev/null and b/tutorials/scripting/debug/img/overview_output.webp differ diff --git a/tutorials/scripting/debug/index.rst b/tutorials/scripting/debug/index.rst index 6975087fa977..50f961169d76 100644 --- a/tutorials/scripting/debug/index.rst +++ b/tutorials/scripting/debug/index.rst @@ -8,6 +8,7 @@ Debug :name: toc-learn-features-debug overview_of_debugging_tools + output_panel debugger_panel the_profiler custom_performance_monitors diff --git a/tutorials/scripting/debug/output_panel.rst b/tutorials/scripting/debug/output_panel.rst new file mode 100644 index 000000000000..7ae74d6573e4 --- /dev/null +++ b/tutorials/scripting/debug/output_panel.rst @@ -0,0 +1,93 @@ +.. _doc_output_panel: + +Output panel +============ + +The output panel is found at the bottom of the screen. Click on **Output** to open it. + +.. image:: img/overview_output.webp + +The output panel provides several features to make viewing text printed by the +project (and editor) easier. + +.. note:: + + The output panel automatically opens when running a project by default. + You can control this behavior by changing the **Run > Bottom Panel > Action on Play** + editor setting. + +Message categories +------------------ + +Four message categories are available: + +- **Log:** Standard messages printed by the project. Displayed in white or black + (depending on the editor theme). +- **Error:** Messages printed by the project or editor that report important + information, but do not indicate a failure. Displayed in yellow. +- **Warning:** Messages printed by the project or editor that indicate a failure + of some kind. Displayed in red. +- **Editor:** Messages printed by the editor, typically intended to be traces of + undo/redo actions. Displayed in gray. + +Filtering messages +------------------ + +By clicking on the buttons on the right, you can hide certain message categories. +This can make it easier to find specific messages you're looking for. + +You can also filter messages by their text content using the **Filter Messages** box +at the bottom of the Output panel. + +Clearing messages +----------------- + +When running the project, existing messages are automatically cleared by default. This +is controlled by the **Run > Output > Always Clear Output on Play** editor setting. +Additionally, you can manually clear messages by clicking the "cleaning brush" icon +in the top-right corner of the Output panel. + +Printing messages +----------------- + +Several methods are available to print messages: + +- :ref:`print() `: Prints a message. + This method accepts multiple arguments which are concatenated together upon printing. +- :ref:`print_rich() `: Same as ``print()``, + but BBCode can be used to format the text that is printed (see below). +- :ref:`push_error() `: Prints an error message. + When an error is printed in a running project, it's displayed in the **Debugger > Errors** + tab instead. +- :ref:`push_warning() `: Prints a warning message. + When a warning is printed in a running project, it's displayed in the **Debugger > Errors** + tab instead. + +To get more advanced formatting capabilities, consider using +:ref:`doc_gdscript_printf` along with the above printing functions. + +.. _doc_bottom_panel_printing_rich_text: + +Printing rich text +^^^^^^^^^^^^^^^^^^ + +Using :ref:`print_rich() `, you can print +rich text to the editor Output panel and standard output (visible when the user +runs the project from a terminal). This works by converting the BBCode to +`ANSI escape codes `__ that the +terminal understands. + +In the editor output, all BBCode tags are recognized as usual. In the terminal +output, only a subset of BBCode tags will work, as documented in the linked +``print_rich()`` method description above. In the terminal, the colors will look +different depending on the user's theme, while colors in the editor will use the +same colors as they would in the project. + +.. note:: + + ANSI escape code support varies across terminal emulators. On Windows, only + Windows 10 and later can display ANSI escape codes in its default terminal + application. + + The exact colors displayed in terminal output also depend on the terminal + theme chosen by the user. diff --git a/tutorials/scripting/debug/overview_of_debugging_tools.rst b/tutorials/scripting/debug/overview_of_debugging_tools.rst index e0e13e01b8e3..c8f487791dc3 100644 --- a/tutorials/scripting/debug/overview_of_debugging_tools.rst +++ b/tutorials/scripting/debug/overview_of_debugging_tools.rst @@ -14,6 +14,12 @@ in the running game. Finally, you have options to debug the game running on a remote device and to reload changes to your scenes or your code while the game is running. +Output Panel +-------------- + +The output panel allows you to see text printed by the project, but also by the editor (e.g. from ``@tool`` scripts). +You can find information about in :ref:`doc_output_panel`. + Debugger Panel -------------- @@ -251,7 +257,7 @@ GDScript ++++++++ These settings allow you to toggle specific GDScript warnings, such as for -unused variables. You can also turn off warnings completely. See +unused variables. You can also turn off warnings completely. See :ref:`doc_gdscript_warning_system` for more information. Shader Language diff --git a/tutorials/scripting/gdscript/gdscript_documentation_comments.rst b/tutorials/scripting/gdscript/gdscript_documentation_comments.rst index 83957a93c00b..731e3d4b34b4 100644 --- a/tutorials/scripting/gdscript/gdscript_documentation_comments.rst +++ b/tutorials/scripting/gdscript/gdscript_documentation_comments.rst @@ -223,6 +223,8 @@ This can be especially useful for plugin and library creators. While technically you can use both ``@deprecated`` and ``@experimental`` tags on the same class/member, this is not recommended as it is against common conventions. +.. _doc_gdscript_documentation_comments_bbcode_and_class_reference: + BBCode and class reference -------------------------- diff --git a/tutorials/ui/bbcode_in_richtextlabel.rst b/tutorials/ui/bbcode_in_richtextlabel.rst index 68d3d0992f15..18ae2e2f25e8 100644 --- a/tutorials/ui/bbcode_in_richtextlabel.rst +++ b/tutorials/ui/bbcode_in_richtextlabel.rst @@ -21,8 +21,11 @@ scrollbar is automatically displayed if the text does not fit within the control's size. The scrollbar can be disabled by unchecking the **Scroll Active** property in the RichTextLabel inspector. -Note that the BBCode tags can also be used to some extent in the XML source of -the class reference. For more information, see :ref:`doc_class_reference_primer`. +Note that the BBCode tags can also be used to some extent for other use cases: + +- BBCode can be used to :ref:`format comments in the XML source of the class reference `. +- BBCode can be used in :ref:`GDScript documentation comments `. +- BBCode can be used when :ref:`printing rich text to the Output bottom panel `. .. seealso::