From e5f36d30f2dcec26760897cac6cc025c0e5eafac Mon Sep 17 00:00:00 2001
From: Hugo Locurcio <hugo.locurcio@hugo.pro>
Date: Fri, 6 May 2022 18:07:56 +0200
Subject: [PATCH] Improve File paths in Godot projects documentation

- Fix missing word in the beginning of the page.
- Add separate table for exported project data location.
- Fix editor table mentioning `app_userdata`, as it's only relevant
  for project data.
- Remove mention of consoles as Godot currently doesn't officially
  support consoles.
- Mention that self-contained mode isn't supported for use by projects
  yet.
---
 tutorials/io/data_paths.rst | 39 ++++++++++++++++++++++++++++++-------
 1 file changed, 32 insertions(+), 7 deletions(-)

diff --git a/tutorials/io/data_paths.rst b/tutorials/io/data_paths.rst
index 4b35331ba..34de36685 100644
--- a/tutorials/io/data_paths.rst
+++ b/tutorials/io/data_paths.rst
@@ -10,8 +10,8 @@ and where Godot stores user files on your hard-drive.
 Path separators
 ---------------
 
-To as many platforms as possible, Godot only accepts UNIX-style path separators
-(``/``). These work on all platforms, including Windows.
+To make supporting multiple platforms easier, Godot only accepts UNIX-style path
+separators (``/``). These work on all platforms, **including Windows**.
 
 Instead of writing paths like ``C:\Projects``, in Godot, you should write
 ``C:/Projects``.
@@ -35,14 +35,30 @@ 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. On
-mobile and consoles, this path is unique to the project. On desktop, the engine
-stores user files in ``~/.local/share/godot/app_userdata/[project_name]`` on
-Linux, ``~/Library/Application Support/Godot/app_userdata/[project_name]`` on
-macOS (since Catalina) and ``%APPDATA%\Godot\app_userdata\[project_name]`` on Windows.
+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.
+
+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]``                                   |
++-------------------------------+------------------------------------------------------------------------------+
+
 ``[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>`.
 
+On mobile platforms, this path is unique to the project and is not accessible
+by other applications for security reasons.
+
 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.)
@@ -102,3 +118,12 @@ editor.
 
 The `Steam release of Godot <https://store.steampowered.com/app/404790/>`__ uses
 self-contained mode by default.
+
+.. note::
+
+    Self-contained mode is not supported in exported projects yet.
+    To read and write files relative to the executable path, use
+    :ref:`OS.get_executable_path() <class_OS_method_get_executable_path>`.
+    Note that writing files in the executable path only works if the executable
+    is placed in a writable location (i.e. **not** Program Files or another
+    directory that is read-only for regular users).