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) 🔗

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