ResourceLoader

继承： Object

用于加载资源文件的单例。

描述

用于从文件系统加载资源文件的单例。

会使用引擎中（内置或插件）注册的许多 ResourceFormatLoader 类将文件加载到内存中并将其转换为引擎可以使用的格式。

注意：你需要先将文件导入引擎，才能使用 load() 进行加载。如果你想在运行时加载 Image，可以使用 Image.load()。如果你想导入音频文件，可以使用 AudioStreamMP3.data 中描述的代码段。

注意：纯文本文件等非资源文件无法使用 ResourceLoader 读取。请改用 FileAccess 来处理这些文件，注意默认情况下不会导出非资源文件（导出说明见 FileAccess 类描述）。

教程

• Threaded Loading Demo

• 操作系统测试演示

方法

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 将会按照 load() 中的描述使用 ResourceFormatLoader。

对于用 GDScript 编写的 ResourceFormatLoader，此方法将隐式执行（详见 ResourceFormatLoader）。

---

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

返回给定路径 path 是否存在已识别的资源。

可选的 type_hint 可用于进一步指定 ResourceFormatLoader 应处理的 Resource 类型。任何继承自 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) 🔗

返回与一个给定资源路径关联的 ID，如果不存在此类 ID，则返回 -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，然后尝试加载。如果加载失败，则还会尝试其余的 ResourceFormatLoader。

可选的 type_hint 可用于进一步指定 ResourceFormatLoader 应处理的 Resource 类型。任何继承自 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) 🔗

更改缺少子资源时的行为。默认行为是中止加载。