From fc7c06472d3f8102c228057184ed740b47f39819 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Mon, 10 Jul 2023 19:15:40 +0200 Subject: [PATCH] Update Command line tutorial for Godot 4.1 - Update list of command line arguments and descriptions to match Godot 4.1. - Add a legend to clearly denote which CLI arguments are supported in each build type. - Add instructions on making Godot easily available in the `PATH` on Windows and macOS. - Fix invalid backtick usage in some pages. --- tutorials/editor/command_line_tutorial.rst | 304 ++++++++++-------- tutorials/editor/img/editor.svg | 1 + tutorials/editor/img/template_debug.svg | 1 + tutorials/editor/img/template_release.svg | 1 + .../exporting_for_dedicated_servers.rst | 2 +- .../gdextension/gdextension_cpp_example.rst | 2 +- 6 files changed, 179 insertions(+), 132 deletions(-) create mode 100644 tutorials/editor/img/editor.svg create mode 100644 tutorials/editor/img/template_debug.svg create mode 100644 tutorials/editor/img/template_release.svg diff --git a/tutorials/editor/command_line_tutorial.rst b/tutorials/editor/command_line_tutorial.rst index 0f3fd7000f7..617ed12b66e 100644 --- a/tutorials/editor/command_line_tutorial.rst +++ b/tutorials/editor/command_line_tutorial.rst @@ -1,5 +1,3 @@ -:article_outdated: True - .. _doc_command_line_tutorial: Command line tutorial @@ -29,72 +27,87 @@ suitable for this workflow. Command line reference ---------------------- +.. |release| image:: img/template_release.svg +.. |debug| image:: img/template_debug.svg +.. |editor| image:: img/editor.svg + +**Legend** + +- |release| Available in editor builds, debug export templates and release export templates. +- |debug| Available in editor builds and debug export templates only. +- |editor| Only available in editor builds. + +Note that unknown command line arguments have no effect whatsoever. The engine +will **not** warn you when using a command line argument that doesn't exist with a +given build type. + **General options** -+----------------------------+----------------------------------------------------------------------+ -| Command | Description | -+----------------------------+----------------------------------------------------------------------+ -| ``-h``, ``--help`` | Display the list of command line options. | -+----------------------------+----------------------------------------------------------------------+ -| ``--version`` | Display the version string. | -+----------------------------+----------------------------------------------------------------------+ -| ``-v``, ``--verbose`` | Use verbose stdout mode. | -+----------------------------+----------------------------------------------------------------------+ -| ``-q, --quiet`` | Quiet mode, silences stdout messages. Errors are still displayed. | -+----------------------------+----------------------------------------------------------------------+ ++----------------------------+-----------------------------------------------------------------------------+ +| Command | Description | ++----------------------------+-----------------------------------------------------------------------------+ +| ``-h``, ``--help`` | |release| Display the list of command line options. | ++----------------------------+-----------------------------------------------------------------------------+ +| ``--version`` | |release| Display the version string. | ++----------------------------+-----------------------------------------------------------------------------+ +| ``-v``, ``--verbose`` | |release| Use verbose stdout mode. | ++----------------------------+-----------------------------------------------------------------------------+ +| ``-q``, ``--quiet`` | |release| Quiet mode, silences stdout messages. Errors are still displayed. | ++----------------------------+-----------------------------------------------------------------------------+ **Run options** +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Command | Description | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--`` | Separator for user-provided arguments. Following arguments are not used by the engine, but can be read from ``OS.get_cmdline_user_args()``. | +| ``--``, ``++`` | |release| Separator for user-provided arguments. Following arguments are not used by the engine, but can be read from ``OS.get_cmdline_user_args()``. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``-e``, ``--editor`` | Start the editor instead of running the scene (:ref:`target=editor ` must be used). | +| ``-e``, ``--editor`` | |editor| Start the editor instead of running the scene. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``-p``, ``--project-manager`` | Start the Project Manager, even if a project is auto-detected (:ref:`target=editor ` must be used). | +| ``-p``, ``--project-manager`` | |editor| Start the Project Manager, even if a project is auto-detected. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--debug-server `` | Start the editor debug server (``://[:]``, e.g. ``tcp://127.0.0.1:6007``) | +| ``--debug-server `` | |editor| Start the editor debug server (``://[:]``, e.g. ``tcp://127.0.0.1:6007``) | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--quit`` | Quit after the first iteration. | +| ``--quit`` | |release| Quit after the first iteration. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``-l``, ``--language `` | Use a specific locale. ```` follows the format ``language_Script_COUNTRY_VARIANT`` where language is a 2 or 3-letter language code in lower case | -| | and the rest is optional. See :ref:`doc_locales` for more details. | +| ``--quit-after`` | |release| Quit after the given number of iterations. Set to 0 to disable. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--path `` | Path to a project (```` must contain a 'project.godot' file). | +| ``-l``, ``--language `` | |release| Use a specific locale. ```` follows the format ``language_Script_COUNTRY_VARIANT`` where language is a 2 or 3-letter language code in | +| | lowercase and the rest is optional. See :ref:`doc_locales` for more details. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``-u``, ``--upwards`` | Scan folders upwards for 'project.godot' file. | +| ``--path `` | |release| Path to a project (```` must contain a 'project.godot' file). | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--main-pack `` | Path to a pack (.pck) file to load. | +| ``-u``, ``--upwards`` | |release| Scan folders upwards for 'project.godot' file. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--render-thread `` | Render thread mode ('unsafe', 'safe', 'separate'). See :ref:`Thread Model ` | -| | for more details. | +| ``--main-pack `` | |release| Path to a pack (.pck) file to load. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--remote-fs
`` | Remote filesystem (``[:]`` address). | +| ``--render-thread `` | |release| Render thread mode ('unsafe', 'safe', 'separate'). See :ref:`Thread Model ` | +| | for more details. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--remote-fs-password `` | Password for remote filesystem. | +| ``--remote-fs
`` | |release| Remote filesystem (``[:]`` address). | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--audio-driver `` | Audio driver. Use ``--help`` first to display the list of available drivers. | +| ``--remote-fs-password `` | |release| Password for remote filesystem. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--display-driver `` | Display driver (and rendering driver). Use ``--help`` first to display the list of available drivers. | +| ``--audio-driver `` | |release| Audio driver. Use ``--help`` first to display the list of available drivers. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--rendering-method `` | Renderer name. Requires driver support. | +| ``--display-driver `` | |release| Display driver (and rendering driver). Use ``--help`` first to display the list of available drivers. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--rendering-driver `` | Rendering driver (depends on display driver). Use ``--help`` first to display the list of available drivers. | +| ``--rendering-method `` | |release| Renderer name. Requires driver support. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--gpu-index `` | Use a specific GPU (run with ``--verbose`` to get available device list). | +| ``--rendering-driver `` | |release| Rendering driver (depends on display driver). Use ``--help`` first to display the list of available drivers. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--text-driver `` | Text driver ('Fonts', 'BiDi', 'shaping') | +| ``--gpu-index `` | |release| Use a specific GPU (run with ``--verbose`` to get available device list). | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--tablet-driver `` | Pen tablet input driver. | +| ``--text-driver `` | |release| Text driver (Fonts, BiDi, shaping). | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--headless`` | Enable headless mode (``--display-driver headless --audio-driver Dummy``). Useful for servers and with ``--script``. | +| ``--tablet-driver `` | |release| Pen tablet input driver. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--write-movie `` | Run the engine in a way that a movie is written (by default .avi MJPEG). Fixed FPS is forced when enabled, but can be used to change movie FPS. | -| | Disabling vsync can speed up movie writing but makes interaction more difficult. | +| ``--headless`` | |release| Enable headless mode (``--display-driver headless --audio-driver Dummy``). Useful for servers and with ``--script``. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``--disable-vsync`` | Force disabling of vsync. Run the engine in a way that a movie is written (by default .avi MJPEG). | -| | Fixed FPS is forced when enabled, but can be used to change movie FPS. | +| ``--write-movie `` | |release| Run the engine in a way that a movie is written (usually with .avi or .png extension). | +| | ``--fixed-fps`` is forced when enabled, but can be used to change movie FPS. | +| | ``--disable-vsync`` can speed up movie writing but makes interaction more difficult. | +| | ``--quit-after`` can be used to specify the number of frames to write. | +------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------+ **Display options** @@ -102,117 +115,148 @@ Command line reference +------------------------------------+----------------------------------------------------------------------------+ | Command | Description | +------------------------------------+----------------------------------------------------------------------------+ -| ``-f``, ``--fullscreen`` | Request fullscreen mode. | +| ``-f``, ``--fullscreen`` | |release| Request fullscreen mode. | +------------------------------------+----------------------------------------------------------------------------+ -| ``-m``, ``--maximized`` | Request a maximized window. | +| ``-m``, ``--maximized`` | |release| Request a maximized window. | +------------------------------------+----------------------------------------------------------------------------+ -| ``-w``, ``--windowed`` | Request windowed mode. | +| ``-w``, ``--windowed`` | |release| Request windowed mode. | +------------------------------------+----------------------------------------------------------------------------+ -| ``-t``, ``--always-on-top`` | Request an always-on-top window. | +| ``-t``, ``--always-on-top`` | |release| Request an always-on-top window. | +------------------------------------+----------------------------------------------------------------------------+ -| ``--resolution x`` | Request window resolution. | +| ``--resolution x`` | |release| Request window resolution. | +------------------------------------+----------------------------------------------------------------------------+ -| ``--position ,`` | Request window position. | +| ``--position ,`` | |release| Request window position. | +------------------------------------+----------------------------------------------------------------------------+ -| ``--single-window`` | Use a single window (no separate subwindows). | +| ``--screen `` | |release| Request window screen. | +------------------------------------+----------------------------------------------------------------------------+ -| ``--xr-mode `` | Select XR mode (default/off/on). | +| ``--single-window`` | |release| Use a single window (no separate subwindows). | ++------------------------------------+----------------------------------------------------------------------------+ +| ``--xr-mode `` | |release| Select XR mode ('default', 'off', 'on'). | +------------------------------------+----------------------------------------------------------------------------+ **Debug options** -.. note:: - - Debug options are only available in the editor and debug export templates - (they require ``debug`` or ``release_debug`` build targets, see - :ref:`doc_introduction_to_the_buildsystem_target` for more details). - -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| Command | Description | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``-d``, ``--debug`` | Debug (local stdout debugger). | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``-b``, ``--breakpoints`` | Breakpoint list as source::line comma-separated pairs, no spaces (use %20 instead). | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``--profiling`` | Enable profiling in the script debugger. | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``--gpu-profile`` | Show a GPU profile of the tasks that took the most time during frame rendering. | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``--gpu-validation`` | Enable graphics API :ref:`validation layers ` for debugging. | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``--gpu-abort`` | Abort on GPU errors (usually validation layer errors), may help see the problem if your system freezes. | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``--remote-debug `` | Remote debug (``://[:]``, e.g. ``tcp://127.0.0.1:6007``). | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``--debug-collisions`` | Show collision shapes when running the scene. | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``--debug-paths`` | Show path lines when running the scene. | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``--debug-navigation`` | Show navigation polygons when running the scene. | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``--debug-stringnames`` | Print all StringName allocations to stdout when the engine quits. | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``--frame-delay `` | Simulate high CPU load (delay each frame by milliseconds). | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``--time-scale `` | Force time scale (higher values are faster, 1.0 is normal speed). | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``--disable-render-loop`` | Disable render loop so rendering only occurs when called explicitly from script. | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``--disable-crash-handler`` | Disable crash handler when supported by the platform code. | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``--fixed-fps `` | Force a fixed number of frames per second. This setting disables real-time synchronization. | -+------------------------------+---------------------------------------------------------------------------------------------------------+ -| ``--print-fps`` | Print the frames per second to the stdout. | -+------------------------------+---------------------------------------------------------------------------------------------------------+ ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| Command | Description | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``-d``, ``--debug`` | |release| Debug (local stdout debugger). | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``-b``, ``--breakpoints`` | |release| Breakpoint list as source::line comma-separated pairs, no spaces (use ``%20`` instead). | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--profiling`` | |release| Enable profiling in the script debugger. | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--gpu-profile`` | |release| Show a GPU profile of the tasks that took the most time during frame rendering. | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--gpu-validation`` | |release| Enable graphics API :ref:`validation layers ` for debugging. | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--gpu-abort`` | |debug| Abort on GPU errors (usually validation layer errors), may help see the problem if your system freezes. | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--remote-debug `` | |release| Remote debug (``://[:]``, e.g. ``tcp://127.0.0.1:6007``). | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--single-threaded-scene`` | |release| Scene tree runs in single-threaded mode. Sub-thread groups are disabled and run on the main thread. | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--debug-collisions`` | |debug| Show collision shapes when running the scene. | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--debug-paths`` | |debug| Show path lines when running the scene. | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--debug-navigation`` | |debug| Show navigation polygons when running the scene. | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--debug-avoidance`` | |debug| Show navigation avoidance debug visuals when running the scene. | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--debug-stringnames`` | |debug| Print all StringName allocations to stdout when the engine quits. | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--frame-delay `` | |release| Simulate high CPU load (delay each frame by milliseconds). | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--time-scale `` | |release| Force time scale (higher values are faster, 1.0 is normal speed). | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--disable-vsync`` | |release| Forces disabling of vertical synchronization, even if enabled in the project settings. | +| | Does not override driver-level V-Sync enforcement. | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--disable-render-loop`` | |release| Disable render loop so rendering only occurs when called explicitly from script. | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--disable-crash-handler`` | |release| Disable crash handler when supported by the platform code. | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--fixed-fps `` | |release| Force a fixed number of frames per second. This setting disables real-time synchronization. | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--delta-smoothing `` | |release| Enable or disable frame delta smoothing ('enable', 'disable'). | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ +| ``--print-fps`` | |release| Print the frames per second to the stdout. | ++--------------------------------+-----------------------------------------------------------------------------------------------------------------+ **Standalone tools** -+------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| Command | Description | -+------------------------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------+ -| ``-s``, ``--script