Merge pull request #7271 from Calinou/gdscript-add-breakpoints

Document how to add breakpoints in the editor and using `breakpoint`

Author: mhilbrunner

tutorials/scripting/debug/debugger_panel.rst

@@ -17,8 +17,24 @@ The Debugger 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.
+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 iself. 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:
 
@@ -32,6 +48,8 @@ You can use the buttons in the top-right corner to:
 - **Break**. This button pauses the game's execution.
 - **Continue**. This button resumes the game after a breakpoint or pause.
 
+
+
 .. warning::
 
     Breakpoints won't break on code if it's

tutorials/scripting/debug/overview_of_debugging_tools.rst

@@ -81,6 +81,20 @@ 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.
 
+.. 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 iself. Unlike breakpoints created by
+    clicking in the gutter, this keyword-based breakpoint is persistent across
+    different machines when using version control.
+
 .. image:: img/overview_script_editor.webp
 
 The **Break** button causes a break in the script like a breakpoint would.
@@ -93,6 +107,10 @@ has been closed.
 The **Debug with External Editor** option lets you debug your game with an external editor.
 This option is also accessible in **Editor Settings > Debugger**.
 
+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.
+
 .. warning::
 
     Breakpoints won't break on code if it's

tutorials/scripting/gdscript/gdscript_basics.rst

@@ -199,7 +199,8 @@ in case you want to take a look under the hood.
 +------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
 | var        | Defines a variable.                                                                                                                               |
 +------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
-| breakpoint | Editor helper for debugger breakpoints.                                                                                                           |
+| breakpoint | Editor helper for debugger breakpoints. Unlike breakpoints created by clicking in the gutter, ``breakpoint`` is stored in the script itself.      |
+|            | This makes it persistent across different machines when using version control.                                                                    |
 +------------+---------------------------------------------------------------------------------------------------------------------------------------------------+
 | preload    | Preloads a class or variable. See `Classes as resources`_.                                                                                        |
 +------------+---------------------------------------------------------------------------------------------------------------------------------------------------+