Шляхи до файлів у проектах Godot

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 project and editor files on your and your users' systems.

Роздільники шляху

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\Game, in Godot, you should write C:/Projects/Game.

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 вважає, що проект існує в будь-якій теці, яка містить текстовий файл project.godot, навіть якщо файл пустий. Тека, яка містить цей файл, є кореневою текою проекту.

Ви можете отримати доступ до будь-якого файлу відносно кореневої теки, написавши шлях, що починаються з приставки res://, яка означає ресурси. Наприклад, ви можете отримати доступ до файлу зображення character.png, розташованого в кореневій папці проекту з коду за таким шляхом: res://some_texture.png.

Accessing persistent user data (user://)

Щоб зберігати постійні файли даних, наприклад збереження, або параметри, гри, потрібно використовувати user:// замість res://. Це пов'язано з тим, що під час запуску гри файлова система проекту, швидше за все, буде доступна лише для читання.

The user:// prefix points to a different directory on the user's device. 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 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 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 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.

На настільних платформах фактичні шляхи каталогів для user:// є:

Тип

Розташування

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] базується на назві програми, визначеній у параметрах проекту, але ви можете змінити її на основі кожної платформи, використовуючи теги функцій.

На мобільних платформах цей шлях є унікальним для проекту і недоступний іншим додаткам з міркувань безпеки.

При експорті на HTML5, user:// буде посилатися на віртуальну файлову систему, що зберігається на пристрої через IndexedDB. (Взаємодія з основною файловою системою все ще може здійснюватися через синглтон JavaScript.)

Converting paths to absolute paths or "local" paths

You can use ProjectSettings.globalize_path() to convert a "local" path like res://path/to/file.txt to an absolute OS path. For example, ProjectSettings.globalize_path() can be used to open "local" paths in the OS file manager using 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 ProjectSettings.localize_path(). This only works for absolute paths that point to files or folders in your project's root or user:// folders.

Шляхи до даних редактора

The editor uses different paths for editor data, editor settings, and cache, depending on the platform. By default, these paths are:

Тип

Розташування

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/

Кеш
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 відповідає `специфікації базового каталогу XDG<https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html>`__ на всіх платформах. Ви можете перевизначити змінні середовища після специфікації, щоб змінити шляхи даних редактора і проекту.

Примітка

Якщо ви використовуєте `Godot, упакований як Flatpak<https://flathub.org/apps/details/org.godotengine.Godot>`__, шляхи даних редактора будуть розташовані в вкладених папках у ~/.var/app/org.godotengine.Godot/.

Автономний режим

If you create a file called ._sc_ or _sc_ in the same directory as the 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.

Випуск Steam Godot використовує автономний режим за замовчуванням.

Примітка

Автономний режим ще не підтримується в експортованих проектах. Для читання та запису файлів відносно шляху виконання використовуйте OS.get_executable_path(). Запримітьте, що запис файлів у шляху виконання працює тільки в тому випадку, якщо виконуваний файл розміщений в придатному для запису місці (тобто не Program Files або іншому каталозі, який доступний лише для читання для звичайних користувачів).