Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Пути файлов в проектах Godot

На этой странице объясняется, как работают пути к файлам в проектах Godot. Вы узнаете, как получать доступ к путям в своих проектах с помощью обозначений res:// и user://, а также где Godot хранит файлы проектов и редакторов в вашей системе и системах ваших пользователей.

Разделители путей

Для упрощения поддержки нескольких платформ Godot использует разделители путей в стиле UNIX (косая черта /). Они работают на всех платформах, включая Windows.

Вместо того, чтобы прописывать пути вида C:\Projects\Game, в Godot следует писать C:/Projects/Game.

Разделители путей в стиле Windows (обратная косая черта \) также поддерживаются в некоторых методах, связанных с путями, но их необходимо дублировать (\\), поскольку \ обычно используется в качестве экранированного символа для символов со специальным значением.

Это позволяет работать с путями, возвращаемыми другими приложениями Windows. Мы по-прежнему рекомендуем использовать в вашем коде только прямые слеши, чтобы гарантировать корректную работу.

Совет

Класс String предлагает более десятка методов для работы со строками, представляющими пути к файлам:

Доступ к файлам в папке проекта (`res://`)

Godot считает, что проект существует в любой папке, содержащей текстовый файл project.godot, даже если этот файл пуст. Папка с этим файлом является корневой папкой вашего проекта.

Вы можете получить доступ к любому файлу относительно него, указав пути, начинающиеся с res://, что означает «resources». Например, доступ к файлу изображения character.png, расположенному в корневой папке проекта, можно получить в коде, используя следующий путь: res://character.png.

Доступ к постоянным данным пользователя (`user://`)

Чтобы хранить постоянные файлы данных, такие как сохранения или настройки игрока, вам нужно использовать префикс папки user:// вместо префикса папки res:// в качестве префикса пути. Это связано с тем, что во время работы игры файловая система проекта, скорее всего, будет доступна только для чтения.

Префикс user:// указывает на другой каталог на устройстве пользователя. В отличие от res://, каталог, на который указывает user://, создаётся автоматически и гарантированно доступен для записи, даже в экспортированном проекте.

Расположение папки user:// зависит от Project Settings:

По умолчанию папка user:// создаётся в каталоге Godot app_userdata/[project_name] в каталоге Godot editor data path. Это значение по умолчанию используется для того, чтобы прототипы и тестовые проекты оставались самостоятельными в папке Godot.
Если в настройках проекта включено application/config/use_custom_user_dir, папка user:// создается рядом с путем к данным редактора Godot, т. е. в стандартном месте для данных приложений.
- По умолчанию имя папки определяется из имени проекта, но его можно настроить с помощью application/config/custom_user_dir_name. Этот путь может содержать разделители, поэтому его можно использовать, например, для группировки проектов одной студии по структуре Название студии/Название игры.

На настольных платформах фактические пути к каталогам для user:// следующие:

Тип	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]`
Пользовательский каталог	Windows: `%APPDATA%\[project_name]` macOS: `~/Library/Application Support/[project_name]` Linux: `~/.local/share/[project_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. (Взаимодействие с основной файловой системой по-прежнему может осуществляться через синглтон JavaScriptBridge.)

Ведение журнала файлов

См. также

Документация по ведению журнала файлов перенесена в Ведение журнала.

Преобразование путей в абсолютные или "локальные" пути

Вы можете использовать ProjectSettings.globalize_path() для преобразования "локального" пути, например res://path/to/file.txt, в абсолютный путь ОС. Например, ProjectSettings.globalize_path() можно использовать для открытия "локальных" путей в файловом менеджере ОС с помощью OS.shell_open(), поскольку он принимает только собственные пути ОС.

Чтобы преобразовать абсолютный путь ОС в локальный, начинающийся с res:// или user://, используйте метод ProjectSettings.localize_path(). Это работает только для абсолютных путей, указывающих на файлы или папки в корневом каталоге проекта или в папках user://.

Пути данных редактора

Редактор использует разные пути для данных, настроек и кэша в зависимости от платформы. По умолчанию это следующие пути:

Тип	Location
Редактор данных	Windows: `%APPDATA%\Godot\` macOS: `~/Library/Application Support/Godot/` Linux: `~/.local/share/godot/`
Настройки редактора	Windows: `%APPDATA%\Godot\` macOS: `~/Library/Application Support/Godot/` Linux: `~/.config/godot/`
Кэш	Windows: `%TEMP%\Godot\` macOS: `~/Library/Caches/Godot/` Linux: `~/.cache/godot/`

Editor data содержат шаблоны экспорта и данные, специфичные для проекта.
Editor settings содержат основной файл конфигурации настроек редактора, а также различные другие пользовательские настройки (макеты редактора, профили функций, шаблоны сценариев и т. д.).
Cache содержит данные, сгенерированные редактором или временно сохранённые. Его можно безопасно удалить при закрытии Godot.

Godot соответствует спецификации XDG Base Directory Specification в Linux/*BSD. Вы можете переопределить переменные окружения XDG_DATA_HOME, XDG_CONFIG_HOME и XDG_CACHE_HOME, чтобы изменить пути к данным редактора и проекта.

Примечание

Если вы используете Godot, упакованный в виде Flatpak, пути к данным редактора будут расположены в подпапках ~/.var/app/ org.godotengine.Godot/.

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

Если вы создадите файл ._sc_ или _sc_ в том же каталоге, что и исполняемый файл редактора (или в MacOS/Contents/ для пакета .app редактора для macOS), Godot включит автономный режим. В этом режиме Godot будет записывать все данные редактора, настройки и кэш в каталог editor_data/, расположенный в том же каталоге, что и исполняемый файл редактора. Вы можете использовать его для создания переносимой установки редактора.

В версии Godot для Steam по умолчанию используется автономный режим.

Примечание

Автономный режим пока не поддерживается в экспортированных проектах. Для чтения и записи файлов относительно пути к исполняемому файлу используйте OS.get_executable_path(). Обратите внимание, что запись файлов в пути к исполняемому файлу работает только в том случае, если исполняемый файл находится в папке, доступной для записи (т.е. не Program Files или другой каталог, доступный только для чтения обычным пользователям).