Пути файлов в проектах 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 или другой каталог, доступный только для чтения обычным пользователям).