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...

ResourceLoader

Наследует: Object

Синглтон для загрузки файлов ресурсов.

Описание

Одиночный объект, используемый для загрузки файлов ресурсов из файловой системы.

Он использует множество классов ResourceFormatLoader, зарегистрированных в движке (встроенных или из плагина), для загрузки файлов в память и преобразования их в формат, который может использоваться движком.

Примечание: Сначала необходимо импортировать файлы в движок, чтобы загрузить их с помощью load(). Если вы хотите загрузить Image во время выполнения, вы можете использовать Image.load(). Если вы хотите импортировать аудиофайлы, вы можете использовать фрагмент, описанный в AudioStreamMP3.data.

Примечание: Нересурсные файлы, такие как текстовые файлы, нельзя прочитать с помощью ResourceLoader. Вместо этого используйте FileAccess для этих файлов и имейте в виду, что нересурсные файлы по умолчанию не экспортируются (см. примечания в описании класса FileAccess для получения инструкций по их экспорту).

Обучающие материалы

Методы

void	add_resource_format_loader(format_loader: ResourceFormatLoader, at_front: bool = false)
bool	exists(path: String, type_hint: String = "")
Resource	get_cached_ref(path: String)
PackedStringArray	get_dependencies(path: String)
PackedStringArray	get_recognized_extensions_for_type(type: String)
int	get_resource_uid(path: String)
bool	has_cached(path: String)
PackedStringArray	list_directory(directory_path: String)
Resource	load(path: String, type_hint: String = "", cache_mode: CacheMode = 1)
Resource	load_threaded_get(path: String)
ThreadLoadStatus	load_threaded_get_status(path: String, progress: Array = [])
Error	load_threaded_request(path: String, type_hint: String = "", use_sub_threads: bool = false, cache_mode: CacheMode = 1)
void	remove_resource_format_loader(format_loader: ResourceFormatLoader)
void	set_abort_on_missing_resources(abort: bool)

Перечисления

enum ThreadLoadStatus: 🔗

ThreadLoadStatus THREAD_LOAD_INVALID_RESOURCE = 0

Ресурс недействителен или не был загружен с помощью load_threaded_request().

ThreadLoadStatus THREAD_LOAD_IN_PROGRESS = 1

Ресурс все еще загружается.

ThreadLoadStatus THREAD_LOAD_FAILED = 2

Вас постигла неудача, во время загрузки произошла ошибка.

ThreadLoadStatus THREAD_LOAD_LOADED = 3

Ресурс успешно загружен и к нему можно получить доступ через load_threaded_get().

enum CacheMode: 🔗

CacheMode CACHE_MODE_IGNORE = 0

Ни основной ресурс (тот, который был запрошен для загрузки), ни какой-либо из его подресурсов не извлекается из кэша и не сохраняется в нем. Зависимости (внешние ресурсы) загружаются с CACHE_MODE_REUSE.

CacheMode CACHE_MODE_REUSE = 1

Основной ресурс (тот, который был запрошен для загрузки), его подресурсы и его зависимости (внешние ресурсы) извлекаются из кэша, если они присутствуют, а не загружаются. Те, которые не кэшируются, загружаются и затем сохраняются в кэше. Те же правила рекурсивно распространяются вниз по дереву зависимостей (внешние ресурсы).

CacheMode CACHE_MODE_REPLACE = 2

Как CACHE_MODE_REUSE, но кэш проверяется для основного ресурса (того, который запрашивается для загрузки), а также для каждого из его подресурсов. Те, которые уже находятся в кэше, пока загруженные и кэшированные типы совпадают, обновляют свои данные из хранилища в уже существующие экземпляры. В противном случае они воссоздаются как совершенно новые объекты.

CacheMode CACHE_MODE_IGNORE_DEEP = 3

Подобно CACHE_MODE_IGNORE, но распространяется рекурсивно вниз по дереву зависимостей (внешние ресурсы).

CacheMode CACHE_MODE_REPLACE_DEEP = 4

Подобно CACHE_MODE_REPLACE, но распространяется рекурсивно вниз по дереву зависимостей (внешние ресурсы).

Описания метода

void add_resource_format_loader(format_loader: ResourceFormatLoader, at_front: bool = false) 🔗

Регистрирует новый ResourceFormatLoader. ResourceLoader будет использовать ResourceFormatLoader, как описано в load().

Этот метод выполняется неявно для ResourceFormatLoaders, написанных на GDScript (см. ResourceFormatLoader для получения дополнительной информации).

bool exists(path: String, type_hint: String = "") 🔗

Возвращает, существует ли распознанный ресурс для указанного path.

Необязательный type_hint может использоваться для дальнейшего указания типа Resource, который должен обрабатываться ResourceFormatLoader. Все, что наследуется от Resource, может использоваться как подсказка типа, например Image.

Примечание: Если вы используете Resource.take_over_path(), этот метод вернет true для принятого пути, даже если ресурс не был сохранен (т. е. существует только в кэше ресурсов).

Resource get_cached_ref(path: String) 🔗

Возвращает ссылку на кэшированный ресурс для указанного path.

Примечание: Если ресурс не кэширован, возвращаемый Resource будет недействительным.

PackedStringArray get_dependencies(path: String) 🔗

Возвращает зависимости для ресурса по указанному path.

Каждая зависимость — это строка, которую можно разделить на секции с помощью ::. Секция может быть одна или три, при этом вторая секция всегда пуста. Если секция одна, она содержит путь к файлу. Если секции три, первая секция содержит UID, а третья — резервный путь.

for dependency in ResourceLoader.get_dependencies(path):
    if dependency.contains("::"):
        print(dependency.get_slice("::", 0)) # Печатает UID.
        print(dependency.get_slice("::", 2)) # Печатает резервный путь.
    else:
        print(dependency) # Печатает путь.

PackedStringArray get_recognized_extensions_for_type(type: String) 🔗

Возвращает список распознанных расширений для типа ресурса.

int get_resource_uid(path: String) 🔗

Возвращает идентификатор, связанный с указанным путем к ресурсу, или -1, если такой идентификатор не существует.

bool has_cached(path: String) 🔗

Возвращает, доступен ли кэшированный ресурс для указанного path.

После загрузки ресурса движком он кэшируется в памяти для более быстрого доступа, и будущие вызовы метода load() будут использовать кэшированную версию. Кэшированный ресурс можно переопределить, используя Resource.take_over_path() для нового ресурса для того же пути.

PackedStringArray list_directory(directory_path: String) 🔗

Перечисляет каталог, возвращая все ресурсы и подкаталоги, содержащиеся в нем. Файлы ресурсов имеют исходные имена файлов, которые видны в редакторе перед экспортом. К каталогам добавлены "/".

# Выводит ["extra_data/", "model.gltf", "model.tscn", "model_slime.png"]
print(ResourceLoader.list_directory("res://assets/enemies/slime"))

Примечание: Порядок файлов и каталогов, возвращаемых этим методом, не является детерминированным и может различаться в зависимости от операционной системы.

Примечание: Чтобы нормально пройти по файловой системе, см. DirAccess.

Resource load(path: String, type_hint: String = "", cache_mode: CacheMode = 1) 🔗

Загружает ресурс по указанному path, кэшируя результат для дальнейшего доступа.

Зарегистрированные ResourceFormatLoader запрашиваются последовательно, чтобы найти первый, который может обработать расширение файла, а затем пытаются загрузить. Если загрузка не удалась, также пытаются загрузить оставшиеся ResourceFormatLoader.

Необязательный type_hint может использоваться для дальнейшего указания типа Resource, который должен обрабатываться ResourceFormatLoader. Все, что наследуется от Resource, может использоваться в качестве подсказки типа, например Image.

Свойство cache_mode определяет, следует ли и как использовать или обновлять кэш при загрузке ресурса.

Возвращает пустой ресурс, если ни один ResourceFormatLoader не может обработать файл, и выводит ошибку, если файл не найден по указанному пути.

GDScript имеет упрощенный встроенный метод @GDScript.load(), который можно использовать в большинстве ситуаций, оставляя использование ResourceLoader для более сложных сценариев.

Примечание: Если ProjectSettings.editor/export/convert_text_resources_to_binary имеет значение true, @GDScript.load() не сможет прочитать преобразованные файлы в экспортированном проекте. Если вы полагаетесь на загрузку файлов, присутствующих в PCK, во время выполнения, установите ProjectSettings.editor/export/convert_text_resources_to_binary на false.

Примечание: Относительные пути будут иметь префикс "res://" перед загрузкой, чтобы избежать непредвиденных результатов, убедитесь, что ваши пути абсолютные.

Resource load_threaded_get(path: String) 🔗

Возвращает ресурс, загруженный load_threaded_request().

Если это вызывается до завершения потока загрузки (т. е. load_threaded_get_status() не является THREAD_LOAD_LOADED), вызывающий поток будет заблокирован до тех пор, пока ресурс не завершит загрузку. Однако рекомендуется использовать load_threaded_get_status(), чтобы узнать, когда загрузка фактически завершена.

ThreadLoadStatus load_threaded_get_status(path: String, progress: Array = []) 🔗

Возвращает статус операции потоковой загрузки, запущенной с помощью load_threaded_request() для ресурса в path.

Переменная массива может быть дополнительно передана через progress и вернет одноэлементный массив, содержащий отношение завершения потоковой загрузки (между 0.0 и 1.0).

Примечание: Рекомендуемый способ использования этого метода — вызывать его во время разных кадров (например, в Node._process(), а не в цикле).

Error load_threaded_request(path: String, type_hint: String = "", use_sub_threads: bool = false, cache_mode: CacheMode = 1) 🔗

Загружает ресурс с помощью потоков. Если use_sub_threads равен true, для загрузки ресурса будет использоваться несколько потоков, что ускоряет загрузку, но может повлиять на основной поток (и, таким образом, вызвать замедление игры).

Параметр cache_mode определяет, следует ли и как использовать или обновлять кэш при загрузке ресурса.

void remove_resource_format_loader(format_loader: ResourceFormatLoader) 🔗

Отменяет регистрацию указанного ResourceFormatLoader.

void set_abort_on_missing_resources(abort: bool) 🔗

Изменяет поведение при отсутствии подресурсов. Поведение по умолчанию — прерывание загрузки.