Merge pull request #9124 from chrisl8/update_debugging_tools_for_4.3

Update Overview of Debugging Tools for 4.3.

Author: mhilbrunner

tutorials/scripting/debug/img/customize_run_instances.webp

@@ -35,43 +35,163 @@ 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 for debugging.
+When this option is enabled, using one-click deploy will make the executable
+attempt to connect to this computer's IP so the running project can be debugged.
+This option is intended to be used for remote debugging (typically with a mobile
+device).
+You don't need to enable it to use the GDScript debugger locally.
 
-Small Deploy with Network FS
-++++++++++++++++++++++++++++
+Small Deploy with Network Filesystem
+++++++++++++++++++++++++++++++++++++
 
 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.
+When **Small Deploy with Network Filesystem** 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.
+Also, on Android, the game is deployed using the USB cable to speed up
+deployment.
 
 Visible Collision Shapes
 ++++++++++++++++++++++++
 
-This option makes collision shapes and raycast nodes visible in the running game.
+When this option is enabled, collision shapes and raycast nodes (for 2D and 3D)
+will be visible in the running project.
+
+Visible Paths
++++++++++++++
+
+When this option is enabled, curve resources used by path nodes will be visible
+in the running project.
 
 Visible Navigation
 ++++++++++++++++++
 
-Navigation meshes and polygons will be visible on the running game.
+When this option is enabled, navigation meshes, and polygons will be visible in
+the running project.
 
-Sync Scene Changes
-++++++++++++++++++
+Visible Avoidance
++++++++++++++++++
+
+When this option is enabled, avoidance object shapes, radiuses, and velocities
+will be visible in the running project.
+
+Debug CanvasItem Redraws
+++++++++++++++++++++++++
+
+When this option is enabled, redraw requests of 2D objects will become visible
+(as a short flash) in the running project.
+This is useful to troubleshoot low processor mode.
+
+Synchronize Scene Changes
+++++++++++++++++++++++++++
 
-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.
+When this option is enabled, any changes made to the scene in the editor will be
+replicated in the running project.
+When used remotely on a device, this is more efficient when the network
+filesystem option is enabled.
 
-Sync Script Changes
-+++++++++++++++++++
+Synchronize Script Changes
++++++++++++++++++++++++++++
 
-Any script that is saved will be reloaded on the running game. When used
+When this option is enabled, any changes made to the script in the editor will
+be reloaded in the running project. When used
 remotely on a device, this is more efficient with the network filesystem.
 
+Keep Debug Server Open
+++++++++++++++++++++++
+
+When this option is enabled, the editor debug server will stay open and listen
+for new sessions started outside of the editor itself.
+
+Customize Run Instances...
+++++++++++++++++++++++++++
+
+This opens a dialog allowing you to tell Godot to run multiple instances of the
+game at once, and to specify the command line arguments for each instance. This
+is especially useful when building and debugging multiplayer games.
+
+.. image:: img/customize_run_instances.webp
+
+Enable Multiple Instances
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When this option is enabled, the editor will run multiple instances of the
+project at once when you Run Project.
+
+Below this checkbox is a selector to pick how many instances to run.
+
+Checking the box and setting this to only 1 is the same as not checking this box
+at all.
+
+Main Run Args
+^^^^^^^^^^^^^
+
+These are the arguments that will be passed to **every** instance of the project
+when you Run Project, unless you select "Enabled" under "Override Main Run Args"
+for a specific instance.
+
+Note that these arguments are space-separated.
+
+.. tip::
+
+    These arguments can be accessed in your script by using
+    :ref:`get_cmdline_args<class_OS_method_get_cmdline_args>`.
+
+.. warning::
+
+    Even if you uncheck "Enable Multiple Instances" these arguments will be
+    passed when you Run Project.
+
+Main Feature Tags
+^^^^^^^^^^^^^^^^^
+
+These are the feature tags that will be passed to **every** instance of the
+project when you Run Project, unless you select "Enabled" under "Override Main
+Tags" for a specific instance.
+
+Override Main Run Args
+^^^^^^^^^^^^^^^^^^^^^^
+
+When this is enabled, the arguments in the "Main Run Args" field will **not be
+passed** to this specific instance of the project when you Run Project.
+
+Launch Arguments
+^^^^^^^^^^^^^^^^
+
+These are the arguments that will be passed to this specific instance of the
+project when you Run Project. They will be **combined with** the "Main Run Args"
+unless you select "Enabled" under "Override Main Run Args".
+
+Override Main Tags
+^^^^^^^^^^^^^^^^^^
+
+When this is enabled, the tags in the "Main Feature Tags" field will **not be
+passed** to this specific instance of the project when you Run Project.
+
+Feature Tags
+^^^^^^^^^^^^
+
+These are the feature tags that will be passed to this specific instance of the
+project when you Run Project. They will be **combined with** the "Main Feature
+Tags" unless you select "Enabled" under "Override Main Tags".
+
+.. warning::
+    If you want to pass "User" arguments, that can be accessed with
+    :ref:`get_cmdline_user_args<class_OS_method_get_cmdline_user_args>` then you
+    must prefix them with two dashes **and a space** like `-- one two three`.
+
+    Be aware that these dashes will apply to arguments added later in the
+    "Launch Arguments" on a per instance basis, which can cause some confusion
+    when combining the `Main Run Args` and `Launch Arguments`.
+
+    If you place `-- one two three` in the "Main Run Args" and `-- four five
+    six` in the "Launch Arguments" then the final command line arguments will be
+    `one two three -- four five six`. This is because the `--` is repeated in
+    the "Launch Arguments".
+
+
 .. _doc_debugger_tools_and_options:
 
 Script editor debug tools and options
@@ -102,8 +222,6 @@ The **Break** button causes a break in the script like a breakpoint would.
 **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.
 The **Debug with External Editor** option lets you debug your game with an external editor.
 This option is also accessible in **Editor Settings > Debugger**.