Data paths: Fix editor paths and improve docs on custom user dir

(cherry picked from commit 00beb9f6f5eb7b735224b503334e4c25aa925b64)

tutorials/io/data_paths.rst

@@ -4,20 +4,29 @@ File paths in Godot projects
 ============================
 
 This page explains how file paths work inside Godot projects. You will learn how
-to access paths in your projects using the ``res://`` and ``user://`` notations
-and where Godot stores user files on your hard-drive.
+to access paths in your projects using the ``res://`` and ``user://`` notations,
+and where Godot stores project and editor files on your and your users' systems.
 
 Path separators
 ---------------
 
-To make supporting multiple platforms easier, Godot only accepts UNIX-style path
-separators (``/``). These work on all platforms, **including Windows**.
+To make supporting multiple platforms easier, Godot uses **UNIX-style path
+separators** (forward slash ``/``). These work on all platforms, **including
+Windows**.
 
-Instead of writing paths like ``C:\Projects``, in Godot, you should write
-``C:/Projects``.
+Instead of writing paths like ``C:\Projects\Game``, in Godot, you should write
+``C:/Projects/Game``.
 
-Accessing files in the project folder
--------------------------------------
+Windows-style path separators (backward slash ``\``) are also supported in some
+path-related methods, but they need to be doubled (``\\``), as ``\`` is normally
+used as an escape for characters with a special meaning.
+
+This makes it possible to work with paths returned by other Windows
+applications. We still recommend using only forward slashes in your own code to
+guarantee that everything will work as intended.
+
+Accessing files in the project folder (``res://``)
+--------------------------------------------------
 
 Godot considers that a project exists in any folder that contains a
 ``project.godot`` text file, even if the file is empty. The folder that contains
@@ -28,30 +37,52 @@ You can access any file relative to it by writing paths starting with
 file ``character.png`` located in the project's root folder in code with the
 following path: ``res://character.png``.
 
-Accessing persistent user data
-------------------------------
+Accessing persistent user data (``user://``)
+--------------------------------------------
 
 To store persistent data files, like the player's save or settings, you want to
 use ``user://`` instead of ``res://`` as your path's prefix. This is because
 when the game is running, the project's file system will likely be read-only.
 
 The ``user://`` prefix points to a different directory on the user's device.
-Unlike ``res://``, the directory pointed at by ``user://`` is *guaranteed* to be
-writable to, even in an exported project.
+Unlike ``res://``, the directory pointed at by ``user://`` is created
+automatically and *guaranteed* to be writable to, even in an exported project.
+
+The location of the ``user://`` folder depends on what is configured in the
+Project Settings:
+
+- By default, the ``user://`` folder is created within Godot's
+  :ref:`editor data path <doc_data_paths_editor_data_paths>` in the
+  ``app_userdata/[project_name]`` folder. This is the default so that prototypes
+  and test projects stay self-contained within Godot's data folder.
+- If :ref:`application/config/use_custom_user_dir <class_ProjectSettings_property_application/config/use_custom_user_dir>`
+  is enabled in the Project Settings, the ``user://`` folder is created **next
+  to** Godot's editor data path, i.e. in the standard location for applications
+  data.
+
+  * By default, the folder name will be inferred from the project name, but it
+    can be further customized with
+    :ref:`application/config/custom_user_dir_name <class_ProjectSettings_property_application/config/custom_user_dir_name>`.
+    This path can contain path separators, so you can use it e.g. to group
+    projects of a given studio with a ``Studio Name/Game Name`` structure.
 
 On desktop platforms, the actual directory paths for ``user://`` are:
 
-+-------------------------------+------------------------------------------------------------------------------+
-| Type                          | Location                                                                     |
-+===============================+==============================================================================+
-| User data                     | - Windows: ``%APPDATA%\Godot\app_userdata\[project_name]``                   |
-|                               | - macOS: ``~/Library/Application Support/Godot/app_userdata/[project_name]`` |
-|                               | - Linux: ``~/.local/share/godot/app_userdata/[project_name]``                |
-+-------------------------------+------------------------------------------------------------------------------+
-| User data                     | - Windows: ``%APPDATA%\[project_name]``                                      |
-| (when ``use_custom_user_dir`` | - macOS: ``~/Library/Application Support/[project_name]``                    |
-| project setting is ``true``)  | - Linux: ``~/.local/share/[project_name]``                                   |
-+-------------------------------+------------------------------------------------------------------------------+
++---------------------+------------------------------------------------------------------------------+
+| Type                | Location                                                                     |
++=====================+==============================================================================+
+| Default             | | Windows: ``%APPDATA%\Godot\app_userdata\[project_name]``                   |
+|                     | | macOS: ``~/Library/Application Support/Godot/app_userdata/[project_name]`` |
+|                     | | Linux: ``~/.local/share/godot/app_userdata/[project_name]``                |
++---------------------+------------------------------------------------------------------------------+
+| Custom dir          | | Windows: ``%APPDATA%\[project_name]``                                      |
+|                     | | macOS: ``~/Library/Application Support/[project_name]``                    |
+|                     | | Linux: ``~/.local/share/[project_name]``                                   |
++---------------------+------------------------------------------------------------------------------+
+| Custom dir and name | | Windows: ``%APPDATA%\[custom_user_dir_name]``                              |
+|                     | | macOS: ``~/Library/Application Support/[custom_user_dir_name]``            |
+|                     | | Linux: ``~/.local/share/[custom_user_dir_name]``                           |
++---------------------+------------------------------------------------------------------------------+
 
 ``[project_name]`` is based on the application name defined in the Project Settings, but
 you can override it on a per-platform basis using :ref:`feature tags <doc_feature_tags>`.
@@ -63,37 +94,51 @@ On HTML5 exports, ``user://`` will refer to a virtual filesystem stored on the
 device via IndexedDB. (Interaction with the main filesystem can still be performed
 through the :ref:`JavaScript <class_JavaScript>` singleton.)
 
+Converting paths to absolute paths or "local" paths
+---------------------------------------------------
+
+You can use :ref:`ProjectSettings.globalize_path() <class_ProjectSettings_method_globalize_path>`
+to convert a "local" path like ``res://path/to/file.txt`` to an absolute OS path.
+For example, :ref:`ProjectSettings.globalize_path() <class_ProjectSettings_method_globalize_path>`
+can be used to open "local" paths in the OS file manager
+using :ref:`OS.shell_open() <class_OS_method_shell_open>` since it only accepts
+native OS paths.
+
+To convert an absolute OS path to a "local" path starting with ``res://``
+or ``user://``, use :ref:`ProjectSettings.localize_path() <class_ProjectSettings_method_localize_path>`.
+This only works for absolute paths that point to files or folders in your
+project's root or ``user://`` folders.
+
+.. _doc_data_paths_editor_data_paths:
+
 Editor data paths
 -----------------
 
-The editor uses different paths for user data, user settings, and cache,
+The editor uses different paths for editor data, editor settings, and cache,
 depending on the platform. By default, these paths are:
 
-+-------------------------------+----------------------------------------------------------------+
-| Type                          | Location                                                       |
-+===============================+================================================================+
-| User data                     | - Windows: ``%APPDATA%\Godot\app_userdata\[project_name]``     |
-|                               | - macOS: ``~/Library/Application Support/Godot/[project_name]``|
-|                               | - Linux: ``~/.local/share/godot/[project_name]``               |
-+-------------------------------+----------------------------------------------------------------+
-| User data                     | - Windows: ``%APPDATA%\[project_name]``                        |
-| (when ``use_custom_user_dir`` | - macOS: ``~/Library/Application Support/[project_name]``      |
-| project setting is ``true``)  | - Linux: ``~/.local/share/[project_name]``                     |
-+-------------------------------+----------------------------------------------------------------+
-| User settings                 | - Windows: ``%APPDATA%\Godot\``                                |
-|                               | - macOS: ``~/Library/Application Support/Godot/``              |
-|                               | - Linux: ``~/.config/godot/``                                  |
-+-------------------------------+----------------------------------------------------------------+
-| Cache                         | - Windows: ``%TEMP%\Godot\``                                   |
-|                               | - macOS: ``~/Library/Caches/Godot/``                           |
-|                               | - Linux: ``~/.cache/godot/``                                   |
-+-------------------------------+----------------------------------------------------------------+
-
-- **User data** contains export templates and project-specific data.
-- **User settings** contains editor settings, text editor themes, script
-  templates, etc.
-- **Cache** contains temporary data. It can safely be removed when Godot is
-  closed.
++-----------------+---------------------------------------------------+
+| Type            | Location                                          |
++=================+===================================================+
+| Editor data     | | Windows: ``%APPDATA%\Godot\``                   |
+|                 | | macOS: ``~/Library/Application Support/Godot/`` |
+|                 | | Linux: ``~/.local/share/godot/``                |
++-----------------+---------------------------------------------------+
+| Editor settings | | Windows: ``%APPDATA%\Godot\``                   |
+|                 | | macOS: ``~/Library/Application Support/Godot/`` |
+|                 | | Linux: ``~/.config/godot/``                     |
++-----------------+---------------------------------------------------+
+| Cache           | | Windows: ``%TEMP%\Godot\``                      |
+|                 | | macOS: ``~/Library/Caches/Godot/``              |
+|                 | | Linux: ``~/.cache/godot/``                      |
++-----------------+---------------------------------------------------+
+
+- **Editor data** contains export templates and project-specific data.
+- **Editor settings** contains the main editor settings configuration file as
+  well as various other user-specific customizations (editor layouts, feature
+  profiles, script templates, etc.).
+- **Cache** contains data generated by the editor, or stored temporarily.
+  It can safely be removed when Godot is closed.
 
 Godot complies with the `XDG Base Directory Specification
 <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`__
@@ -111,10 +156,11 @@ Self-contained mode
 ~~~~~~~~~~~~~~~~~~~
 
 If you create a file called ``._sc_`` or ``_sc_`` in the same directory as the
-editor binary, Godot will enable *self-contained mode*. This mode makes Godot
-write all user data to a directory named ``editor_data/`` in the same directory
-as the editor binary. You can use it to create a portable installation of the
-editor.
+editor binary (or in `MacOS/Contents/` for a macOS editor .app bundle), Godot
+will enable *self-contained mode*.
+This mode makes Godot write all editor data, settings, and cache to a directory
+named ``editor_data/`` in the same directory as the editor binary.
+You can use it to create a portable installation of the editor.
 
 The `Steam release of Godot <https://store.steampowered.com/app/404790/>`__ uses
 self-contained mode by default.