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 将会按照 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 的资源的依赖项。

注意：返回的单个依赖项是由 :: 分隔的切片。你可以使用 String.get_slice() 来获取每段的内容。

for dependency in ResourceLoader.get_dependencies(path):
    print(dependency.get_slice("::", 0)) # 输出 UID。
    print(dependency.get_slice("::", 2)) # 输出路径。

---

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

列出目录（例如“res://assets/enemies”），返回目录中包含的所有资源。资源文件为原始文件名，与导出前编辑器中所显示的名称一致。

---

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

在给定的 path 中加载资源，并将结果缓存以供进一步访问。

按顺序查询注册的 ResourceFormatLoader，以找到可以处理文件扩展名的第一个 ResourceFormatLoader，然后尝试加载。如果加载失败，则还会尝试其余的 ResourceFormatLoader。

可选的 type_hint 可用于进一步指定 ResourceFormatLoader 应处理的 Resource 类型。任何继承自 Resource 的东西都可以用作类型提示，例如 Image。

cache_mode 属性定义在加载资源时是否以及如何使用或更新缓存。详见 CacheMode。

如果没有 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 处启动的线程加载操作的状态。可能的返回值见 ThreadLoadStatus。

还可以通过 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 属性定义在加载资源时是否以及如何使用或更新缓存。详见 CacheMode。

---

void remove_resource_format_loader(format_loader: ResourceFormatLoader) 🔗

取消注册给定的 ResourceFormatLoader。

---

void set_abort_on_missing_resources(abort: bool) 🔗

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