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

Статус на сервери ResourceLoader буде використовувати ResourceFormatLoader як описано в методичне навантаження.

Цей метод виконується непомітно для ResourceFormatLoaders, написаних в GDScript (див. ResourceFormatLoader для отримання додаткової інформації).

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

Повертає, чи існує визнаний ресурс для вказаного пам'ятний шлях.

Додатковий 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, коли не існує такого ID.

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

Зміни поведінки на відсутніх субресурсах. Поведінка за замовчуванням полягає в скороченні навантаження.