Browse Source

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

(cherry picked from commit 00beb9f6f5eb7b735224b503334e4c25aa925b64)
Rémi Verschelde 2 years ago
parent
commit
4b9efd20fd
1 changed files with 99 additions and 53 deletions
  1. 99 53
      tutorials/io/data_paths.rst

+ 99 - 53
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
 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
 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
 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
 ``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
 file ``character.png`` located in the project's root folder in code with the
 following path: ``res://character.png``.
 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
 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
 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.
 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.
 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:
 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
 ``[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>`.
 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
 device via IndexedDB. (Interaction with the main filesystem can still be performed
 through the :ref:`JavaScript <class_JavaScript>` singleton.)
 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
 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:
 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
 Godot complies with the `XDG Base Directory Specification
 <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`__
 <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
 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
 The `Steam release of Godot <https://store.steampowered.com/app/404790/>`__ uses
 self-contained mode by default.
 self-contained mode by default.