From 73f306f6b0a1187e785fe08a9986d40c896d4286 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Klaim=20=28Jo=C3=ABl=20Lamotte=29?=
 <142265+Klaim@users.noreply.github.com>
Date: Sun, 17 Nov 2024 12:09:34 +0100
Subject: [PATCH] Clarified `--script <script>` expected path values (#9923)

* Clarified expected path value for `--script`

Clarified the kind of paths expected by `--script` and how they are interpreted. [Silent errors in recent Godot versions (regressions)](godotengine/godot#96691) made this even more confusing.

Co-authored-by: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com>

---------

Co-authored-by: A Thousand Ships <96648715+AThousandShips@users.noreply.github.com>
---
 tutorials/editor/command_line_tutorial.rst | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/tutorials/editor/command_line_tutorial.rst b/tutorials/editor/command_line_tutorial.rst
index f240b54bf..ab28667d3 100644
--- a/tutorials/editor/command_line_tutorial.rst
+++ b/tutorials/editor/command_line_tutorial.rst
@@ -188,7 +188,8 @@ given build type.
 +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
 | Command                                                          | Description                                                                                                                                             |
 +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``-s``, ``--script <script>``                                    | |release| Run a script.                                                                                                                                 |
+| ``-s``, ``--script <script>``                                    | |release| Run a script. ``<script>`` must be a resource path relative to the project (``myscript.gd`` will be interpreted as ``res://myscript.gd``)     |
+|                                                                  | or an absolute filesystem path (for example on Windows ``C:/tmp/myscript.gd``)                                                                          |
 +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
 | ``--check-only``                                                 | |release| Only parse for errors and quit (use with ``--script``).                                                                                       |
 +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -288,15 +289,15 @@ For example, the full command for exporting your game (as explained below) might
 
     godot --headless --path path_to_your_project --export-release my_export_preset_name game.exe
 
-When starting from a subdirectory of your project, use the ``--upwards`` argument for Godot to 
+When starting from a subdirectory of your project, use the ``--upwards`` argument for Godot to
 automatically find the ``project.godot`` file by recursively searching the parent directories.
 
-For example, running a scene (as explained below) nested in a subdirectory might look like this 
+For example, running a scene (as explained below) nested in a subdirectory might look like this
 when your working directory is in the same path:
 
 ::
 
-    godot --upwards nested_scene.tscn 
+    godot --upwards nested_scene.tscn
 
 
 ..
@@ -353,7 +354,7 @@ Otherwise, an error will be thrown upon opening the project.
 Running the game
 ----------------
 
-To run the game, execute Godot within the project directory or with the project path as explained above.  
+To run the game, execute Godot within the project directory or with the project path as explained above.
 
 ::
 
@@ -453,6 +454,11 @@ And how to run it:
 If no ``project.godot`` exists at the path, current path is assumed to be the
 current working directory (unless ``--path`` is specified).
 
+The script path will be interpreted as a resource path relative to
+the project, here ``res://sayhello.gd``. You can also use an absolute
+filesystem path instead, which is useful if the script is located
+outside of the project directory.
+
 The first line of ``sayhello.gd`` above is commonly referred to as
 a *shebang*. If the Godot binary is in your ``PATH`` as ``godot``,
 it allows you to run the script as follows in modern Linux