From bd90abed7e7efa3cb8f516c7594972b67cf9e612 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?R=C3=A9mi=20Verschelde?= Date: Thu, 1 Sep 2022 13:46:20 +0200 Subject: [PATCH] Data paths: Fix editor paths and improve docs on custom user dir (cherry picked from commit 00beb9f6f5eb7b735224b503334e4c25aa925b64) --- tutorials/io/data_paths.rst | 150 +++++++++++++++++++++++------------- 1 file changed, 98 insertions(+), 52 deletions(-) diff --git a/tutorials/io/data_paths.rst b/tutorials/io/data_paths.rst index 7774e40f2..4b4d13551 100644 --- a/tutorials/io/data_paths.rst +++ b/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 ` 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 ` + 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 `. + 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 `. @@ -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 ` singleton.) +Converting paths to absolute paths or "local" paths +--------------------------------------------------- + +You can use :ref:`ProjectSettings.globalize_path() ` +to convert a "local" path like ``res://path/to/file.txt`` to an absolute OS path. +For example, :ref:`ProjectSettings.globalize_path() ` +can be used to open "local" paths in the OS file manager +using :ref:`OS.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() `. +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/`` | -+-------------------------------+----------------------------------------------------------------+ ++-----------------+---------------------------------------------------+ +| 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/`` | ++-----------------+---------------------------------------------------+ -- **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. +- **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 `__ @@ -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 `__ uses self-contained mode by default.