data_paths.rst 4.2 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495
  1. .. _doc_data_paths:
  2. File paths in Godot projects
  3. ============================
  4. This page explains how file paths work inside Godot projects. You will learn how
  5. to access paths in your projects using the ``res://`` and ``user://`` notations
  6. and where Godot stores user files on your hard-drive.
  7. Path separators
  8. ---------------
  9. To as many platforms as possible, Godot only accepts UNIX-style path separators
  10. (``/``). These work on all platforms, including Windows.
  11. Instead of writing paths like ``C:\Projects``, in Godot, you should write
  12. ``C:/Projects``.
  13. Accessing files in the project folder
  14. -------------------------------------
  15. Godot considers that a project exists in any folder that contains a
  16. ``project.godot`` text file, even if the file is empty. The folder that contains
  17. this file is your project's root folder.
  18. You can access any file relative to it by writing paths starting with
  19. ``res://``, which stands for resources. For example, you can access an image
  20. file ``character.png`` located in the project's root folder in code with the
  21. following path: ``res://some_texture.png``.
  22. Accessing persistent user data
  23. ------------------------------
  24. To store persistent data files, like the player's save or settings, you want to
  25. use ``user://`` instead of ``res://`` as your path's prefix. This is because
  26. when the game is running, the project's file system will likely be read-only.
  27. The ``user://`` prefix points to a different directory on the user's device. On
  28. mobile and consoles, this path is unique to the project. On desktop, the engine
  29. stores user files in ``~/.local/share/godot/app_userdata/Name`` on macOS and
  30. Linux, and ``%APPDATA%/Name`` on Windows. ``Name`` is based on the application
  31. name defined in the Project Settings, but you can override it on a per-platform
  32. basis using :ref:`feature tags <doc_feature_tags>`.
  33. Editor data paths
  34. -----------------
  35. The editor uses different paths for user data, user settings, and cache,
  36. depending on the platform. By default, these paths are:
  37. +---------------+---------------------------------------------------+
  38. | Type | Location |
  39. +===============+===================================================+
  40. | User data | - Windows: ``%APPDATA%\Godot\`` |
  41. | | - macOS: ``~/Library/Application Support/Godot/`` |
  42. | | - Linux: ``~/.local/share/godot/`` |
  43. +---------------+---------------------------------------------------+
  44. | User settings | - Windows: ``%APPDATA%\Godot\`` |
  45. | | - macOS: ``~/Library/Application Support/Godot/`` |
  46. | | - Linux: ``~/.config/godot/`` |
  47. +---------------+---------------------------------------------------+
  48. | Cache | - Windows: ``%TEMP%\Godot\`` |
  49. | | - macOS: ``~/Library/Caches/Godot/`` |
  50. | | - Linux: ``~/.cache/godot/`` |
  51. +---------------+---------------------------------------------------+
  52. - **User data** contains export templates and project-specific data.
  53. - **User settings** contains editor settings, text editor themes, script
  54. templates, etc.
  55. - **Cache** contains temporary data. It can safely be removed when Godot is
  56. closed.
  57. Godot complies with the `XDG Base Directory Specification
  58. <https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`__
  59. on all platforms. You can override environment variables following the
  60. specification to change the editor and project data paths.
  61. .. note:: If you use `Godot packaged as a Flatpak
  62. <https://flathub.org/apps/details/org.godotengine.Godot>`__, the
  63. editor data paths will be located in subfolders in
  64. ``~/.var/app/org.godotengine.Godot/``.
  65. .. _doc_data_paths_self_contained_mode:
  66. Self-contained mode
  67. ~~~~~~~~~~~~~~~~~~~
  68. If you create a file called ``._sc_`` or ``_sc_`` in the same directory as the
  69. editor binary, Godot will enable *self-contained mode*. This mode makes Godot
  70. write all user data to a directory named ``editor_data/`` in the same directory
  71. as the editor binary. You can use it to create a portable installation of the
  72. editor.
  73. The `Steam release of Godot <https://store.steampowered.com/app/404790/>`__ uses
  74. self-contained mode by default.