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

Статус на сервери 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) 🔗

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