From 9329aa8b51b6fc5fa849402a41772879c20d96c2 Mon Sep 17 00:00:00 2001 From: Nathan Lovato Date: Wed, 22 Jan 2020 19:18:27 -0600 Subject: [PATCH] Edit overview_of_debugging_tools (#2999) Rewrite the intro to explain what the reader will find in this guide and list debugging tools right away. Review grammar and improve the text's clarity. --- .../debug/overview_of_debugging_tools.rst | 187 +++++++++++------- 1 file changed, 112 insertions(+), 75 deletions(-) diff --git a/tutorials/debug/overview_of_debugging_tools.rst b/tutorials/debug/overview_of_debugging_tools.rst index 09be9b444..1dd46e488 100644 --- a/tutorials/debug/overview_of_debugging_tools.rst +++ b/tutorials/debug/overview_of_debugging_tools.rst @@ -3,18 +3,24 @@ Overview of debugging tools =========================== -Introduction ------------- +This guide will give you an overview of the available debugging tools in the +engine. -When developing your game, you want to test your game and debug when problems occur. Godot provides several debugging options and -tools which aid your debugging process. There are the debug dropdown options, Script editor debug options, debug project settings, -and the debugger. +Godot comes with a powerful debugger and profilers to track down bugs, inspect +your game at runtime, monitor essential metrics, and measure performances. +It also offers options to visualize collision boxes and navigation polygons +in the running game. -Debug dropdown options ----------------------- +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. -There are a few options that you can enable when running your game in the editor which can help you in debugging your game. -These options are located in ``DEBUG`` in the main menus. +Debug menu options +------------------ + +There are a few common debug options you can toggle on or off when running +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 @@ -23,18 +29,24 @@ Here are the descriptions of the options: Deploy with Remote Debug ++++++++++++++++++++++++ -When exporting and deploying, the resulting executable will attempt to connect to the IP of your computer, in order to be debugged. +When exporting and deploying, the resulting executable will attempt to connect +to the IP of your computer for debugging. Small Deploy with Network FS ++++++++++++++++++++++++++++ -Export or deploy will produce minimal executable. The filesystem will be provided from the project by the editor over the network. -On Android, deploy will use the USB cable for faster performance. This option speeds up testing for games with a large footprint. +This option speeds up testing for games with a large footprint on remote devices. + +When **Small Deploy with Network FS** is on, instead of exporting the full game, +deploying the game builds a minimal executable. The editor then provides files +from the project over the network. + +Also, on Android, the game is deployed using the USB cable to speed up deployment. Visible Collision Shapes ++++++++++++++++++++++++ -Collision shapes and raycast nodes(for 2D and 3D) will be visible on the running game. +This option makes collision shapes and raycast nodes visible in the running game. Visible Navigation ++++++++++++++++++ @@ -44,80 +56,89 @@ Navigation meshes and polygons will be visible on the running game. Sync Scene Changes ++++++++++++++++++ -Any changes made to the scene in the editor will be replicated in the running game. -When used remotely on a device, this is more efficient with network filesystem. +With this option, any change you make to a scene in the editor at runtime +appears instantly. When used remotely on a device, this is more efficient +with the network filesystem. Sync Script Changes +++++++++++++++++++ -Any script that is saved will be reloaded on the running game. -When used remotely on a device, this is more efficient with network filesystem. +Any script that is saved will be reloaded on the running game. When used +remotely on a device, this is more efficient with the network filesystem. Script editor debug tools and options ------------------------------------- -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. +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.png -The ``Break`` button causes a break in the script like a breakpoint would. ``Continue`` -makes the game continue after pausing at a breakpoint. ``Step Over`` goes to the next -line of code, and ``Step Into`` goes into a function if possible, otherwise it does the -same thing as ``Step Over``. +The **Break** button causes a break in the script like a breakpoint would. +**Continue** makes the game continue after pausing at a breakpoint. +**Step Over** goes to the next line of code, and **Step Into** goes into +a function if possible. Otherwise, it does the same thing as **Step Over**. -The ``Keep Debugger Open`` option keeps the debugger open after a scene has been closed. -And the ``Debug with External Editor`` option lets you debug your game with an external -editor. +The **Keep Debugger Open** option keeps the debugger open after a scene +has been closed. And the **Debug with External Editor** option lets you +debug your game with an external editor. Debug project settings ---------------------- -In the project settings there is a "Debug" category with three sub categories which -control different things. +In the project settings, there is a **Debug** category with three subcategories +which control different things. Settings ++++++++ -These are some general settings such as printing the current FPS to the Output panel, the -maximum amount of functions when profiling and others. +These are some general settings such as printing the current FPS +to the **Output** panel, the maximum amount of functions when profiling +and others. GDScript ++++++++ -These settings allow you to turn specific GDScript warnings, such as an unused variable, on -or off. You can also turn off warnings completely. +These settings allow you to toggle specific GDScript warnings, such as for +unused variables. You can also turn off warnings completely. Shapes ++++++ -Shapes is where you can adjust the color of shapes that only appear for debugging purposes, -such as collision and navigation shapes. +Shapes are where you can adjust the color of shapes that only appear for +debugging purposes, such as collision and navigation shapes. Debugging tools --------------- -The ``Debugger`` can be found in Godot's bottom panel. Click on it and the panel expands -to show all the debugging tools. +You can find the debugger in the bottom panel. Click on **Debugger** to open it. .. image:: img/overview_debugger.png -There are multiple parts of the debugger, each is for a specific task. +The debugger is split into several tabs, each focusing on a specific task. Debugger ++++++++ -The debugger tab is for working with breakpoints in the script. When a script reaches a breakpoint -this panel gives you information on it. +The debugger tab opens automatically when the GDScript compiler reaches +a breakpoint in your code. -The buttons in the top right can be used respectively to: +It gives you a `stack trace `__, +information about the state of the object, and buttons to control +the program's execution. -- Skip all defined breakpoints, without removing them (so you can toggle them on or off while testing). +You can use the buttons in the top-right to: + +- Skip all breakpoints. That way, you can save breakpoints for future + debugging sessions. - Copy the current error message. -- Step Into goes to the next line of code, and if it's a function, it step line by line through the function. -- Step Over goes to the next line of code, but does not go down into function code. -- Break pauses the game like a breakpoint would. -- Continue resumes the game after a breakpoint or pause. +- **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. Errors ++++++ @@ -127,56 +148,72 @@ This is where errors and warning messages are printed while running the game. Profiler ++++++++ -The profiler is used to show why individual frames take as long as they do to process and render. +The debugger comes with three profilers for your processor, network operations, +and video memory. -Unlike other debugging tools the profiler does not start automatically. It can be started at any -time during gameplay by pressing the start button. You can even start the profiler before opening -the game to profile start up performance. It can also be started and stopped while the game is -running without losing information from when it was last running. The information it records won't -go away unless you click clear, or close the game, reopen it and start the profiler again. +The profiler is used to show why individual frames take as long as they do +to process and render. -After starting and stopping the profiler you should see things being kept track of on the left and -a graph on the right. The items listed on the left are everything that contributes to frame time, -and they should each have a value for time and calls for the current frame you are looking at. +Unlike other debugging tools, the profiler does not start automatically. It can +be started at any time during gameplay by pressing the start button. You can +even start the profiler before opening the game to profile startup performance. +It can also be started and stopped while the game is running without losing +information from when it was last running. The information it records won't +go away unless you click clear, or close the game, reopen it and start +the profiler again. -The frame number in the top right tells you which frame you are currently looking at. You can change -this by using the up or down arrows, typing in the frame number, or clicking on the graph. +After starting and stopping the profiler you should see things being kept track +of on the left and a graph on the right. The items listed on the left are +everything that contributes to frame time, and they should each have a value +for time and calls for the current frame you are looking at. -If you want to add something to your graph, or think it looks too cluttered, you can check and -uncheck the box next to an item to add or remove it from the graph. +The frame number in the top right tells you which frame you are currently +looking at. You can change this by using the up or down arrows, typing in the +frame number, or clicking on the graph. + +If you want to add something to your graph, or think it looks too cluttered, +you can check and uncheck the box next to an item to add or remove it +from the graph. 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 +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. 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 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. +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 +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. -Video Mem -+++++++++ +Video Memory +++++++++++++ -Video Mem list the video memory usage of the running game and which resource is using it. +The **Video Mem** tab lists the video memory usage of the running game +and the resources using it. Misc ++++ -Misc is used to identify which control node you are clicking while the game is running. "Clicked Control" -shows where on the scene tree the node is. "Clicked Control Type" tells you what type of node it is. +The **Misc** tab contains tools to identify the control nodes you are clicking +at runtime: -Remote in Scene dock +- **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. + +Remote in scene dock -------------------- -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 game. +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 -.. note:: Some editor settings related to debugging can be found inside the ``Editor Settings``, under Network>Debug and Debugger sections. +.. note:: Some editor settings related to debugging can be found inside + the **Editor Settings**, under the **Network > Debug** and **Debugger** sections.